How to Use Lightdash: The Beginner's Guide (2026)

CodexFuse Team · 2026-11-02T11:39:00.752Z · 18 min read min read

Lightdash is the dbt-native BI platform that turns your dbt models plus a YAML semantic layer into governed Explore views and dashboards. This beginner guide covers the CLI, generate, dimensions and metrics, preview, deploy, and self-hosting.

How to Use Lightdash If You Already Have a dbt Project

Learning how to use Lightdash starts with one mental-model shift, and then everything else is mechanical. Lightdash is not a general-purpose BI tool you point at a database — it is a dbt-native analytics layer that reads your dbt project's models and the YAML semantic layer you write inside them, then lets your whole team explore governed dimensions and metrics in a friendly Explore view. If you already have a dbt project running on a supported warehouse, you are most of the way there before you touch Lightdash at all.

This Lightdash tutorial is the independent beginner guide the search results are missing: the full arc from installing the Lightdash CLI, connecting your dbt project, generating your first Tables with lightdash generate, defining dimensions and metrics in YAML, previewing and deploying with lightdash preview and lightdash deploy, to running your first Explore and saving your first dashboard. Metrics defined once here stay consistent everywhere — that single promise is what makes the whole product worth learning.

The one honest prerequisite: Lightdash needs a dbt project. If dbt is new to you, start with the dbt beginner guide first, then come back here — everything below assumes your models exist and run.

What Is Lightdash, Exactly?

Lightdash is an open-source, dbt-native BI platform that turns your dbt models plus a YAML semantic layer into explorable Tables, dashboards, and governed metrics for the whole team. Its own GitHub README puts it this way: "Lightdash is the Agentic BI platform for teams that want analytics to move like software. Your context layer defines trusted metrics, joins, permissions, business logic, and caching once, then powers every way people consume data." The plain-English version: you write metrics and dimensions as code in your dbt project, and Lightdash compiles them into a BI experience where business users can answer their own questions without rewriting your logic.

Unlike building a separate semantic layer from scratch, Lightdash reads dbt's YAML model definitions and compiled manifest files to generate its queryable data models. That is the architectural trick that makes it fast to adopt: your dbt project already describes your data, so Lightdash reuses that work instead of asking you to rebuild it somewhere else.

Lightdash Is Not Metabase: Draw This Line Once

The lightdash vs metabase question comes up in almost every evaluation, and this is the one distinction that prevents every beginner confusion. Metabase and Superset connect to arbitrary databases and tables directly — point, click, explore anything the database holds. Lightdash refuses that shortcut on purpose: it requires a dbt project (or a native Lightdash YAML project), and the tables you see in Explore still come from your project's dbt or Lightdash YAML models. Lightdash never queries tables you have not modeled.

Question	Lightdash	Metabase / Superset
What does it connect to?	Your dbt project + warehouse	Any database directly
Where are metrics defined?	Once, in dbt YAML	Per-question, in the UI
Who defines the data model?	Analytics engineers, in code	Anyone, in the browser
Metric consistency	Guaranteed by the semantic layer	Depends on the asker

Neither approach is "better" in the abstract — they solve different problems. If your team already runs dbt and fights over whose revenue number is right, Lightdash's governed layer is the fix. If you just need anyone to poke at a database, the Metabase beginner guide covers that world.

What Do You Need Before You Start Lightdash?

Three things, in this order: a warehouse, a dbt project, and a Lightdash instance. Lightdash supports BigQuery, Postgres, Supabase, Redshift, Snowflake, Databricks, Trino, ClickHouse, DuckDB, and Athena today, and the docs note that anything else may still connect through Trino. Supabase connects through the Postgres warehouse type, and Lightdash recommends read-only permissions for its warehouse credentials.

