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.

Lightdash YAML

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

Tables reference

You can run queries against the tables in your Lightdash project.

Dimensions reference

Dimensions are the columns in your table. They are the "attributes" of your data. For example, `user_id` in your users table is a dimension.

Metrics reference

Joins reference

Joins let you connect different models to each other so that you can explore more than one model at the same time in Lightdash and see how different parts of your data relate to each other.

Creating tailored tables from a single dbt model

You can use the `explores` configuration in your Lightdash Semantic Layer to curate multiple ways to query from the same table for different audiences.

How to use parameters

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

SQL variables

When writing SQL in your Lightdash models, you can use the following references to template your SQL and make it more reusable

Virtual views

Turn a custom SQL query into a reusable table in Lightdash. Build a virtual view in the SQL Runner, explore and join it like any dbt table, and manage it as code.

lightdash.config.yml reference

The lightdash.config.yml file allows you to configure project-wide settings for your Lightdash project, including Metrics Catalog, parameters, and defaults.

Writing useful descriptions in your semantic layer

A guide to writing descriptions for models, dimensions, and metrics that serve reviewers, new hires, and AI agents.

Caching

Caching can reduce the overall number of queries that Lightdash executes against your data warehouse. Learn more about the types of caching and how to enable caching in this doc.

Pre-aggregates

Getting started with pre-aggregates

Define pre-aggregates in your dbt YAML, configure scheduling, and start serving queries from materialized data.

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.

dbt

dbt Projects

You can easily make changes in dbt and see them updated in your Lightdash project.

dbt MetricFlow metrics

Connect Lightdash to your dbt MetricFlow semantic layer metrics

dbt modeling strategies for Lightdash

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

dbt write-back

dbt Write-Back allows you to develop your models and Metrics in Lightdash and write back these changes to your dbt project. Writing back to dbt will create a new branch and pull request in your project so you can save and manage these changes.

Migrating to dbt 1.10: Fix Meta and Tags Configuration Warnings

Learn how to fix dbt 1.10 deprecation warnings for `meta` and `tags` properties, and migrate your project automatically with MetaMove.

Migrating to dbt Fusion

Migrate from dbt Core or dbt Cloud to the dbt Fusion engine: preparation steps, requirements, and the changes to expect.