Skip to content

Commit d2e32cd

Browse files
torimwhaleygithub-actions[bot]
torimwhaley
and
github-actions[bot]
authored
adding Lightdash YAML page (#365)
* adding dbt-less ligthdash page * one adjustment * last updates * adding image * updating name of file * 🤖 Auto-fix: Move images to correct directories Automatically fixed image location issues. Co-Authored-By: GitHub Actions <github-actions[bot]@users.noreply.github.com> * updating loom * note that this syntax is similar to LD semantic layer * adding config file mention --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
1 parent 7423d36 commit d2e32cd

4 files changed

Lines changed: 179 additions & 1 deletion

File tree

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,7 @@
208208
"pages": [
209209
"references/integrations",
210210
"references/integrations/dbt-projects",
211+
"references/integrations/lightdash-yaml",
211212
"references/integrations/slack-integration",
212213
"references/integrations/google-sheets",
213214
"references/integrations/lightdash-mcp"

‎guides/lightdash-semantic-layer.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ Tables represent important business objects like customers, orders, or products.
3939
Lightdash's semantic layer works with your existing data warehouse through four key steps:
4040

4141
1. **Data warehouse connection:** Lightdash connects directly to tables or views in your data warehouse.
42-
2. **YAML configuration:** You define your semantic layer through YAML configuration files that specify metrics, dimensions, and their relationships. This approach makes definitions transparent, version-controllable, and easy to maintain.
42+
2. **YAML configuration:** You define your semantic layer through YAML configuration files that specify metrics, dimensions, and their relationships. This approach makes definitions transparent, version-controllable, and easy to maintain. You can define your semantic layer within a [dbt project](/references/integrations/dbt-projects) or use [Lightdash YAML](/references/integrations/lightdash-yaml) if you don't have dbt.
4343
3. **Metadata enrichment:** Lightdash lets you add business-friendly labels, descriptions, and formatting to make the data easier to understand. This metadata turns technical fields into business concepts.
4444
4. **Dynamic query generation:** When users interact with the semantic layer, Lightdash automatically generates optimized SQL queries, handling all the complexity of joins, aggregations, and filters behind the scenes.
4545

‎images/references/integrations/lightdash-yaml/warehouse-connection.png‎

482 KB
Loading

‎references/integrations/lightdash-yaml.mdx‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
title: "Lightdash YAML"
3+
sidebarTitle: Lightdash YAML
4+
description: "Use Lightdash without a dbt project by defining your semantic layer directly in YAML files."
5+
---
6+
7+
<Frame>
8+
<iframe width="100%" height="420" src="https://www.loom.com/embed/d7cab1a72e2a40f088998c4fb387e185" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen />
9+
</Frame>
10+
11+
## What is Lightdash YAML?
12+
13+
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.
14+
15+
This approach lets you leverage Lightdash's powerful features without needing to adopt dbt first.
16+
17+
## Why use Lightdash YAML?
18+
19+
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.
20+
21+
However, not every team uses dbt. If you're interested in Lightdash features like:
22+
23+
- **AI agents** that can answer questions about your data
24+
- **A semantic layer** with consistent metric definitions
25+
- **Self-service analytics** for your business users
26+
27+
...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.
28+
29+
## dbt vs Lightdash YAML: which should you use?
30+
31+
| Scenario | Recommendation |
32+
|----------|----------------|
33+
| You already have a dbt project | Use the standard [dbt integration](/references/integrations/dbt-projects) |
34+
| You're planning to adopt dbt soon | Consider setting up dbt first, then connecting to Lightdash |
35+
| You don't use dbt and want to try Lightdash quickly | Use Lightdash YAML |
36+
| You want AI agents or semantic layer features without dbt | Use Lightdash YAML |
37+
| You have tables in your warehouse ready to explore | Use Lightdash YAML |
38+
39+
The good news: if you start with Lightdash YAML and later decide to adopt dbt, the YAML formats are compatible, so migration is straightforward.
40+
41+
## Getting started with Lightdash YAML
42+
43+
### Prerequisites
44+
45+
Before you begin, make sure you have:
46+
47+
1. The [Lightdash CLI installed](/guides/cli/how-to-install-the-lightdash-cli)
48+
2. [Authenticated with Lightdash](/guides/cli/cli-authentication)
49+
3. Credentials for your data warehouse (e.g., Snowflake)
50+
4. Tables in your warehouse that you want to explore
51+
52+
### Step 1: Create your project configuration
53+
54+
At the root of your project, create a `lightdash.config.yml` file to specify your warehouse type:
55+
56+
```yaml
57+
warehouse:
58+
type: snowflake
59+
```
60+
61+
Replace `snowflake` with your warehouse type (e.g., `bigquery`, `databricks`, `redshift`, `postgres`, `trino`).
62+
63+
### Step 2: Create your first model
64+
65+
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.
66+
67+
Create a directory structure for your Lightdash project:
68+
69+
```bash
70+
mkdir -p lightdash/models
71+
```
72+
73+
Create a YAML file for your first model. For example, `./lightdash/models/users.yml`:
74+
75+
```yaml
76+
# Metadata
77+
type: model
78+
name: users
79+
80+
# Table definition
81+
sql_from: 'DB.SCHEMA.USERS'
82+
83+
# Metric definitions
84+
# For more configuration see: https://docs.lightdash.com/references/metrics
85+
metrics:
86+
user_count:
87+
type: count_distinct
88+
sql: ${TABLE}.USER_ID
89+
description: Total unique users
90+
91+
# Dimension definitions
92+
# For more configuration see: https://docs.lightdash.com/references/dimensions
93+
dimensions:
94+
- name: subscription_type
95+
sql: ${TABLE}.SUBSCRIPTION
96+
type: string
97+
98+
- name: signed_up_at
99+
sql: ${TABLE}.SIGNED_UP
100+
type: date
101+
time_intervals:
102+
- DAY
103+
- WEEK
104+
- MONTH
105+
```
106+
107+
Update the configuration:
108+
109+
- Set `sql_from` to the fully qualified name of your table (e.g., `DATABASE.SCHEMA.TABLE`)
110+
- Update the dimensions to match the columns in your table
111+
- Add metrics that make sense for your data
112+
113+
### Step 3: Validate your YAML
114+
115+
Check your YAML files for errors by running:
116+
117+
```bash
118+
lightdash lint
119+
```
120+
121+
This command validates your configuration and reports any issues before you deploy.
122+
123+
### Step 4: Deploy your project
124+
125+
Create your Lightdash project by deploying with the CLI:
126+
127+
```bash
128+
lightdash deploy --create --no-warehouse-credentials
129+
```
130+
131+
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:
132+
133+
1. Go to **Settings** (gear icon in the top right)
134+
2. Under **Current project**, click **Connection settings**
135+
3. Configure your **Warehouse connection** with your database credentials
136+
137+
<Frame>
138+
![Warehouse connection settings](../../images/references/integrations/lightdash-yaml/warehouse-connection.png)
139+
</Frame>
140+
141+
For detailed instructions on configuring your warehouse connection, see [Connect to a warehouse](/get-started/setup-lightdash/connect-project#1-connect-to-a-warehouse).
142+
143+
### Step 5: Update your project
144+
145+
After your initial deployment, you can edit your `.yml` files and redeploy changes:
146+
147+
```bash
148+
lightdash deploy --no-warehouse-credentials
149+
```
150+
151+
## Developing with AI copilots
152+
153+
If you're developing with Cursor, Claude Code, Kilo Code, or another AI copilot, you can speed up your workflow significantly.
154+
155+
### Recommended setup
156+
157+
1. **Provide the schema reference:** Give your copilot this link to the Lightdash YAML format specification:
158+
```
159+
https://raw.githubusercontent.com/lightdash/lightdash/refs/heads/main/packages/common/src/schemas/json/model-as-code-1.0.json
160+
```
161+
162+
2. **Use validation:** Prompt your copilot to always run `lightdash lint` after making any changes to catch errors early.
163+
164+
3. **Share your warehouse schema:** Give your copilot access to your warehouse schema. This makes it very fast to generate YAML files that match your actual table structures.
165+
166+
<Tip>
167+
With access to your warehouse schema, AI copilots can auto-generate dimension and metric definitions for entire tables in seconds.
168+
</Tip>
169+
170+
## Next steps
171+
172+
Once you've deployed your Lightdash YAML project:
173+
174+
- [Explore your data](/get-started/exploring-data/using-explores) in the Lightdash UI
175+
- [Create metrics](/get-started/develop-in-lightdash/how-to-create-metrics) to define your key business calculations
176+
- [Set up AI agents](/guides/ai-agents) to enable natural language queries
177+
- Learn about the [semantic layer reference](/references/metrics) for advanced configuration options

0 commit comments

Comments
 (0)