developing-in-lightdash

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

Common Mistakes

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

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.

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:

models:
  - name: orders
    config:
      meta:
        metrics:
          total_revenue:
            type: sum
            sql: "${TABLE}.amount"

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

Setting Up Warehouse Connection

If the project needs a different warehouse connection (e.g., switching from Postgre

Content truncated.