> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-mintlify-cccf65ca.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Lightdash YAML
> Use Lightdash without a dbt project by defining your semantic layer directly in YAML files.
## 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?
| Scenario | Recommendation |
| --------------------------------------------------------- | ------------------------------------------------------------------------- |
| You already have a dbt project | Use the standard [dbt integration](/references/integrations/dbt-projects) |
| You're planning to adopt dbt soon | Consider setting up dbt first, then connecting to Lightdash |
| You don't use dbt and want to try Lightdash quickly | Use Lightdash YAML |
| You want AI agents or semantic layer features without dbt | Use Lightdash YAML |
| You have tables in your warehouse ready to explore | Use 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.
## Recommended: build with an AI coding agent
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.
Follow the [CLI installation guide](/guides/cli/how-to-install-the-lightdash-cli) and [authenticate](/guides/cli/cli-authentication) with Lightdash.
Run [`lightdash install-skills`](/get-started/develop-in-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.
```bash theme={null}
lightdash install-skills
```
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](/guides/cli/how-to-install-the-lightdash-cli)
2. [Authenticated with Lightdash](/guides/cli/cli-authentication)
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:
```yaml theme={null}
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](/references/integrations/dbt-projects), 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:
```bash theme={null}
mkdir -p lightdash/models
```
Create a YAML file for your first model. For example, `./lightdash/models/users.yml`:
```yaml theme={null}
# 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:
```bash theme={null}
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:
```bash theme={null}
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
For detailed instructions on configuring your warehouse connection, see [Connect to a warehouse](/get-started/setup-lightdash/connect-project#1-connect-to-a-warehouse).
### Step 5: Update your project
After your initial deployment, you can edit your `.yml` files and redeploy changes:
```bash theme={null}
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.
### Recommended setup
1. **Install Lightdash skills:** Run [`lightdash install-skills`](/get-started/develop-in-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.
```bash theme={null}
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](https://raw.githubusercontent.com/lightdash/lightdash/refs/heads/main/packages/common/src/schemas/json/model-as-code-1.0.json) directly.
## Next steps
Once you've deployed your Lightdash YAML project:
* [Explore your data](/get-started/exploring-data/using-explores) in the Lightdash UI
* [Create metrics](/get-started/develop-in-lightdash/how-to-create-metrics) to define your key business calculations
* [Set up AI agents](/guides/ai-agents) to enable natural language queries
* Learn about the [semantic layer reference](/references/metrics) for advanced configuration options