Skip to main content
ZICQ

Skills ZICQ category:DevOps & Cloud developing-in-lightdash

Developing In Lightdash

Use when working with Lightdash YAML files, dbt models with Lightdash metadata, the lightdash CLI (deploy, upload, download, preview, lint, warehouse-catalog, sql, set-warehouse, apps create/preview/validate), or managing charts, dashboards, spaces and access, AI agents, scheduled content, data apps, custom chart types (Chart Studio, `apps create --chart-type`, `--chart-types`), organization Data App themes, data-app external connections, users, groups, custom roles, metrics, and dimensions as code

428 installs

Official URL:skills.sh

What this skill does

Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.

What it does

Use when working with Lightdash YAML files, dbt models with Lightdash metadata, the lightdash CLI (deploy, upload, download, preview, lint, warehouse-catalog, sql, set-warehouse, apps create/preview/validate), or managing charts, dashboards, spaces and access, AI agents, scheduled content, data apps, custom chart types (Chart Studio, `apps create --chart-type`, `--chart-types`), organization Data App themes, data-app external connections, users, groups, custom roles, metrics, and dimensions as code

When to use it

- Working with Lightdash YAML files (charts, dashboards, models as code)

How agents load it

Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: Developing in Lightdash; When to Use; What You Can Do; Common Mistakes; Before You Start; Check Your Target Project. It includes spec-recommended sections: step-by-step instructions.

File analysis

File analysis: instruction-only skill (SKILL.md). The agent loads the full body when activated.

Developing in LightdashWhen to UseWhat You Can DoCommon MistakesBefore You StartCheck Your Target ProjectDetect Your Project TypeSyntax ComparisonSetting Up Warehouse ConnectionCore WorkflowsVerify Filter Values Before Using ThemEditing Metrics & Dimensions

Source category:skills.sh agent-skill

SKILL.md & Agent activation

Official spec ↗
name
developing-in-lightdash
description
Use when working with Lightdash YAML files, dbt models with Lightdash metadata, the lightdash CLI (deploy, upload, download, preview, lint, warehouse-catalog, sql, set-warehouse, apps create/preview/validate), or managing charts, dashboards, spaces and access, AI agents, scheduled content, data apps, custom chart types (Chart Studio, `apps create --chart-type`, `--chart-types`), organization Data App themes, data-app external connections, users, groups, custom roles, metrics, and dimensions as code
  1. DiscoverThe client exposes names and descriptions to the agent.
  2. ActivateYour request or the task context selects the skill and loads its instructions.
  3. Load resourcesReferenced scripts, documentation and assets are used when needed.

Invocation syntax and available tools depend on your Agent client. Client integration guide ↗

Install this skill

Skills CLI ↗

Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.

Ask your Agent to install

Copy these instructions to a compatible agent and confirm the target directory matches your client.

Install the agent skill "developing-in-lightdash" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-48d671b9da2ebb77-Developing-In-Lightdash.html
Save it as .cursor/skills/developing-in-lightdash/SKILL.md or .claude/skills/developing-in-lightdash/SKILL.md and keep the frontmatter name and description exactly as-is.

Full package on GitHub ↗

Install from the terminal · Skills CLI

Requires Node.js and npx. First inspect the repository's skill list to confirm the name.

npx skills add 'https://github.com/lightdash/lightdash' --list

npx skills add 'https://github.com/lightdash/lightdash' --skill 'developing-in-lightdash'

The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.