On the dbt side, Lightdash compiles your project with dbt Core 1.x — the project's dbt version field defaults to "latest," meaning the newest dbt Core 1.x Lightdash supports. There is no dbt Core v2 (Fusion) option yet; for a Fusion project you keep "latest" and stay compatible with dbt Core 1.10 or later. You connect the dbt project one of three ways: through the Lightdash CLI deploy, through a git connection (GitHub, GitLab, Azure DevOps, or Bitbucket), or through the dbt Cloud connection, which reads models, columns, and compiled SQL from your dbt Cloud project's metadata instead of compiling anything itself. You can also skip dbt entirely with a native Lightdash YAML project, but the dbt route is the main path this guide follows.

Finally, you need somewhere Lightdash runs. The fastest zero-setup option is Lightdash Cloud (free trial) or the hosted Playground with sample data for exploration; the alternative is self-hosting on your own infrastructure, which we cover below. If you have no dbt project yet, the Playground's sample data lets you learn Explore without any of this setup.

How Do You Install the Lightdash CLI?

The Lightdash CLI is where developers live: it generates Tables, compiles your semantic layer, previews changes, and deploys them. The docs recommend installing with Homebrew on macOS, Linux, or Windows via WSL — it ships a self-contained binary and does not require Node.js — or downloading a prebuilt binary from the GitHub releases. The advanced path is npm: the CLI is published as @lightdash/cli and needs Node.js 24 or newer, plus the dbt core or dbt cloud CLI installed and available under the dbt command.

I verified the npm path end to end on 2026-11-02: npm i -g @lightdash/cli installed version 3.118.3, and lightdash --help reports the tool as "Developer tools for dbt and Lightdash," with real commands including login, generate, compile, deploy, preview, validate, and dbt. The built-in examples confirm the workflow vocabulary the docs teach:

lightdash generate -- generates .yml file for all dbt models
lightdash generate -s mymodel -- generates .yml file for a single dbt model
lightdash deploy -- compiles and deploys Lightdash metrics to active project
lightdash compile -- compiles Lightdash metrics and dimensions
lightdash dbt run -- runs dbt for all models and updates .yml for all models

Versions move fast — the registry showed 3.118.3 at install time today, so always check the current version rather than memorizing these numbers. With the CLI installed, you authenticate with lightdash login, which uses browser-based OAuth by default: for a Cloud project at petey.lightdash.cloud you would type lightdash login petey to pop up a login window. Your active project lives in the CLI config, or the LIGHTDASH_PROJECT environment variable.

How Do You Connect Lightdash to Your dbt Project?

Connecting is a two-part job: a warehouse connection and a dbt project connection. The warehouse connection is created in the Lightdash project's settings or the new-project wizard — this is where you hand Lightdash the credentials for your BigQuery, Snowflake, Postgres, or other supported warehouse. The dbt project connection decides how Lightdash sees your models: point it at a git repository (GitHub, GitLab, Azure DevOps, or Bitbucket) and give the project directory path from the repo root to the folder containing dbt_project.yml, connect through the dbt Cloud API, or skip remote connections entirely and push from your laptop with the CLI.

The git route is the most common for teams, and it keeps your semantic layer versioned alongside your dbt code — if your git workflow is rusty, the Git beginner guide covers branches and remotes. The CLI-deploy route is the fastest for a solo developer: authenticate, then run lightdash deploy from your dbt project directory, and the CLI compiles locally and pushes the result to your active project, using the credentials in your local profiles.yml. One important line from the docs: changing the warehouse connection later does not change the tables in Explore — they still come from the project's dbt or Lightdash YAML models.

How Do You Use Lightdash, Step by Step?

The whole developer workflow fits in seven steps, straight from the vendor's current "build your semantic layer" track. Learn this arc and you know the product:

Install the Lightdash CLI and authenticate, so your local machine can talk to your Lightdash project.
Tag the dbt models you want to expose as Tables, so staging and intermediate models stay out of Lightdash.
Run lightdash generate to write a starting YAML file for each model, with an entry for every column.
Define your dimensions — the attributes your team groups and filters by, declared in the model's YAML.
Define your metrics — the aggregations your team measures, written once so everyone's numbers stay consistent.
Run lightdash preview to spin up a temporary project from your local changes and check your work against real data without touching production.
Run lightdash deploy to push your local dbt or native Lightdash YAML models to your production project.

