Skip to main content
The Lightdash semantic layer sits between your data warehouse and the people who query it. You define your business concepts once — in YAML — and everyone gets the same metric definitions, dimension logic, and table relationships everywhere they work. It’s the difference between seeing a field called cust_id in a table called tbl_ord_dtl and seeing Customer on an Order.

​
Core components

  • Metrics — the numbers your business cares about, like revenue, customer count, or order volume, each defined once with clear business logic.
  • Dimensions — the attributes you slice metrics by, such as time periods, regions, or product categories.
  • Tables — the business objects (customers, orders, products) that hold your dimensions and support your metrics.

​
How it’s defined

You define the semantic layer in version-controlled YAML, either inside a dbt project or with Lightdash YAML if you don’t use dbt. Lightdash connects to your warehouse, reads these definitions, and generates optimized SQL at query time — handling joins, aggregations, and filters for you. Adding business-friendly labels, descriptions, and formatting turns technical fields into concepts the whole organization can use.

​
Ways to use it

  • In the app — explore metrics in the Metrics Catalog or query directly from tables.
  • With AI — Lightdash AI agents answer natural-language questions using the same definitions and guardrails as your business users, and can propose writeback changes to your semantic layer.
  • Programmatically — the API and Python SDK give you the semantic layer from code, for automation, scheduled reporting, or embedding.

Tables reference

How dbt models become queryable Tables, and every option for configuring them

Dimensions reference

The columns of your tables, and every option for defining and configuring them in YAML

Metrics reference

Every metric type, its configuration options, filters, formatting, and the SQL it compiles to

Joins reference

Connect models to each other so people can query more than one table at a time

Explores

Curate multiple ways to query the same table for different audiences

How to use parameters

Parameters are variables users set at runtime to build dynamic, reusable queries without writing SQL

SQL variables

Reference variables that template the SQL in your models and make it reusable

Virtual views

Turn a custom SQL query into a reusable table you can explore, join, and manage as code

Lightdash YAML

Use Lightdash without a dbt project by defining your semantic layer directly in YAML files

Caching

Cut the number of queries Lightdash runs against your warehouse with results and warehouse caching

lightdash.config.yml reference

Configure project-wide settings like the Metrics Catalog, parameters, and defaults in one YAML file

Writing useful descriptions in your semantic layer

Write descriptions for models, dimensions, and metrics that serve reviewers, new hires, and AI agents

dbt modeling strategies for Lightdash

How to structure your dbt models so they explore well in Lightdash

Pre-aggregates

External pre-aggregates

Route pre-aggregate queries to a warehouse table you build and refresh yourself

Monitoring and debugging pre-aggregates

Track materialization status, understand why queries miss pre-aggregates, and manage refreshes

Auditing pre-aggregates from the CLI

Use lightdash pre-aggregate-audit to inspect coverage, find gaps in your YAML, and gate CI on dashboard hit rates