Use when working with Lightdash YAML files, dbt models with Lightdash metadata, the lightdash CLI (deploy, upload, download, preview, lint, sql, set-warehouse), or creating/editing charts, dashboards, metrics, and dimensions as code
Build and deploy Lightdash analytics projects. This skill covers the semantic layer (metrics, dimensions, joins) and content (charts, dashboards).
lightdash CLI (deploy, upload, download, preview, lint, sql)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.
| Task | Commands | References |
|---|---|---|
| Explore data warehouse | lightdash sql to execute raw sql, read .csv results |
| CLI Reference |
| Define metrics & dimensions | Edit dbt YAML or Lightdash YAML | Metrics, Dimensions |
| Create charts | lightdash download, edit YAML, lightdash upload | Chart Types |
| Add period comparisons | Add PoP additional metrics to chart YAML | Period over Period |
| Build dashboards | lightdash download, edit YAML, lightdash upload | Dashboard Reference |
| Lint yaml files | lightdash lint | CLI Reference |
| Set warehouse connection | lightdash set-warehouse from profiles.yml | CLI Reference |
| Deploy changes | lightdash deploy (semantic layer), lightdash upload (content) | CLI Reference |
| Test changes | lightdash preview | Workflows |
| 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 |
Always verify which project you're deploying to. Deploying to the wrong project can overwrite production content.
lightdash config get-project # Show current project
lightdash config list-projects # List available projects
lightdash config set-project --name "My Project" # Switch project
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 |
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 ofmeta:. The properties are identical — only the nesting changes. Example:models: - name: orders config: meta: metrics: total_revenue: type: sum sql: "${TABLE}.amount"
dbt YAML (metadata under meta:):