// Build, configure, and deploy Lightdash analytics projects. Supports both dbt projects with embedded Lightdash metadata and pure Lightdash YAML projects without dbt. Create metrics, dimensions, charts, and dashboards using the Lightdash CLI.
| name | developing-in-lightdash |
| description | Build, configure, and deploy Lightdash analytics projects. Supports both dbt projects with embedded Lightdash metadata and pure Lightdash YAML projects without dbt. Create metrics, dimensions, charts, and dashboards using the Lightdash CLI. |
Build and deploy Lightdash analytics projects. This skill covers the semantic layer (metrics, dimensions, joins) and content (charts, dashboards).
| 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 |
| Build dashboards | lightdash download, edit YAML, lightdash upload | Dashboard Reference |
| Lint yaml files | lightdash lint | CLI Reference |
| Deploy changes | lightdash deploy (semantic layer), lightdash upload (content) | CLI Reference |
| Test changes | lightdash preview | Workflows |
Always verify which project you're deploying to. Deploying to the wrong project can overwrite production content.
# Check current project
lightdash config get-project
# List available projects
lightdash config list-projects
# Switch to correct project
lightdash config set-project --name "My Project"
The YAML syntax differs significantly between project types.
| Type | Detection | Key Difference |
|---|---|---|
| dbt Project | Has dbt_project.yml | Metadata nested under meta: |
| Pure Lightdash | Has lightdash.config.yml, no dbt | Top-level properties |
# Quick detection
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 YAML (metadata under meta:):
models:
- name: orders
meta:
metrics:
total_revenue:
type: sum
sql: "${TABLE}.amount"
columns:
- name: status
meta:
dimension:
type: string
Pure Lightdash YAML (top-level):
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
models/*.yml, pure Lightdash: lightdash/models/*.yml)lightdash lint (pure Lightdash) or dbt compile (dbt projects)lightdash deploySee Metrics Reference and Dimensions Reference for configuration options.
lightdash download --charts chart-sluglightdash/ directorylightdash upload --charts chart-sluglightdash download --dashboards dashboard-sluglightdash/ directorylightdash upload --dashboards dashboard-slugCharts and dashboards are typically created in the UI first, then managed as code:
lightdash download to pull as YAMLlightdash upload to sync changesFor larger changes, test in isolation:
lightdash preview --name "my-feature"
# Make changes and iterate
lightdash stop-preview --name "my-feature"
| 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 sql "..." -o file.csv | Run SQL queries against warehouse |
lightdash run-chart -p chart.yml | Execute chart YAML query against warehouse |
See CLI Reference for full command documentation.
The semantic layer defines your data model: what can be queried and how.
Tables are dbt models or Lightdash YAML models that define queryable entities.
# dbt example
models:
- name: orders
meta:
label: "Orders"
joins:
- join: customers
sql_on: "${orders.customer_id} = ${customers.customer_id}"
See Tables Reference for all options.
Aggregated calculations (sum, count, average, etc.) on your data.
metrics:
total_revenue:
type: sum
sql: "${TABLE}.amount"
format: "usd"
Common types: count, count_distinct, sum, average, min, max, number (custom SQL)
See Metrics Reference for all types and options.
Attributes for grouping and filtering data.
columns:
- name: created_at
meta:
dimension:
type: timestamp
time_intervals: [DAY, WEEK, MONTH, YEAR]
Types: string, number, boolean, date, timestamp
See Dimensions Reference for all options including time intervals.
Connect related tables for cross-table analysis.
joins:
- join: customers
sql_on: "${orders.customer_id} = ${customers.customer_id}"
type: left
See Joins Reference for configuration options.
Lightdash supports 9 chart types. Each has a dedicated reference:
| Type | Use Case | Reference |
|---|---|---|
cartesian | Bar, line, area, scatter | Cartesian |
pie | Parts of whole | Pie |
table | Data tables | Table |
big_number | KPIs | Big Number |
funnel | Conversion funnels | Funnel |
gauge | Progress indicators | Gauge |
treemap | Hierarchical data | Treemap |
map | Geographic data | Map |
custom | Vega-Lite | Custom Viz |
See individual chart type references for YAML structure and configuration options.
Dashboards arrange charts and content in a grid layout. See Dashboard Reference for YAML structure, tile types, tabs, and filters.
Use lightdash sql to explore data when building models:
# 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
| Pattern | When to Use |
|---|---|
Direct (deploy + upload) | Solo dev, rapid iteration |
| Preview-First | Team, complex changes |
| CI/CD | Automated on merge |
See Workflows Reference for detailed examples and CI/CD configurations.