Skip to main content

Create your first project in Lightdash

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.

tip

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

What are Tables?​

Tables are the starting point to any data exploration in Lightdash - they're the data in Lightdash that you can query. The beauty of Lightdash is that we're pretty well synced with your dbt project. So, in Lightdash, Tables actually come from dbt models that have been defined in your dbt project's .yml files.

If your dbt model has been defined in a .yml file, it will appear in Lightdash as a Table.

tip

Not sure what a .yml file is? Make sure to check out dbt's docs to learn more about building .yml files for your dbt project.

Here's an example of our Community stats daily model we've defined in dbt. In Lightdash, we can see it in our list of available Tables to explore.

Step 1: Install 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 the Lightdash CLI, run the following on your command line.

npm install -g @lightdash/cli
If you see any errors, you might need to install an extra package:
**Mac OS**
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # install homebrew if you don't have it
brew install unixodbc
npm install -g @lightdash/cli

Ubuntu

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

Step 2: Login to the CLI​

1. If you use your email + password in the browser, login with your email and password.
To login to your Lightdash instance run the following command and provide your login email and password:
lightdash login https://my-lightdash.domain.com

where https://my-lightdash.domain.com is the address for your running Lightdash instance. For example Lightdash cloud users in the US would type lightdash login https://app.lightdash.cloud if you're in Europe you'd type lightdash login https://eu1.lightdash.com.

2. If you use single sign-on (SSO) in the browser, login with a personal access token.
First, you'll need to create a new personal access token in the UI by going to Settings > Personal Access Tokens. You can't use an existing personal access token! You have to create a new one just for yourself.

Then, run the following command in your project:

lightdash login https://my-lightdash.domain.com --token

where https://my-lightdash.domain.com is the address for your running Lightdash instance. For example Lightdash cloud users in the US would type lightdash login https://app.lightdash.cloud if you're in Europe you'd type lightdash login https://eu1.lightdash.com.

3. If you're running in a CI/CD pipeline, login with environment variables

You can use the following environment variables to authenticate yourself on each command:

  • LIGHTDASH_API_KEY a personal access token you can generate in the app under the user settings
  • LIGHTDASH_URL address for your running Lightdash instance

Example:

LIGHTDASH_API_KEY=946fedb74003405646867dcacf1ad345 LIGHTDASH_URL="https://app.lightdash.cloud" lightdash preview

Step 3: Add Tables​

info

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 will generate Tables and dimensions for your entire dbt project. It will document all of the columns in your models and these are what we explore in Lightdash as Dimensions.

For example, if we have a projects.yml file, we'd have a Table called Projects and it would have the dimensions: Dashboards created num total and Days since project created.

If you only want to generate Tables and dimensions for some of the models in your dbt project, check this out​

Generate Tables and 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 as Tables in Lightdash. If this is the case, we recommend [using dbt's `tags`](https://docs.getdbt.com/reference/resource-configs/tags) to tag these models. You can use sets of existing tags, or you can create a new Lightdash-specific tag. Something like this:
{{
  config(
    materialized='table',
    tags=['lightdash']
  )
}}

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
Generate Tables and 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 tables for all of the models with .yml files. It will also generate dimensions for all of the columns in your dbt project.

Step 4: Create your project​

Now, your dbt project is Lightdash-ready! Just run this command and follow the link to start exploring your data:

lightdash deploy --create