Readable layout
--- name: developing-in-lightdash description: Use when working with Lightdash YAML files, dbt models with Lightdash metadata, the lightdash CLI (deploy, upload, download, preview, lint, warehouse-catalog, sql, set-warehouse, apps create/preview/validate), or managing charts, dashboards, spaces and access, AI agents, scheduled content, data apps, custom chart types (Chart Studio, `apps create --chart-type`, `--chart-types`), organization Data App themes, data-app external connections, users, groups, custom roles, metrics, and dimensions as code --- # Developing in Lightdash For CLI users and writeback sandboxes working with YAML and dbt files. Build and deploy Lightdash analytics projects. This skill covers the **semantic layer** (metrics, dimensions, joins) and **content** (charts, dashboards). ## When to Use - Working with Lightdash YAML files (charts, dashboards, models as code) - Using the `lightdash` CLI (`deploy`, `upload`, `download`, `preview`, `lint`, `warehouse-catalog`, `sql`) - Defining metrics, dimensions, joins, or tables in dbt or pure Lightdash projects - Creating or editing charts and dashboards as code - Downloading, uploading, or locally developing data apps (enterprise) - Creating, downloading, editing, or uploading custom chart types built in Chart Studio (enterprise) - Creating, editing, migrating, downloading, or uploading organization Data App themes **Don't use for:** Developing the Lightdash application itself (use the codebase CLAUDE.md), general dbt work without Lightdash metadata, or raw SQL unrelated to Lightdash models. ## What You Can Do | Task | Commands | References | |------|----------|------------| | Create a pure Lightdash project from warehouse metadata | Use Lightdash or an already-authenticated warehouse CLI to inspect catalog metadata and aggregate profiles | [Creating from a Warehouse Catalog](./resources/creating-from-warehouse-catalog.md) | | Discover warehouse tables and fields | `lightdash warehouse-catalog --json` | [CLI Reference](./resources/cli-reference.md) | | Explore data warehouse values | `lightdash sql` to execute raw sql, read .csv results | [CLI Reference](./resources/cli-reference.md) | | Define metrics & dimensions | Edit dbt YAML or Lightdash YAML | [Metrics](./resources/metrics-reference.md), [Dimensions](./resources/dimensions-reference.md) | | Create charts | `lightdash download`, edit YAML, `lightdash upload` | [Chart Types](#chart-types) | | Add period comparisons | Add PoP additional metrics to chart YAML | [Period over Period](./resources/period-over-period-reference.md) | | Build dashboards | `lightdash download`, edit YAML, `lightdash upload` | [Dashboard Reference](./resources/dashboard-reference.md) | | Manage content as code across project and organization resources | `lightdash download`, `lightdash upload` | [Content as Code](./resources/content-as-code-reference.md) | | Manage data apps as code (enterprise) | `lightdash download --apps ` (one app) or `--include-apps` (all), edit bundle, `lightdash upload --apps `; local dev via `lightdash apps create/preview/validate` | [Data Apps](#working-with-data-apps-enterprise), [Content as Code](./resources/content-as-code-reference.md) | | Build or edit a custom chart type (enterprise) | `lightdash apps create "" --chart-type` or `lightdash download --chart-types `, edit `chart-types//src/`, `lightdash upload --chart-types ` | [Custom Chart Types](#working-with-custom-chart-types-enterprise) | | Manage organization Data App themes as code | `lightdash download --organization`, edit `themes//`, `lightdash upload --organization` | [Data App Themes](./resources/data-app-themes-reference.md) | | Manage data-app external connections (enterprise) | `lightdash download --include-external-connections`, edit YAML, `lightdash upload` | [Content as Code](./resources/content-as-code-reference.md) | | Lint yaml files | `lightdash lint` | [CLI Reference](./resources/cli-reference.md) | | Set warehouse connection | `lightdash set-warehouse` from profiles.yml | [CLI Reference](./resources/cli-reference.md) | | Deploy changes | `lightdash deploy` (semantic layer), `lightdash upload` (content) | [CLI Reference](./resources/cli-reference.md) | | Test changes | `lightdash preview` | [Workflows](./resources/workflows-reference.md) | ## Common Mistakes | Mistake | Consequence | Prevention | |---------|-------------|------------| | **Guessing filter values** | Case mismatches (`'Payment'` vs `'payment'`) cause charts to silently return no data | Always run `lightdash sql "SELECT DISTINCT column FROM table LIMIT 50" -o values.csv` and use exact values | | **Not updating dashboard tiles after renaming a chart** | Dashboard tile still shows old title — `title` and `chartName` are independent overrides that do NOT auto-update | Download the dashboard, find tiles with matching `chartSlug`, update `title` and `chartName` to match | | **Including unused dimensions in metricQuery** | "Results may be incorrect" warning — extra dimensions change SQL grouping and produce wrong numbers | Every dimension in `metricQuery.dimensions` must appear in the chart config. For cartesian: `layout.xField`, `layout.yField`, or `pivotConfig.columns` | | **Unsorted YAML keys** | `lightdash upload` warns "unsorted YAML keys" and diffs become noisy | Always sort keys alphabetically at every nesting level — the CLI writes with `sortKeys: true` | | **Deploying to wrong project** | Overwrites production content | Always run `lightdash config get-project` before deploying | | **Missing `contentType` field** | Content type can't be determined without relying on directory structure | Always include `contentType: chart`, `contentType: dashboard`, or `contentType: sql_chart` at the top level | | **Adding `--include-apps` to an `--apps ` selection** | `--include-apps` always requests ALL project apps (capped at 50), so the command downloads every app plus the ref — not just the one app | `--apps ` alone downloads/uploads only that app (by slug, app URL, or UUID). Use `--include-apps` only when you want every app | | **Editing a data app without reading its bundled skills** | App code violates the SDK-only data access and dependency boundaries (direct `fetch`, `pnpm add`, vendored libraries) and the upload rejects or the app breaks when deployed | Every app bundle ships the `developing-data-apps-locally` and `lightdash-data-app` skills — read them before editing files in an app folder (see [Data Apps](#working-with-data-apps-enterprise)) | | **Building a reusable chart as a Vega-Lite `custom` chart** | The visualization lives inside one saved chart and can't be reused or picked from the explorer's chart type picker | For a new reusable visualization, build a custom chart type (see [Custom Chart Types](#working-with-custom-chart-types-enterprise)). Use Vega-Lite only for existing `chartConfig.type: custom` charts or when the project has no custom chart types (enterprise) | | **Editing a chart type without reading its bundled skills** | The component queries or fetches data itself, or its `vizSchema` drifts from what `src/` reads, so the chart type breaks or never appears in the chart type picker | Every chart type folder ships `AGENTS.md` plus the `reusable-visualization` and `developing-chart-types-locally` skills — read all three before editing files in `chart-types//` | | **Inventing a theme-only CLI command or treating a missing folder as deletion** | The command does not exist, or a supposedly deleted remote theme returns on the next download | Use organization download/upload, and read [Data App Themes](./resources/data-app-themes-reference.md) before changing `themes/` | ## Before You Start When a task uses `lightdash download` or `lightdash upload`, especially for bulk edits, spaces and access, scheduled content, AI agents, data apps, custom chart types, organization themes, external connections, users, groups, or custom roles, **read and follow [Content as Code](./resources/content-as-code-reference.md) first**. Project and organization content require separate commands, and a default download is not a complete snapshot. For any task that creates, edits, migrates, downloads, uploads, or tests an organization Data App theme, **always read and follow [Data App Themes](./resources/data-app-themes-reference.md) before touching `themes/`**. Theme packages are strict multi-file resources, organization upload has no theme-only mode, and `lightdash lint` does not validate them. ### Check Your Target Project **Always verify which project you're deploying to.** Deploying to the wrong project can overwrite production content. ```bash lightdash config get-project # Show current project lightdash config list-projects # List available projects lightdash config set-project --name "My Project" # Switch project ``` ### Detect Your Project Type **The YAML syntax differs significantly between project types.** | Type | Detection | Key Difference | |------|-----------|----------------| | **dbt Project** | Has `dbt_project.yml` | Metadata nested under `meta:` | | **dbt Fusion / dbt 1.10+** | Has `dbt_project.yml`, uses dbt Fusion or dbt >= 1.10 | Metadata nested under `config: meta:` | | **Pure Lightdash** | Has `lightdash.config.yml`, no dbt | Top-level properties | ```bash ls dbt_project.yml 2>/dev/null && echo "dbt project" || echo "Not dbt" ls lightdash.config.yml 2>/dev/null && echo "Pure Lightdash" || echo "Not pure Lightdash" ``` > **dbt Fusion / dbt 1.10+:** Lightdash metadata must be nested under `config: meta:` instead of `meta:`. The properties are identical — only the nesting changes. Example: > ```yaml > models: > - name: orders > config: > meta: > metrics: > total_revenue: > type: sum > sql: "${TABLE}.amount" > ``` ### Syntax Comparison **dbt YAML** (metadata under `meta:`): ```yaml models: - name: orders meta: metrics: total_revenue: type: sum sql: "${TABLE}.amount" columns: - name: status meta: dimension: type: string ``` **Pure Lightdash YAML** (top-level): ```yaml type: model name: orders sql_from: 'DB.SCHEMA.ORDERS' metrics: total_revenue: type: sum sql: ${TABLE}.amount dimensions: - name: status sql: ${TABLE}.STATUS type: string ``` ## Setting Up Warehouse Connection If the project needs a different warehouse connection (e.g., switching from Postgres to BigQuery), update it from your profiles.yml: ```bash lightdash set-warehouse --project-dir ./dbt --profiles-dir ./profiles --assume-yes ``` This reads credentials from profiles.yml, updates the warehouse connection on the currently selected project, and triggers a recompile. Run this before `lightdash deploy`. To target a specific project: ```bash lightdash set-warehouse --project-dir ./dbt --profiles-dir ./profiles --project --assume-yes ``` ## Core Workflows ### Verify Filter Values Before Using Them **CRITICAL**: Never guess filter values. Case mismatches (e.g., `'Payment'` vs `'payment'`) cause charts to silently return no data. Filters are case-sensitive by default. The `case_sensitive` key can override this in order of priority: - Dimension metadata - Model/explore metadata - `lightdash.config.yml` `defaults.case_sensitive` **Before writing any string filter**, query actual values from the warehouse: ```bash lightdash sql "SELECT DISTINCT category FROM payments LIMIT 50" -o category_values.csv ``` Read the CSV and use the **exact values** in your filter YAML. This applies to all `equals`/`notEquals` filters with string values — in charts and dashboards. ### Editing Metrics & Dimensions 1. **Find the model YAML file** (dbt: `models/*.yml`, pure Lightdash: `lightdash/models/*.yml`) 2. **Edit metrics/dimensions** using the appropriate syntax for your project type 3. **Validate**: `lightdash lint` (pure Lightdash) or `dbt compile` (dbt projects) 4. **Deploy**: `lightdash deploy` See [Metrics Reference](./resources/metrics-reference.md) and [Dimensions Reference](./resources/dimensions-reference.md) for configuration options. ### Creating a Pure Lightdash Project from a Warehouse Catalog When the prepared project has no usable dbt project and the task is to bootstrap a semantic layer from warehouse metadata, **always read and follow [Creating from a Warehouse Catalog](./resources/creating-from-warehouse-catalog.md) before inspecting data or writing YAML**. This applies whether warehouse access comes from the selected Lightdash project or an already-authenticated warehouse CLI such as Snowflake CLI or `bq`. Do not use that workflow when an existing dbt semantic layer can be extended. ### Editing Charts 1. **Download**: `lightdash download --charts chart-slug` 2. **Edit** the YAML file in `lightdash/` directory 3. **Verify filter values**: If you added or changed filters, use `lightdash sql` to check actual column values (see [Common Mistakes](#common-mistakes)) 4. **Update dashboard tiles**: If you changed the chart's name or purpose, download any dashboards that reference it and update their tile `title` and `chartName` properties to match (see [Common Mistakes](#common-mistakes)) 5. **Lint**: `lightdash lint` to validate before uploading 6. **Upload**: `lightdash upload --charts chart-slug` (and any modified dashboards) **Dashboard tiles have their own titles.** A `saved_chart` tile's `title` and `chartName` properties are independent overrides — they do NOT auto-update when you rename the chart. If you change a chart from "Total Revenue" to "Gross Profit" but don't update the dashboard tile, the dashboard will still display "Total Revenue". Always download the dashboard, find tiles with matching `chartSlug`, and update their `title` and `chartName` to match. ```yaml # Dashboard tile — title and chartName must be updated manually when chart changes tiles: - type: saved_chart properties: chartSlug: total-revenue-kpi title: "Gross Profit" # ← Update this when chart name/purpose changes chartName: "Gross Profit" # ← Update this too ``` ### Editing Dashboards 1. **Download**: `lightdash download --dashboards dashboard-slug` 2. **Edit** the YAML file in `lightdash/` directory 3. **Verify filter values**: If you added or changed filters, use `lightdash sql` to check actual column values (see [Common Mistakes](#common-mistakes)) 4. **Lint**: `lightdash lint` to validate before uploading 5. **Upload**: `lightdash upload --dashboards dashboard-slug` ### Working with Data Apps (Enterprise) Data apps are multi-file React bundles under `apps//` with a `lightdash-app.yml` manifest — not single YAML files. Full flag semantics and manifest details: [Content as Code](./resources/content-as-code-reference.md). **Download one app** — `--apps ` alone is the complete command (ref = slug, app URL, or UUID; also finds apps not added to any space): ```bash lightdash download --apps revenue-explorer --path ./lightdash ``` Never add `--include-apps` to "scope" the download — it always requests ALL project apps (see [Common Mistakes](#common-mistakes)). **Download all apps**: `lightdash download --include-apps` (capped at 50; raise with `--apps-limit `). Add `--apps-only` to skip charts, dashboards, and spaces. **Upload**: ```bash lightdash upload --apps revenue-explorer # one app (slug = folder name, URL, or UUID) lightdash upload --include-apps # every app folder on disk ``` - `--app-space ` — space (slug or UUID) for apps this upload **creates**; existing apps keep their space. - `--create-new` — create a fresh app (new slug) instead of updating the app referenced in `lightdash-app.yml`. - `--allow-custom-dependencies` — required for non-interactive uploads of apps that declare custom npm dependencies. **Develop locally** with the `lightdash apps` subcommand group: ```bash lightdash apps create "Revenue Explorer" # scaffold a new app under ./lightdash/apps/ lightdash apps preview # run the app locally against your real Lightdash instance, authenticated as you lightdash apps validate # check source, manifest, dependencies, and semantic-layer references ``` **Every created or downloaded app bundle ships its own skills** inside the app folder: - `developing-data-apps-locally` — the edit → validate → upload loop, local preview, SDK-only data access, and dependency boundaries - `lightdash-data-app` — the `@lightdash/query-sdk` reference for the app's source code When editing files inside an app folder, **read those bundled skills first**. They are version-matched to the app and authoritative for local development — this skill only covers moving apps between disk and Lightdash. ### Working with Custom Chart Types (Enterprise) A custom chart type is a reusable visualization built in Chart Studio: one React component that Lightdash hands query results and settings to, offered in the explorer's chart type picker for every chart in the project. On disk it is a multi-file bundle under `chart-types//` with a `lightdash-app.yml` manifest whose `vizSchema` declares the fields and options the component reads. It is not a data app (it runs no query of its own) and not the legacy Vega-Lite `custom` chart. **Create one locally:** ```bash lightdash apps create "Radial Gauge" --chart-type # scaffolds ./lightdash/chart-types/radial-gauge/ ``` **Download** — `--chart-types ` alone is the complete command (ref = slug, URL, or UUID): ```bash lightdash download --chart-types radial-gauge --path ./lightdash lightdash download --include-chart-types # every chart type in the project (capped at 50; raise with --chart-types-limit ) lightdash download --chart-types-only # chart types only, skipping charts, dashboards, and spaces ``` Downloading a chart that renders with a custom chart type also downloads that chart type. In chart YAML the binding is `chartConfig.type: data_app_viz` with `config.dataAppVizSlug`, `fieldMapping`, and `optionValues`. **Upload:** ```bash lightdash upload --chart-types radial-gauge # one chart type (slug = folder name, URL, or UUID) lightdash upload --include-chart-types # every chart type folder on disk ``` A chart YAML that binds to a chart type by `dataAppVizSlug` fails to upload unless that chart type exists in the target project. Upload the chart type first, or pass `--chart-types ` in the same run (chart types upload before charts). **Edit inside the folder.** Change into `chart-types//` and **read its `AGENTS.md` plus the `reusable-visualization` and `developing-chart-types-locally` skills before touching `src/`**: - `reusable-visualization` — the component contract: `useVizContext()` is the only channel to the host, and the component never queries or fetches anything itself - `developing-chart-types-locally` — keeping `vizSchema` in lockstep with the component, `lightdash apps validate --build`, the fixture preview, and the upload-and-verify loop Those files are version-matched to the chart type and authoritative for editing it. This skill only covers moving chart types between disk and Lightdash. ### Working with Organization Data App Themes Organization Data App themes are multi-file packages under `themes//` and participate automatically in `lightdash download --organization` and `lightdash upload --organization`. They do not have a standalone command group or theme-specific selectors. Before creating, editing, migrating, synchronizing, or testing a theme, **read and follow [Data App Themes](./resources/data-app-themes-reference.md)** for the manifest contract, asset rules, synchronization behavior, and generation boundaries. ### Creating New Content Charts and dashboards are typically created in the UI first, then managed as code: 1. Create in UI 2. `lightdash download` to pull as YAML 3. Edit and version control 4. `lightdash lint` to validate before uploading 5. `lightdash upload` to sync changes ### Testing with Preview For larger changes, test in isolation: ```bash lightdash preview --name "my-feature" # Make changes and iterate lightdash stop-preview --name "my-feature" ``` ## CLI Quick Reference | Command | Purpose | |---------|---------| | `lightdash deploy` | Sync semantic layer (metrics, dimensions) | | `lightdash upload` | Upload charts/dashboards | | `lightdash download` | Download charts/dashboards as YAML | | `lightdash lint` | Validate YAML locally | | `lightdash preview` | Create temporary test project | | `lightdash warehouse-catalog --json` | Discover raw warehouse tables | | `lightdash sql "..." -o file.csv` | Run SQL queries against warehouse | | `lightdash run-chart -p chart.yml` | Execute chart YAML query against warehouse | | `lightdash apps create ` | Scaffold a new data app locally (enterprise) | | `lightdash apps create --chart-type` | Scaffold a new custom chart type locally (enterprise) | | `lightdash apps preview` | Run a data app locally against your Lightdash instance | | `lightdash apps validate` | Validate data app or chart type source, manifest, and semantic references | | `lightdash download --chart-types ` / `lightdash upload --chart-types ` | Move custom chart types between disk and Lightdash (enterprise) | See [CLI Reference](./resources/cli-reference.md) for full command documentation. ## Semantic Layer The semantic layer defines your data model. See individual references for full configuration: - [Tables Reference](./resources/tables-reference.md) — queryable entities, labels, joins - [Metrics Reference](./resources/metrics-reference.md) — aggregated calculations (`count`, `sum`, `average`, `min`, `max`, `number`, etc.) - [Dimensions Reference](./resources/dimensions-reference.md) — attributes for grouping/filtering (`string`, `number`, `boolean`, `date`, `timestamp`) - [Joins Reference](./resources/joins-reference.md) — cross-table relationships - [User Attributes Reference](./resources/user-attributes-reference.md) — SQL variables, row-level security, access control ## Chart Types All charts share a common base structure: ```yaml chartConfig: config: {} # Type-specific — see individual references type: contentType: chart # Required: chart, dashboard, or sql_chart dashboardSlug: my-dashboard # Optional: scopes chart to dashboard (won't appear in space) metricQuery: dimensions: - my_explore_category exploreName: my_explore # Required: which explore to query filters: {} limit: 500 metrics: - my_explore_total_sales sorts: [] name: "Chart Name" slug: unique-chart-slug spaceSlug: target-space tableConfig: columnOrder: [] tableName: my_explore # Required: top-level explore/table name version: 1 ``` **Key ordering:** All YAML keys must be sorted alphabetically at every nesting level. The CLI writes files with `sortKeys: true` and warns on upload if keys are unsorted. When writing or editing YAML by hand, keep keys in alphabetical order to avoid warnings and noisy diffs. **Chart scoping:** Use `spaceSlug` only for shared charts. Add `dashboardSlug` to scope a chart to a specific dashboard (it won't appear in the space). **Nested spaces:** Spaces can be nested. In YAML, `spaceSlug` uses `parent/child` syntax to address a sub-space — the `/` denotes hierarchy. Examples: ```yaml spaceSlug: sales # Top-level space "sales" spaceSlug: sales/maps # Sub-space "maps" inside "sales" spaceSlug: sales/eu/forecasts # Deeper nesting works the same way ``` Each path segment must be the slug of an existing (or to-be-created) space at that level. A bare slug like `sales-maps` is a flat top-level space, NOT a sub-space — the slash is the only thing that creates the hierarchy. ### Choosing the Right Chart Type | Data Pattern | Recommended Chart | Why | |--------------|-------------------|-----| | Trends over time | Line or area (`cartesian`) | Shows continuous change with time on X-axis | | Category comparisons | Bar (`cartesian`) | Easy visual comparison between discrete categories | | Part-of-whole relationships | `pie` or `treemap` | Shows proportions summing to 100% | | Single KPI metric | `big_number` | Focuses attention on one important value | | Conversion stages | `funnel` | Visualizes drop-off between sequential steps | | Progress toward target | `gauge` | Shows current value relative to goal | | Geographic data | `map` | Plots data points or regions on a map | | Flow between categories | `sankey` | Shows how values move from source to target nodes | | Detailed records | `table` | Displays raw data with sorting and formatting | | Visualization none of the above cover | Custom chart type | Reusable React component offered in the chart type picker — see [Custom Chart Types](#working-with-custom-chart-types-enterprise) | | Vega-Lite chart | `custom` (legacy) | For charts already saved with `chartConfig.type: custom`, or projects without custom chart types (enterprise) | | Type | Use Case | Reference | |------|----------|-----------| | `cartesian` | Bar, line, area, scatter | [Cartesian](./resources/cartesian-chart-reference.md) | | `pie` | Parts of whole | [Pie](./resources/pie-chart-reference.md) | | `table` | Data tables | [Table](./resources/table-chart-reference.md) | | `big_number` | KPIs | [Big Number](./resources/big-number-chart-reference.md) | | `funnel` | Conversion funnels | [Funnel](./resources/funnel-chart-reference.md) | | `gauge` | Progress indicators | [Gauge](./resources/gauge-chart-reference.md) | | `treemap` | Hierarchical data | [Treemap](./resources/treemap-chart-reference.md) | | `map` | Geographic data | [Map](./resources/map-chart-reference.md) | | `sankey` | Flow diagrams | [Sankey](./resources/sankey-chart-reference.md) | | `custom` | Legacy Vega-Lite custom chart | [Custom Viz](./resources/custom-viz-reference.md) | | `data_app_viz` | Chart rendered by a custom chart type | [Custom Chart Types](#working-with-custom-chart-types-enterprise) | ## Dashboards Dashboards arrange charts and content in a grid layout. See [Dashboard Reference](./resources/dashboard-reference.md) for YAML structure, tile types, tabs, and filters. ## Exploring the Warehouse Use `lightdash sql` to explore data when building models: ```bash # Preview table structure lightdash sql "SELECT * FROM orders LIMIT 5" -o preview.csv # Check distinct values for a dimension lightdash sql "SELECT DISTINCT status FROM orders" -o statuses.csv # Test metric calculations lightdash sql "SELECT SUM(amount) FROM orders" -o test.csv ``` ## Workflow Patterns | Pattern | When to Use | |---------|-------------| | **Direct** (`deploy` + `upload`) | Solo dev, rapid iteration | | **Preview-First** | Team, complex changes | | **CI/CD** | Automated on merge | See [Workflows Reference](./resources/workflows-reference.md) for detailed examples and CI/CD configurations. ## Resources ### Semantic Layer - [Creating from a Warehouse Catalog](./resources/creating-from-warehouse-catalog.md) - [Dimensions Reference](./resources/dimensions-reference.md) - [Metrics Reference](./resources/metrics-reference.md) - [Tables Reference](./resources/tables-reference.md) - [Joins Reference](./resources/joins-reference.md) - [User Attributes Reference](./resources/user-attributes-reference.md) ### Charts - [Cartesian Chart Reference](./resources/cartesian-chart-reference.md) - Bar, line, area, scatter - [Pie Chart Reference](./resources/pie-chart-reference.md) - [Table Chart Reference](./resources/table-chart-reference.md) - [Big Number Reference](./resources/big-number-chart-reference.md) - [Funnel Chart Reference](./resources/funnel-chart-reference.md) - [Gauge Chart Reference](./resources/gauge-chart-reference.md) - [Treemap Chart Reference](./resources/treemap-chart-reference.md) - [Map Chart Reference](./resources/map-chart-reference.md) - [Sankey Chart Reference](./resources/sankey-chart-reference.md) - [Custom Viz Reference](./resources/custom-viz-reference.md) - Legacy Vega-Lite `custom` charts - [Period over Period Reference](./resources/period-over-period-reference.md) - PoP comparisons (YoY, MoM, etc.) ### Dashboards & Workflows - [Dashboard Reference](./resources/dashboard-reference.md) - [Dashboard Best Practices](./resources/dashboard-best-practices.md) - [Data App Themes Reference](./resources/data-app-themes-reference.md) - [Content as Code Reference](./resources/content-as-code-reference.md) - [CLI Reference](./resources/cli-reference.md) - [Workflows Reference](./resources/workflows-reference.md) ### External - [Lightdash Docs](https://docs.lightdash.com)

Related skills

DevOps & Cloud

Docker Essentials

Essential Docker commands and workflows for container management, image operations, and debugging.

DevOps & Cloud

Find Skills

Discover and install skills from the open agent skills ecosystem. Use when: (1) user asks "how do I do X" where X might have an existing ski…

DevOps & Cloud

Microsoft Foundry

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd a…

DevOps & Cloud

Azure Deploy

Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT us…