Build your semantic layer

This track is for people who build in Lightdash. Everything you expose for BI is written as code in your dbt project, so the developer journey runs through the Lightdash CLI: you generate Tables from your models, then define the metrics and dimensions your team explores. Each step below gets you moving, then links to the page that covers it in full.

1. Install and authenticate the CLI

The CLI is how your dbt project reaches Lightdash. Install it, then log in to link it to your instance.

npm install -g @lightdash/cli
lightdash login https://your-instance.lightdash.cloud

See installing the CLI and authenticating. To build conversationally with an AI coding agent, also install the Lightdash skills.

2. Choose which models become Tables

Tag the dbt models you want to expose, so staging and intermediate models stay out of Lightdash:

models:
  - name: model_name
    config:
      tags: ['lightdash']

Then point your project’s Tables configuration at that tag. See choosing which Tables appear.

3. Generate your YAML

lightdash generate writes a starting YAML file for each model, with an entry for every column, so you’re editing rather than authoring from scratch.

lightdash generate -s model_name

See lightdash generate.

4. Define dimensions

Dimensions are the attributes your team groups and filters by. Each one is a column in your model, declared in its YAML. See dimensions for the full set of configuration options, formatting, and additional dimensions.

5. Define metrics

Metrics are the aggregations your team measures. Defining them once here is what keeps everyone’s numbers consistent. See metrics for every metric type and configuration option.

6. Preview before you deploy

lightdash preview spins up a temporary project from your local changes so you can check your work against real data without touching production.

lightdash preview

See preview projects.

7. Deploy to production

Once the preview looks right, deploy the changes to your production project.

lightdash deploy

See lightdash deploy, and set up CI/CD to run this automatically on merge.

Where to go next

The rest of the Workflow area covers the software lifecycle around your project: preview environments, pull request checks, content as code, and validating your content. Prefer to watch first? This overview walks through the Lightdash developer workflow end to end.

​1. Install and authenticate the CLI

​2. Choose which models become Tables

​3. Generate your YAML

​4. Define dimensions

​5. Define metrics

​6. Preview before you deploy

​7. Deploy to production

​Where to go next