Define Lightdash metrics in a dbt project YAML file using meta tags so that they surface automatically in the Lightdash semantic layer
domain: docs.lightdash.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Open the YAML properties file for your dbt model and locate the column you want to aggregate into a metric
Under the column's meta key, add a metrics block with a named metric entry specifying type (e.g., sum, count, count_distinct, average) and optionally a label and description
Refresh your Lightdash project (via the CLI command lightdash generate or via the UI refresh) so that Lightdash reads the updated dbt YAML and registers the new metric
In the Lightdash Metrics Catalog, verify the metric appears with the correct label and that it can be added to a chart alongside dimensions from the same model
Optionally use the dbt write-back feature to promote custom metrics created in the Lightdash UI back to your dbt YAML files, making them permanent and version-controlled
Known gotchas
Lightdash reads metric definitions from the meta tags in dbt YAML at project refresh time; if you add a metric but do not refresh the project, the metric will not appear in the Lightdash UI regardless of dbt compile success
Lightdash YAML (standalone, without dbt) uses the same metric syntax as the dbt meta tag approach but places configuration at the top level rather than nested under meta; mixing the two syntaxes in the same project causes parsing errors
Custom metrics created interactively in the Lightdash UI are stored in Lightdash's database and are not automatically reflected back to your dbt project; use the write-back feature intentionally to promote metrics you want to retain long-term
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?