Lightdash reads your dbt project’s YAML and generates a BI layer from it. Columns become dimensions. meta: tag annotations become metrics, joins, and display configuration. The article Defining metrics in Lightdash with dbt is the full guide. These garden notes break it into reusable concepts.
The Building Blocks
Lightdash Dimension Configuration in dbt YAML — How every dbt column becomes a dimension. Types, the hidden flag for raw columns you want to aggregate but not expose, time_intervals for date fields, format strings, and additional_dimensions for computed values that don’t map to physical columns.
Lightdash Metric Types and Definition Syntax — The three metric categories (aggregate, non-aggregate, post-calculation), the rule that aggregate metrics reference dimensions and non-aggregate metrics reference other metrics, column-level vs model-level placement, and the write-back feature for promoting ad-hoc Explore metrics into governed YAML definitions.
Lightdash Joins and Fanout Protection — Connecting models so users can combine dimensions and metrics across tables. The relationship property, why it matters for preventing inflated metrics in one-to-many joins, and when to use pre-joined dbt marts instead of BI-layer joins.
Organizing Lightdash Metrics at Scale — Sidebar group_details, the Metrics Catalog with Spotlight categories, and parameters for environment-specific values. When to introduce each — groups at ~20 fields, Spotlight at ~5-6 models, parameters when you have multiple deployment environments.
Related Concepts
The Metrics as Code note covers the broader practice — why putting metric definitions in version control matters, the governance problems it solves, and which tools support the pattern. Lightdash is one implementation; Semantic Layer Architecture compares it to MetricFlow, Snowflake Semantic Views, and Databricks Metric Views.
For Lightdash’s position in the broader BI landscape, see BI Tool Selection Framework.
If you’re building in MetricFlow instead of Lightdash’s native syntax, the parallel notes are MetricFlow Metric Types, Metric Naming Conventions in dbt, and Metric Organization in dbt Projects.
How Lightdash Reads Your dbt Project
Lightdash connects to your dbt project through a Git repository (GitHub, GitLab, Azure DevOps, or Bitbucket). When changes merge to the connected branch, Lightdash reads the repo, compiles the project, and regenerates the BI layer. You can also push compiled projects via lightdash deploy from CI/CD, or trigger a manual refresh in the UI.
On dbt v1.9 and earlier, the meta: block sits directly under the column or model. On v1.10+ and Fusion, it wraps inside a config: block. The notes in this hub use v1.9 syntax.
Source Article
lightdash-dbt-metrics-yaml — the complete YAML reference with worked examples across dimensions, metrics, joins, and organization patterns.