developing-in-lightdash

Developing in Lightdash

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)

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

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 Postgres to BigQuery), update it from your profiles.yml:

lightdash set-warehouse --project-dir ./dbt --profiles-dir ./profiles --assume-yes

This reads credentials from profiles.yml, updates the warehouse connection on the currently selected project, and triggers a recompile. Run this before lightdash deploy.

To target a specific project:

lightdash set-warehouse --project-dir ./dbt --profiles-dir ./profiles --project <uuid> --assume-yes

Core Workflows

Verify Filter Values Before Using Them

CRITICAL: Never guess filter values. Case mismatches (e.g., 'Payment' vs 'payment') cause charts to silently return no data.

Filters are case-sensitive by default. The case_sensitive key can override this in order of priority:

• Dimension metadata
• Model/explore metadata
• lightdash.config.yml defaults.case_sensitive

Before writing any string filter, query actual values from the warehouse:

lightdash sql "SELECT DISTINCT category FROM payments LIMIT 50" -o category_values.csv

Read the CSV and use the exact values in your filter YAML. This applies to all equals/notEquals filters with string values — in charts and dashboards.

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.

Creating a Pure Lightdash Project from a Warehouse Catalog

When the prepared project has no usable dbt project and the task is to bootstrap a semantic layer from warehouse metadata, always read and follow Creating from a Warehouse Catalog before inspecting data or writing YAML. This applies whether warehouse access comes from the selected Lightdash project or an already-authenticated warehouse CLI such as Snowflake CLI or bq. Do not use that workflow when an existing dbt semantic layer can be extended.

Editing Charts

1. Download: `lig

Content truncated.