shield_lock
JinDaGe
← Back to skills
extension
Category: Marketing & GrowthNo API key required

developing-in-lightdash

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.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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

Charts

Dashboards & Workflows

External