developing-in-lightdash

name: developing-in-lightdash description: Use when reading, creating, and editing Lightdash dashboards and charts as JSON, including dashboard layout and chart-type-specific configuration.

Developing in Lightdash

Use this skill when working with Lightdash dashboards and charts.

What You Can Do

Rules:

• Always read content before editing if you have not read it since the last user message.
• Preserve unrelated fields.
• Prefer minimal patches.
• Follow the dashboard or chart shape from the resource instead of inventing structure.
• When you create or edit content, please provide links for them in the final response

Common Mistakes

Core Workflows

Edit Dashboards

1. Call readContent and inspect the current JSON shape.
2. Always read the dashboard-reference resource.
3. Build the smallest possible JSON Patch.
4. Call editContent with that patch.
5. Re-read if needed to verify the final state.

Edit Charts and Dashboard Tiles

1. Call readContent for the chart slug.
2. Always read the chart reference for chart type (see Choosing the Right Chart Type below).
3. If you add or change filters, verify exact filter values before patching.
4. If you change the chart's name or purpose, also update dashboards that reference that chart.
5. Build the smallest possible JSON Patch.
6. If you changed the chart's metricQuery, call runContentQuery with source.type: "metricQuery" and the edited chart's tableName/metricQuery.
7. Call editContent with that patch.
8. Re-read if needed to verify the final state.

Create Charts

1. Use discoverFields to explore available fields and plan your chart.
2. Always read the chart reference for chart type (see Choosing the Right Chart Type below) to understand required fields and configuration.
3. Build the full chart JSON with that metric query and other required fields.
4. Call runContentQuery with source.type: "metricQuery" and the chart's tableName/metricQuery.
5. Call createContent with the verified chart JSON.

Create Dashboards

1. Always read the dashboard-reference and dashboard-best-practices resources.
2. Explore existing dashboards and charts to find reusable content and inspiration for layout and design.
3. Use discoverFields to explore available fields and plan which charts to include.
4. Create an empty dashboard shell first.
5. Start building charts and adding them to the dashboard one by one, using the workflow above for creating charts.

Editing Charts

Dashboard tiles have their own titles. A saved_chart tile's title and chartName are independent overrides and do not automatically change when a chart is renamed. If you change a chart from "Total Revenue" to "Gross Profit", update the dashboard tile too.

{
    "tiles": [
        {
            "properties": {
                "chartName": "Gross Profit",
                "chartSlug": "total-revenue-kpi",
                "title": "Gross Profit"
            },
            "type": "saved_chart"
        }
    ]
}

Slug Fields

slug is a read-only stable identifier.

Dashboards

• spaceSlug is the dashboard's space path. Changing it moves the dashboard to another space.
• Dashboard tile properties.chartSlug references an existing reusable or dashboard-owned chart.

Charts

Charts are either reusable space charts or dashboard-owned charts.

• Reusable chart: no dashboardSlug; spaceSlug is its space path and changing it moves the chart.
• Dashboard-owned chart: has dashboardSlug; both dashboardSlug and spaceSlug are read-only, and spaceSlug is the owning dashboard's space.

Chart Types

All charts share a common base structure:

{
    "chartConfig": {
        "config": {},
        "type": "<type>"
    },
    "contentType": "chart",
    "dashboardSlug": "my-dashboard",
    "metricQuery": {
        "dimensions": ["my_explore_category"],
        "exploreName": "my_explore",
        "filters": {},
        "limit": 500,
        "metrics": ["my_explore_total_sales"],
        "sorts": []
    },
    "name": "Chart Name",
    "slug": "unique-chart-slug",
    "spaceSlug": "target-space",
    "tableConfig": {
        "columnOrder": []
    },
    "tableName": "my_explore",
    "version": 1
}

Spaces can be nested. Use parent/child syntax in spaceSlug for sub-spaces, for example "sales/forecasts". A bare slug like "sales-forecasts" is a flat top-level space; the slash defines the hierarchy.

Choosing the Right Chart Type

For period comparisons, read period-over-period-reference in addition to the chart type reference.

Resources

Charts

• cartesian-chart-reference - Bar, line, area, scatter
• pie-chart-reference - Parts of whole
• table-chart-reference - Data tables
• big-number-chart-reference - KPIs
• funnel-chart-reference - Conversion funnels
• gauge-chart-reference - Progress indicators
• treemap-chart-reference - Hierarchical composition
• map-chart-reference - Geographic data
• sankey-chart-reference - Flow diagrams
• custom-viz-reference - Vega-Lite
• period-over-period-reference - PoP comparisons
• field-formatting-reference - Chart-level field formatting overrides for metrics and dimensions

Dashboards

• dashboard-reference - Dashboard structure, layout, tabs, tiles, and filters
• dashboard-best-practices - Dashboard design guidance