Skip to main content

Get your dbt project Lightdash-ready

In Lightdash, everything you need for BI is written as code in your dbt project. You use dbt to transform all of the data from your data warehouse, then you use Lightdash to explore it.

But, before you hook up your dbt project to Lightdash, we want to make sure it's ready for exploring. We'll walk you through the steps of installing + using the Lightdash CLI and generating the .yml you need for your dbt project.

New to dbt?​

If you haven't used dbt before, follow dbt's getting started guide before proceeding with setting up Lightdash.

Installing the Lightdash CLI tool​

The Lightdash CLI is the recommended way to develop your dbt + Lightdash project. It makes development faster and easier, as well as giving you options for building more powerful automation to manage your Lightdash instance.

To install Lightdash, you'll need to have npm installed. Mac/Linux users usually already have npm available (you can check by running npm in your command line).

To install the Lightdash CLI, run the following on your command line.

npm install -g @lightdash/cli

Or install a specific version (eg: 0.162.0)

npm install -g @lightdash/cli@0.162.0

You may need to install an additional package if you see any errors:

Mac OS

/bin/bash -c "$(curl -fsSL" # install homebrew if you don't have it
brew install unixodbc
npm install -g @lightdash/cli


sudo apt install unixodbc
npm install -g @lightdash/cli

Creating dimensions in Lightdash using lightdash dbt run​

Dimensions are attributes of your data. They are directly linked to a column in a dbt model.

To explore data in Lightdash, you need to have dimensions defined in your dbt model properties. Dimensions are created automatically when you define columns in your dbt model properties.

For example, if I had a dbt .yml file that looked like this:

version: 2
- name: users
- name: user_id
description: "unique ID for a user"
- name: first_name
description: "User's first name"

Then, I'd see a table in Lightdash called Users with two dimensions to explore: User id and First name.


Before you get started with the next steps, you might want to check out onto a new branch if you're working with a version controlled project!

To get our dbt project Lightdash-ready, we need to define all of the columns in our dbt models that we want to explore in Lightdash. We've made this really easy to do using our CLI tool and the command:

lightdash dbt run

This command runs our dbt project to create our analysis-ready tables in our data warehouse. Then, it auto-generates our Lightdash configuration.

You have a few options with this command though:

1. Generate dimensions for my entire dbt project​

To do this, you just need to run the following on your command line:

lightdash dbt run

This command will run + generate the .yml files with dimensions for all of the columns for all of the models in your dbt project.

2. Generate dimensions for some of the models in my dbt project​

There may be a specific set of models that you want to start out with in Lightdash. If this is the case, we recommend using dbt's tags to tag these models. You can use sets of existing tags, or you can create a new Lightdash-specific tag. Something like this:


The lightdash dbt run command supports dbt model selection syntax to generate .yml files for a group of models. This means you can use tags or other model selection syntax to specify which models you want to generate dimensions for in your dbt project.

lightdash dbt run -s tag:lightdash # all models with the lightdash tag
lightdash dbt run -s payments # just payments
lightdash dbt run -s payments+ # payments and all children
lightdash dbt run -s +payments # payments and all parents
lightdash dbt run -s payments+ +customers tag:lightdash # mix and match

After running our dbt project, lightdash dbt run is going to auto-generate all the configuration that Lightdash needs to build your semantic layer. Here’s an example of an auto-generated .yml file that you might see:

# customers.yml
version: 2
- name: customers
- name: customer_id
type: string
- name: name
type: string
- name: created_at
type: timestamp

The customers.yml file tells Lightdash about all the attributes of customers. So by now our Lightdash project usually looks a little like this:

β”œβ”€β”€ dbt_project.yml
└── models
β”œβ”€β”€ customers.sql
└── customers.yml

Now let’s push this project to Lightdash so we can start exploring our data through the UI.

Make sure your changes are in production, then you're ready to go!​

If you're working with a version controlled project, you'll just want to make sure to merge your changes into production (e.g. main or master) before you move onto the next steps.

Once you've got the model .yml files where you want 'em, you're ready to move onto the next step of connecting your project.