That loop — generate, define, preview, deploy — is the analytics-as-software development cycle the product is built around. Everything after this section is a close-up of one of these steps.

How Does the Lightdash YAML Semantic Layer Work?

The Lightdash semantic layer is the YAML you write inside your dbt project, and it has exactly two building blocks: dimensions and metrics. Dimensions are the attributes your team groups and filters by — each one is a column in your model, declared in its YAML under the meta tag. You rarely specify types by hand: dimension types like string, number, timestamp, date, and boolean are pulled from your data warehouse automatically, and timestamp or date dimensions get automatic time intervals (day, week, month, quarter, year) for free.

Metrics are the aggregations your team measures — and defining them once here is what keeps everyone's numbers consistent. The docs define a metric as "a value that describes or summarizes features from a collection of data points," like a count of user IDs or a sum of revenue, declared under the meta tag at the column or model level. The guide's one-liner is worth memorizing: if dimensions segment your data into groups, metrics calculate interesting statistics for those groups. A minimal example in your model's schema.yml looks like this:

models:
  - name: orders
    columns:
      - name: order_total
        meta:
          dimension:
            type: number
          metrics:
            total_revenue:
              type: sum
      - name: order_id
        meta:
          dimension:
            type: string
          metrics:
            order_count:
              type: count

Metric types come in three families, and the distinction matters. Aggregate metrics (sum, count, count_distinct, average, median, percentile, min, max) can only reference dimensions, never other metrics. Non-aggregate metrics (number, boolean, string, date) are calculations on other metrics. Post-calculation metrics (percent_of_previous, percent_of_total, running_total) are computed after the aggregates and non-aggregates. Lightdash can also translate a supported subset of dbt MetricFlow metrics into Lightdash metrics at deploy time, which softens migrations from MetricFlow-based setups.

Where does all this YAML live? In a dbt project, it lives in your model's schema.yml files, with Lightdash config under each column's meta tag. If you run a native Lightdash YAML project without dbt, the files live under a lightdash/ folder — lightdash.config.yml plus lightdash/models/, and documents under lightdash/documents/. Either way, the rule holds: everything your team explores is written as code, reviewable in pull requests like everything else.

What Does lightdash generate Actually Do?

Writing schema.yml entries by hand for every column of every model would be miserable, so the CLI automates the boring part. The docs describe it plainly: to make it faster to write and maintain your schema.yml files, the Lightdash CLI will automatically generate and sync them. Run lightdash generate inside your dbt project and it writes a starting YAML file for each model, with an entry for every column — you edit rather than author from scratch.

Two practical details make this work well. First, run dbt run before you generate, because the command relies on your database schema to detect which columns are required — generating against an empty warehouse produces an empty skeleton. Second, you do not have to generate everything: the CLI supports dbt's model-selection syntax, so lightdash generate -s mymodel covers one model, -s tag:sales covers every model tagged sales, and -s +mymodel covers a model plus its parents. Re-running generate later syncs your files with new columns that appeared in the database, so the command is part of ongoing maintenance, not a one-time step.

How Do You Preview and Deploy Your Changes?

Preview is the safety net that makes the analytics-as-code loop trustworthy. lightdash preview spins up a temporary project from your local changes so you can check your work against real data without touching production. The fine print matters: for a dbt project, a preview only compiles your dbt code into Explores — it never runs dbt run or dbt build against your warehouse. Previews copy charts and dashboards from the parent project, they expire on their own, and you can remove one with lightdash stop-preview --name or promote its content back to production.

When the preview looks right, lightdash deploy pushes your local dbt or native Lightdash YAML models to Lightdash. By default it uses your local dbt profile for the connection, pushes the current state of your local dbt project files — including uncommitted changes or code from your active branch — to the authenticated project, and triggers a re-compile and refresh. You can narrow a deploy with dbt node-selection flags like --select, and strict flags like --no-partial-compilation and --validate-warehouse-columns turn the deploy into a proper CI gate. The warehouse credentials come from your local dbt profiles.yml (by default at ~/.dbt/profiles.yml), so the machine running the CLI needs warehouse access — deploy from CI with a read-only service user and you have a governed promotion pipeline.

