Use when creating or modifying dbt Semantic Layer components — semantic models, metrics, dimensions, entities, measures, or time spines. Covers MetricFlow configuration, metric types (simple, derived, cumulative, ratio, conversion), and validation for both latest and legacy YAML specs.
This skill guides the creation and modification of dbt Semantic Layer components: semantic models, entities, dimensions, and metrics.
There are two versions of the Semantic Layer YAML spec:
Look for existing semantic layer configuration in the project:
semantic_models: key in YAML files → legacy specsemantic_model: block nested under a model → latest specIf semantic layer already exists:
uvx dbt-autofix deprecations --semantic-layer or the migration guide. They don't have to upgrade; continuing with legacy is fine.If no semantic layer exists:
Once you know which spec to use, follow the corresponding guide's implementation workflow (Steps 1-4) for all YAML authoring. The guides are self-contained with full examples.
Users may ask questions related to building metrics with the semantic layer in a few different ways. Here are the common entry points to look out for:
When the user describes a metric or analysis need (e.g., "I need to track customer lifetime value by segment"):
When the user specifies a model to expose (e.g., "Add semantic layer to customers model"):
Both paths converge on the same implementation workflow.
User asks to build the semantic layer for a project or models that are not specified. ("Build the semantic layer for my project")
Both specs support these metric types. For YAML syntax, see the spec-specific guides.
Directly aggregate a single column expression. The most common metric type and the building block for all others.
metrics: on the model with type: simple, agg, and exprmetrics: referencing a measure via type_params.measureCombine multiple metrics using a mathematical expression. Use for calculations like profit (revenue - cost) or growth rates (period-over-period with offset_window).
Aggregate a metric over a running window or grain-to-date period. Requires a time spine. Use for running totals, trailing windows (e.g., 7-day rolling average), or period-to-date (MTD, YTD).
Note: window and grain_to_date cannot be used together on the same cumulative metric.
Create a ratio between two metrics (numerator / denominator). Use for conversion rates, percentages, and proportions. Both numerator and denominator can have optional filters.
Measure how often one event leads to another for a specific entity within a time window. Use for funnel analysis (e.g., visit-to-purchase conversion rate). Supports constant_properties to ensure the same dimension value across both events.
Filters can be added to simple metrics or metric inputs to advanced metrics. Use Jinja template syntax: