> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> 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.
# Lightdash
export const PartnerBadge = () => {
return ;
};
export const Image = ({img, alt, size}) => {
return
;
};
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.
Developers love Lightdash for its open architecture, version-controlled YAML models, and integrations that fit directly into their workflow - from GitHub to the IDE.
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.
Build an interactive dashboard with Lightdash and ClickHouse
In this guide, you’ll see how **Lightdash** connects to **ClickHouse** to explore your dbt models and build interactive dashboards.\
The example below shows a finished dashboard powered by data from ClickHouse.
Gather connection data
When setting up your connection between Lightdash and ClickHouse, you’ll need the following details:
* **Host:** The address where your ClickHouse database is running
* **User:** Your ClickHouse database username
* **Password:** Your ClickHouse database password
* **DB name:** The name of your ClickHouse database
* **Schema:** The default schema used by dbt to compile and run your project (found in your `profiles.yml`)
* **Port:** The ClickHouse HTTPS interface port (default: `8443`)
* **Secure:** Enable this option to use HTTPS/SSL for secure connections
* **Retries:** Number of times Lightdash retries failed ClickHouse queries (default: `3`)
* **Start of week:** Choose which day your reporting week starts; defaults to your warehouse setting
To connect to ClickHouse with HTTP(S) you need this information:
| Parameter(s) | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `HOST` and `PORT` | Typically, the port is 8443 when using TLS or 8123 when not using TLS. |
| `DATABASE NAME` | Out of the box, there is a database named `default`, use the name of the database that you want to connect to. |
| `USERNAME` and `PASSWORD` | Out of the box, the username is `default`. Use the username appropriate for your use case. |
The details for your ClickHouse Cloud service are available in the ClickHouse Cloud console.
Select a service and click **Connect**:
Choose **HTTPS**. Connection details are displayed in an example `curl` command.
If you're using self-managed ClickHouse, the connection details are set by your ClickHouse administrator.
***
Configure your dbt profile for ClickHouse
In Lightdash, connections are based on your existing **dbt project**.\
To connect ClickHouse, make sure your local `~/.dbt/profiles.yml` file contains a valid ClickHouse target configuration.
For example:
Create a Lightdash project connected to ClickHouse
Once your dbt profile is configured for ClickHouse, you’ll also need to connect your **dbt project** to Lightdash.
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:
[Import a dbt project → Lightdash Docs](https://docs.lightdash.com/get-started/setup-lightdash/connect-project#2-import-a-dbt-project?utm_source=clickhouse\&utm_medium=partner\&utm_campaign=integration_docs)
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.
***
Explore your ClickHouse data in Lightdash
Once connected, Lightdash automatically syncs your dbt models and exposes:
* **Dimensions** and **measures** defined in YAML
* **Semantic layer logic**, such as metrics, joins, and explores
* **Dashboards** powered by real-time ClickHouse queries
You can now build dashboards, share insights, and even use **Ask AI** to generate visualizations directly on top of ClickHouse — no manual SQL required.
***
Define metrics and dimensions in Lightdash
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.
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.
To learn more about how to define these, see the following Lightdash guides:
* [How to create metrics](https://docs.lightdash.com/guides/how-to-create-metrics?utm_source=clickhouse\&utm_medium=partner\&utm_campaign=integration_docs)
* [How to create dimensions](https://docs.lightdash.com/guides/how-to-create-dimensions?utm_source=clickhouse\&utm_medium=partner\&utm_campaign=integration_docs)
***
Query your data from tables
Once your dbt project is connected and synced with Lightdash, you can start exploring data directly from your **tables** (or “explores”).\
Each table represents a dbt model and includes the metrics and dimensions you’ve defined in YAML.
The **Explore** page is made up of five main areas:
1. **Dimensions and Metrics** — all fields available on the selected table
2. **Filters** — restrict the data returned by your query
3. **Chart** — visualize your query results
4. **Results** — view the raw data returned from your ClickHouse database
5. **SQL** — inspect the generated SQL query behind your results
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.
For a deeper look at explores and how to query from your tables, see:\
[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?utm_source=clickhouse\&utm_medium=partner\&utm_campaign=integration_docs)
***
Build dashboards
Once you’ve explored your data and saved visualizations, you can combine them into **dashboards** to share with your team.
Dashboards in Lightdash are fully interactive — you can apply filters, add tabs, and view charts powered by real-time ClickHouse queries.
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.
To create a dashboard-only chart:
1. Click **Add tile**
2. Select **New chart**
3. Build your visualization in the chart builder
4. Save it — it will appear at the bottom of your dashboard
Learn more about how to create and organize dashboards here:\
[Building dashboards → Lightdash Docs](https://docs.lightdash.com/get-started/exploring-data/dashboards?utm_source=clickhouse\&utm_medium=partner\&utm_campaign=integration_docs)
***
Ask AI: self-serve analytics powered by dbt
**AI Agents** in Lightdash make data exploration truly self-serve.\
Instead of writing queries, you 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.
It’s powered by the same semantic layer you use in dbt, meaning every answer stays governed, explainable, and fast — all backed by ClickHouse.
Learn more about AI Agents here: [AI Agents → Lightdash Docs](https://docs.lightdash.com/guides/ai-agents?utm_source=clickhouse\&utm_medium=partner\&utm_campaign=integration_docs)
Learn more
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?utm_source=clickhouse\&utm_medium=partner\&utm_campaign=integration_docs).