How Do You Explore and Build Your First Dashboard?

Everything so far was developer work; Explore is where everyone else lives. The Explore view lets you query a table, sort and chart the results, and save the chart. You pick a Table, drag in dimensions and metrics, add filters, watch the results table fill in, choose a chart type, and save — saved charts re-run their queries when opened, so they stay fresh. "Explore from here" opens a copy of any existing chart or dashboard tile so you can experiment without touching the original.

The Explore view has five areas you will learn by feel: the metrics-and-dimensions picker, the filters panel, the chart area, the results table, and the query controls. The key beginner realization is that you are never choosing raw columns — you are choosing dimensions and metrics your analytics engineers defined, which is exactly why the numbers always agree. Saved charts and dashboards live in Spaces, which the docs describe plainly: "Spaces are kind of like folders. All saved charts and dashboards exist in a Space and can only be in one Space at a time." Organize by team or topic from day one, and your first lightdash dashboard is simply a Space with a few saved charts arranged on a canvas.

How Do You Self-Host Lightdash?

If you would rather run Lightdash on your own infrastructure, the lightdash self hosted route starts with Docker Compose: the minimal path: clone the GitHub repo, set PGPASSWORD and LIGHTDASH_SECRET, and run docker compose up -d for a working instance — the docs frame this as the proof-of-concept route that avoids Kubernetes entirely. For production, there is an official Helm chart plus general Kubernetes guidance, and on-prem enterprise deployments are supported.

Under the hood, a production self-hosted Lightdash is several services: the API and UI, a dedicated scheduler worker for deliveries and exports, a warehouse query worker, a Browserless Chromium instance for chart rendering, managed PostgreSQL for Lightdash's own metadata, and an S3-compatible bucket for results. Knowing that shape matters when you size the deployment — the warehouse does the heavy analytical lifting, but Lightdash's metadata database and result storage need real capacity too. If container commands are new to you, the Docker beginner guide walks through them from zero.

How Much Does Lightdash Cost?

The pricing story is simple in outline and moving in detail — treat every number below as a snapshot of 2026-11-02, not a quote. Lightdash offers an open-source self-hosted tier you deploy on your own infrastructure, a Cloud Pro tier at $3,000 per month flat with no per-seat pricing and unlimited users, and an Enterprise tier with custom pricing for features like SSO/SAML/SCIM, SOC 2, and HIPAA support.

Tier	Price (2026-11-02 snapshot)	Best for
Open Source (self-hosted)	Free; you pay for infrastructure	Teams with DevOps capacity
Cloud Pro	$3,000/mo flat, unlimited users, no per-seat	Teams that want managed hosting
Enterprise	Custom	SSO, compliance, dedicated regions

The flat per-project Cloud pricing is unusual in BI and worth noticing: unlimited users at one price makes the cost-per-user math favor large teams. On the open-source side, the code is published openly — the docs describe the self-hosted product as MIT-licensed open source — but third parties circulate conflicting license claims, so if licensing matters to your legal team, read the LICENSE file in the repo before building on it. Check the official pricing page before you budget; this space moves.

7 Beginner Mistakes and How to Avoid Them

These are the traps first-time Lightdash users actually fall into:

Mistake	Why it hurts	The fix
Pointing Lightdash at a warehouse with no dbt project	Explore shows nothing — Lightdash only exposes modeled Tables	Set up the dbt project first, or start on the sample-data Playground
Generating YAML before running dbt	`generate` reads your database schema; an empty warehouse makes an empty skeleton	Run `dbt run` first, then `lightdash generate`
Exposing every model as a Table	Staging and intermediate models clutter Explore and confuse users	Tag only clean marts as Tables; keep staging models out
Defining the same metric in two models	Two definitions drift apart and the "single source of truth" promise breaks	Define each metric once; aggregate metrics can only reference dimensions anyway
Skipping preview and deploying straight to production	A bad YAML change breaks Explore for everyone immediately	Use `lightdash preview` to check against real data first
Deploying with personal warehouse credentials	Deploys keep working after the person leaves — until their access is revoked	Use a read-only service user, especially from CI
Treating it like Metabase	Frustration that you "cannot query that table" — it was never modeled	Remember: model it in dbt first, explore it in Lightdash second

