Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt

Use this file to discover all available pages before exploring further.

​
What is Lightdash YAML?

Lightdash YAML allows you to use Lightdash without an existing dbt project. Instead of defining your semantic layer within dbt model YAML files, you define it directly in standalone YAML files that point to tables in your data warehouse. This approach lets you leverage Lightdash’s powerful features without needing to adopt dbt first.

​
Why use Lightdash YAML?

Lightdash has always operated with dbt at its core. Traditionally, customers have active dbt projects, and Lightdash builds its semantic layer within that dbt context. However, not every team uses dbt. If you’re interested in Lightdash features like:
  • AI agents that can answer questions about your data
  • A semantic layer with consistent metric definitions
  • Self-service analytics for your business users
…but you don’t have dbt set up, Lightdash YAML provides a path forward. You can define your semantic layer directly and start using Lightdash immediately, without the overhead of adopting dbt.

​
dbt vs Lightdash YAML: which should you use?

ScenarioRecommendation
You already have a dbt projectUse the standard dbt integration
You’re planning to adopt dbt soonConsider setting up dbt first, then connecting to Lightdash
You don’t use dbt and want to try Lightdash quicklyUse Lightdash YAML
You want AI agents or semantic layer features without dbtUse Lightdash YAML
You have tables in your warehouse ready to exploreUse Lightdash YAML
The good news: if you start with Lightdash YAML and later decide to adopt dbt, the YAML formats are compatible, so migration is straightforward. The fastest way to get started with Lightdash YAML is to let an AI coding agent (Claude Code, Cursor, etc.) do the heavy lifting for you.
1

Install the Lightdash CLI

Follow the CLI installation guide and authenticate with Lightdash.
2

Install Lightdash skills

Run lightdash install-skills to teach your coding agent everything it needs to know about building in Lightdash, from writing YAML models to creating metrics and deploying.
lightdash install-skills
3

Ask your agent to build your project

Prompt your coding agent to:
  • Create your lightdash.config.yml and YAML model files based on tables in your warehouse
  • Generate dimensions and metrics for those models
  • Deploy your project to Lightdash with lightdash deploy --create --no-warehouse-credentials
Example prompt:
/developing-in-lightdash Profile my warehouse, create Lightdash YAML
models for the users and orders tables with sensible metrics and
dimensions, then deploy the project to Lightdash.
Prefer to set things up manually? Follow the step-by-step guide below.

​
Getting started with Lightdash YAML

​
Prerequisites

Before you begin, make sure you have:
  1. The Lightdash CLI installed
  2. Authenticated with Lightdash
  3. Credentials for your data warehouse (e.g., Snowflake)
  4. Tables in your warehouse that you want to explore

​
Step 1: Create your project configuration

At the root of your project, create a lightdash.config.yml file to specify your warehouse type: 
warehouse:
  type: snowflake
Replace snowflake with your warehouse type (e.g., bigquery, databricks, redshift, postgres, trino).

​
Step 2: Create your first model

Lightdash YAML uses the same syntax as the Lightdash semantic layer in dbt, but instead of nesting everything under meta tags, all configuration is at the top level of the file. Create a directory structure for your Lightdash project: 
mkdir -p lightdash/models
Create a YAML file for your first model. For example, ./lightdash/models/users.yml: 
# Metadata
type: model
name: users

# Table definition
sql_from: 'DB.SCHEMA.USERS'

# Metric definitions
# For more configuration see: https://docs.lightdash.com/references/metrics
metrics:
  user_count:
    type: count_distinct
    sql: ${TABLE}.USER_ID
    description: Total unique users

# Dimension definitions
# For more configuration see: https://docs.lightdash.com/references/dimensions
dimensions:
  - name: subscription_type
    sql: ${TABLE}.SUBSCRIPTION
    type: string

  - name: signed_up_at
    sql: ${TABLE}.SIGNED_UP
    type: date
    time_intervals:
      - DAY
      - WEEK
      - MONTH
Update the configuration:
  • Set sql_from to the fully qualified name of your table (e.g., DATABASE.SCHEMA.TABLE)
  • Update the dimensions to match the columns in your table
  • Add metrics that make sense for your data

​
Step 3: Validate your YAML

Check your YAML files for errors by running: 
lightdash lint
This command validates your configuration and reports any issues before you deploy.

​
Step 4: Deploy your project

Create your Lightdash project by deploying with the CLI: 
lightdash deploy --create --no-warehouse-credentials
The --no-warehouse-credentials flag tells Lightdash that you’re deploying without warehouse credentials embedded in the CLI. After deploying, you’ll need to configure your warehouse connection in the Lightdash UI:
  1. Go to Settings (gear icon in the top right)
  2. Under Current project, click Connection settings
  3. Configure your Warehouse connection with your database credentials
Warehouse connection settings
For detailed instructions on configuring your warehouse connection, see Connect to a warehouse.

​
Step 5: Update your project

After your initial deployment, you can edit your .yml files and redeploy changes: 
lightdash deploy --no-warehouse-credentials

​
Developing with AI coding agents

If you’re developing with Cursor, Claude Code, or another AI coding agent, you can speed up your workflow significantly.
  1. Install Lightdash skills: Run lightdash install-skills to give your coding agent everything it needs to build YAML models, create metrics, and deploy to Lightdash. Then ask your agent to create your YAML files, add some metrics, and deploy to Lightdash. 
    lightdash install-skills
  2. Share your warehouse schema: Give your coding agent access to your warehouse schema so it can generate YAML files that match your actual table structures.
  3. Use validation: Prompt your coding agent to always run lightdash lint after making any changes to catch errors early.
With access to your warehouse schema, AI coding agents can auto-generate dimension and metric definitions for entire tables in seconds.
If you’d rather not install the skills, you can still point your coding agent at the Lightdash YAML format specification directly.

​
Next steps

Once you’ve deployed your Lightdash YAML project: