Developing in Lightdash

Build and deploy Lightdash analytics projects. This skill covers the semantic layer (metrics, dimensions, joins) and content (charts, dashboards).

What You Can Do

| 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 |

Before You Start

Check Your Target Project

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"

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: | | 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"

Syntax Comparison

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

Core Workflows

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 and Dimensions Reference for configuration options.

Editing Charts

1. Download: lightdash download --charts chart-slug
2. Edit the YAML file in lightdash/ directory
3. Upload: lightdash upload --charts chart-slug

Editing Dashboards

1. Download: lightdash download --dashboards dashboard-slug
2. Edit the YAML file in lightdash/ directory
3. Upload: lightdash upload --dashboards dashboard-slug

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 upload to sync changes

Testing with Preview

For larger changes, test in isolation:

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 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.

Semantic Layer Overview

The semantic layer defines your data model: what can be queried and how.

Tables (Explores)

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.

Metrics

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.

Dimensions

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.

Joins

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.

Chart Types

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

Dashboards arrange charts and content in a grid layout. See Dashboard Reference for YAML structure, tile types, tabs, and filters.

Exploring the Warehouse

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

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 for detailed examples and CI/CD configurations.

Resources

Semantic Layer

• Dimensions Reference
• Metrics Reference
• Tables Reference
• Joins Reference

Charts

• Cartesian Chart Reference - Bar, line, area, scatter
• Pie Chart Reference
• Table Chart Reference
• Big Number Reference
• Funnel Chart Reference
• Gauge Chart Reference
• Treemap Chart Reference
• Map Chart Reference
• Custom Viz Reference

Dashboards & Workflows

• Dashboard Reference
• Dashboard Best Practices
• CLI Reference
• Workflows Reference

External

• Lightdash Docs