Sources

Every fact in this guide was fetched and verified on 2026-11-02. Product details move quickly — verify against the current docs before you build on anything below.

Lightdash docs — Build your semantic layer (updated 2026-10-25): the 7-step developer track, dimensions and metrics definitions, preview and deploy flow — https://docs.lightdash.com/get-started/build-your-semantic-layer
Lightdash docs — CLI install (updated 2026-10-30): Homebrew recommendation, npm path with Node.js 24+, prebuilt binaries, CLI dependencies — https://docs.lightdash.com/workflow/cli/install
Lightdash docs — CLI authentication (updated 2026-10-28): browser OAuth, lightdash login prose example — https://docs.lightdash.com/workflow/cli/authenticate
Lightdash docs — generate (updated 2026-10-29): automatic schema.yml generation and sync, run dbt first — https://docs.lightdash.com/workflow/cli/generate
Lightdash docs — deploy (updated 2026-10-30): pushes local dbt or native YAML models, local profiles.yml, selection flags — https://docs.lightdash.com/workflow/cli/deploy
Lightdash docs — preview projects: temporary preview projects, never runs dbt run/build — https://docs.lightdash.com/workflow/preview-projects
Lightdash docs — connect a project: supported warehouses verbatim list, dbt Core 1.x, connection methods — https://docs.lightdash.com/get-started/setup-lightdash/connect-project
Lightdash docs — dimensions and metrics semantic-layer references: meta tag, auto types, metric families — https://docs.lightdash.com/semantic-layer/dimensions and https://docs.lightdash.com/semantic-layer/metrics
Lightdash GitHub repository (snapshot 2026-11-02): 6,218 stars, 801 forks, created 2021-03-19, TypeScript monorepo — https://github.com/lightdash/lightdash
Lightdash official pricing page (snapshot 2026-11-02): open-source self-hosted, Cloud Pro $3,000/mo flat, Enterprise custom — http://www.lightdash.com/pricing
Railway deploy guide for Lightdash (fetched 2026-11-02): production self-hosted service shape, first-Explore flow — https://railway.com/deploy/lightdash

Frequently Asked Questions

Is Lightdash free?

Yes, the open-source self-hosted tier is free — you clone the repo, run it with Docker Compose or the Helm chart, and pay only for your own infrastructure. Lightdash Cloud's Pro tier is a flat $3,000 per month with unlimited users and no per-seat pricing (snapshot 2026-11-02), and Enterprise is custom-priced.

Do I need dbt to use Lightdash?

Almost always yes. Lightdash is dbt-native: it reads your dbt project's YAML model definitions and compiled manifests to build the semantic layer it exposes in Explore. The only exception is a native Lightdash YAML project, which lets you write the semantic layer without dbt. There is no "connect any table directly" mode — that is the core difference from Metabase and Superset.

Which warehouses does Lightdash support?

As of 2026-11-02 the docs list BigQuery, Postgres, Supabase, Redshift, Snowflake, Databricks, Trino, ClickHouse, DuckDB, and Athena, with read-only credentials recommended. If your warehouse is not listed, the docs suggest you may still connect through Trino.

How is Lightdash different from Metabase?

Metabase connects to databases directly and lets anyone explore any table. Lightdash requires a dbt project and only exposes the models, dimensions, and metrics you define as code — every number in Explore comes from a governed definition, which is why teams adopt it for consistent metrics rather than ad-hoc exploration.

What is the Lightdash CLI used for?

The CLI is the developer workflow: lightdash generate writes starting YAML for your dbt models, you define dimensions and metrics in that YAML, lightdash preview tests your changes in a temporary project against real data, and lightdash deploy pushes them to production. It also validates projects, runs dbt commands, and manages logins.