Skip to content

Commit 8fc2cae

Browse files
torimwhaleytorimwhaley
committed
lightdash.md file
1 parent a4e09d4 commit 8fc2cae

File tree

1 file changed

+170
-0
lines changed

1 file changed

+170
-0
lines changed

‎docs/integrations/data-visualization/lightdash-and-clickhouse.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
sidebar_label: 'Lightdash'
3+
sidebar_position: 132
4+
slug: /integrations/lightdash
5+
keywords: ['clickhouse', 'lightdash', 'data visualization', 'BI', 'semantic layer', 'dbt', 'self-serve analytics', 'connect']
6+
description: 'Lightdash is a modern open-source BI tool built on top of dbt, enabling teams to explore and visualize data from ClickHouse through a semantic layer. Learn how to connect Lightdash to ClickHouse for fast, governed analytics powered by dbt.'
7+
title: 'Connecting Lightdash to ClickHouse'
8+
doc_type: 'guide'
9+
integration:
10+
- support_level: 'partner'
11+
- category: 'data_visualization'
12+
---
13+
14+
import lightdash_01 from '@site/static/images/integrations/data-visualization/lightdash_01.png';
15+
import lightdash_02 from '@site/static/images/integrations/data-visualization/lightdash_02.png';
16+
import lightdash_03 from '@site/static/images/integrations/data-visualization/lightdash_03.png';
17+
import lightdash_04 from '@site/static/images/integrations/data-visualization/lightdash_04.png';
18+
import lightdash_05 from '@site/static/images/integrations/data-visualization/lightdash_05.png';
19+
import lightdash_06 from '@site/static/images/integrations/data-visualization/lightdash_06.png';
20+
import ConnectionDetails from '@site/docs/_snippets/_gather_your_details_http.mdx';
21+
import Image from '@theme/IdealImage';
22+
import PartnerBadge from '@theme/badges/PartnerBadge';
23+
24+
# Goal
25+
26+
In this guide, you’ll see how **Lightdash** connects to **ClickHouse** to explore your dbt models and build interactive dashboards.
27+
The example below shows a finished dashboard powered by data from ClickHouse.
28+
29+
<Image size="lg" img={lightdash_02} alt="Lightdash dashboard example" border />
30+
31+
# Connecting Lightdash to ClickHouse
32+
33+
<PartnerBadge/>
34+
35+
Lightdash is the **AI-first BI platform** built for modern data teams, combining the openness of dbt with the performance of ClickHouse. By connecting ClickHouse to Lightdash, teams get an **AI-powered self-serve analytics experience** grounded in their dbt semantic layer, so every question is answered with governed, consistent metrics.
36+
37+
Developers love Lightdash for its open architecture, version-controlled YAML models, and integrations that fit directly into their workflow - from GitHub to the IDE.
38+
This partnership brings together **ClickHouse’s speed** and **Lightdash’s developer experience**, making it easier than ever to explore, visualize, and automate insights with AI.
39+
40+
41+
## Connection data required {#connection-data-required}
42+
43+
When setting up your connection between Lightdash and ClickHouse, you’ll need the following details:
44+
45+
- **Host:** The address where your ClickHouse database is running
46+
- **User:** Your ClickHouse database username
47+
- **Password:** Your ClickHouse database password
48+
- **DB name:** The name of your ClickHouse database
49+
- **Schema:** The default schema used by dbt to compile and run your project (found in your `profiles.yml`)
50+
- **Port:** The ClickHouse HTTP interface port (default: `8123`)
51+
- **Secure:** Enable this option to use HTTPS/SSL for secure connections
52+
- **Retries:** Number of times Lightdash retries failed ClickHouse queries (default: `3`)
53+
- **Start of week:** Choose which day your reporting week starts; defaults to your warehouse setting
54+
55+
<ConnectionDetails />
56+
57+
---
58+
59+
## Configuring your dbt profile for ClickHouse {#configuring-your-dbt-profile-for-clickhouse}
60+
61+
In Lightdash, connections are based on your existing **dbt project**.
62+
To connect ClickHouse, make sure your local `~/.dbt/profiles.yml` file contains a valid ClickHouse target configuration.
63+
64+
For example:
65+
66+
<Image size="md" img={lightdash_01} alt="Example profiles.yml configuration for a lightdash-clickhouse project" border />
67+
<br/>
68+
69+
## Creating a Lightdash project connected to ClickHouse {#creating-a-lightdash-project-connected-to-clickhouse}
70+
71+
Once your dbt profile is configured for ClickHouse, you’ll also need to connect your **dbt project** to Lightdash.
72+
73+
Because this process is the same for all data warehouses, we won’t go into detail here — you can follow the official Lightdash guide for importing a dbt project:
74+
[Import a dbt project → Lightdash Docs](https://docs.lightdash.com/get-started/setup-lightdash/connect-project#2-import-a-dbt-project)
75+
76+
After connecting your dbt project, Lightdash will automatically detect your ClickHouse configuration from the `profiles.yml` file. Once the connection test succeeds, you’ll be able to start exploring your dbt models and building dashboards powered by ClickHouse.
77+
78+
---
79+
80+
## Exploring your ClickHouse data in Lightdash {#exploring-your-clickhouse-data-in-lightdash}
81+
82+
Once connected, Lightdash automatically syncs your dbt models and exposes:
83+
84+
- **Dimensions** and **measures** defined in YAML
85+
- **Semantic layer logic**, such as metrics, joins, and explores
86+
- **Dashboards** powered by real-time ClickHouse queries
87+
88+
You can now build dashboards, share insights, and even use **Ask AI** to generate visualizations directly on top of ClickHouse — no manual SQL required.
89+
90+
---
91+
92+
## Defining metrics and dimensions in Lightdash {#defining-metrics-and-dimensions-in-lightdash}
93+
94+
In Lightdash, all **metrics** and **dimensions** are defined directly in your dbt model `.yml` files. This makes your business logic version-controlled, consistent, and fully transparent.
95+
96+
<Image size="md" img={lightdash_03} alt="Example of metrics being defined in the .yml file" border />
97+
<br/>
98+
99+
Defining these in YAML ensures your team is using the same definitions across dashboards and analyses. For example, you can create reusable metrics like `total_order_count`, `total_revenue`, or `avg_order_value` right next to your dbt models — no duplication required in the UI.
100+
101+
To learn more about how to define these, see the Lightdash guides:
102+
- [How to create metrics](https://docs.lightdash.com/guides/how-to-create-metrics)
103+
- [How to create dimensions](https://docs.lightdash.com/guides/how-to-create-dimensions)
104+
105+
---
106+
107+
## Querying your data from tables {#querying-your-data-from-tables}
108+
109+
Once your dbt project is connected and synced with Lightdash, you can start exploring data directly from your **tables** (or “explores”).
110+
Each table represents a dbt model and includes the metrics and dimensions you’ve defined in YAML.
111+
112+
## Querying your data from tables {#querying-your-data-from-tables}
113+
114+
Once your dbt project is connected and synced with Lightdash, you can start exploring data directly from your **tables** (also called “explores”).
115+
Each explore represents a dbt model and includes the metrics and dimensions you’ve defined in YAML.
116+
117+
The **Explore** page is made up of five main areas:
118+
119+
1. **Dimensions and Metrics** — all fields available on the selected table
120+
2. **Filters** — restrict the data returned by your query
121+
3. **Chart** — visualize your query results
122+
4. **Results** — view the raw data returned from your ClickHouse database
123+
5. **SQL** — inspect the generated SQL query behind your results
124+
125+
<Image size="lg" img={lightdash_04} alt="Lightdash Explore view showing dimensions, filters, chart, results, and SQL" border />
126+
127+
From here, you can build and adjust queries interactively — dragging and dropping fields, adding filters, and switching between visualization types such as tables, bar charts, or time series.
128+
129+
For a deeper look at explores and how to query from your tables, see:
130+
[An intro to tables and the Explore page → Lightdash Docs](https://docs.lightdash.com/get-started/exploring-data/using-explores#an-intro-to-tables-and-the-explore-page)
131+
132+
---
133+
134+
## Building dashboards {#building-dashboards}
135+
136+
Once you’ve explored your data and saved visualizations, you can combine them into **dashboards** to share with your team.
137+
138+
Dashboards in Lightdash are fully interactive — you can apply filters, add tabs, and view charts powered by real-time ClickHouse queries.
139+
140+
You can also create new charts **directly from within a dashboard**, which helps keep your projects organized and clutter-free. Charts created this way are **exclusive to that dashboard** — they can’t be reused elsewhere in the project.
141+
142+
To create a dashboard-only chart:
143+
1. Click **Add tile**
144+
2. Select **New chart**
145+
3. Build your visualization in the chart builder
146+
4. Save it — it will appear at the bottom of your dashboard
147+
148+
<Image size="lg" img={lightdash_05} alt="Creating and organizing charts within a Lightdash dashboard" border />
149+
150+
Learn more about how to create and organize dashboards here:
151+
[Building dashboards → Lightdash Docs](https://docs.lightdash.com/get-started/exploring-data/dashboards)
152+
153+
---
154+
155+
## Ask AI: self-serve analytics powered by dbt {#ask-ai}
156+
157+
Lightdash’s **AI Agents** make data exploration truly self-serve.
158+
Instead of writing queries, users can simply ask questions in plain language — like *“What was our monthly revenue growth?”* — and the AI Agent automatically generates the right visualization, referencing your dbt-defined metrics and models to ensure accuracy and consistency.
159+
160+
It’s powered by the same semantic layer you use in dbt, meaning every answer stays governed, explainable, and fast — all backed by ClickHouse.
161+
162+
<Image size="lg" img={lightdash_06} alt="Lightdash Ask AI interface showing natural language query powered by dbt metrics" border />
163+
164+
Learn more about AI Agents here:
165+
[AI Agents → Lightdash Docs](https://docs.lightdash.com/guides/ai-agents)
166+
167+
168+
## Learn more
169+
170+
To learn more about connecting dbt projects to Lightdash, visit the [Lightdash Docs → ClickHouse setup](https://docs.lightdash.com/get-started/setup-lightdash/connect-project#clickhouse).

0 commit comments

Comments
 (0)