// 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.
Formats and executes dbt CLI commands, selects the correct dbt executable, and structures command parameters. Use when running models, tests, builds, compiles, or show queries via dbt CLI. Use when unsure which dbt executable to use or how to format command parameters.
Generates a Mermaid flowchart diagram of dbt model lineage using MCP tools, manifest.json, or direct code parsing as fallbacks. Use when visualizing dbt model lineage and dependencies as a Mermaid diagram in markdown format.
Use when a user needs help triaging dbt-core to Fusion migration errors. Runs dbt-autofix first, then classifies remaining errors into actionable categories (auto-fixable, guided fixes, needs input, blocked).
Use when migrating a dbt project from one data platform or data warehouse to another (e.g., Snowflake to Databricks, Databricks to Snowflake) using dbt Fusion's real-time compilation to identify and fix SQL dialect differences.
Creates unit test YAML definitions that mock upstream model inputs and validate expected outputs. Use when adding unit tests for a dbt model or practicing test-driven development (TDD) in dbt.
Implements dbt Mesh governance features (model contracts, access modifiers, groups, versioning) and multi-project collaboration with cross-project refs. Use when implementing dbt Mesh governance, setting up cross-project refs with dependencies.yml, disambiguating similarly-named models across projects, or splitting a monolithic dbt project into multiple mesh projects.
| name | building-dbt-semantic-layer |
| description | 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. |
| user-invocable | false |
| metadata | {"author":"dbt-labs"} |
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.
Minimal latest spec example (dbt Core 1.12+ / Fusion) — use this as your starting point to avoid guessing the structure:
# models/fct_orders.yml
models:
- name: fct_orders
semantic_model:
agg_time_dimension: order_date
entities:
- name: order
type: primary
expr: order_id
- name: customer
type: foreign
expr: customer_id
dimensions:
- name: order_date
type: time
type_params:
time_granularity: day
- name: status
type: categorical
measures:
- name: revenue
agg: sum
expr: amount
metrics:
- name: total_revenue
type: simple
label: Total Revenue
type_params:
measure: revenue
Minimal legacy spec example (dbt Core 1.6–1.11) — use this if the project is on an older version:
# models/sem_orders.yml
semantic_models:
- name: orders
model: ref('fct_orders')
entities:
- name: order
type: primary
expr: order_id
dimensions:
- name: order_date
type: time
type_params:
time_granularity: day
measures:
- name: revenue
agg: sum
expr: amount
metrics:
- name: total_revenue
type: simple
label: Total Revenue
type_params:
measure: revenue
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:
filter: |
{{ Entity('entity_name') }} = 'value'
filter: |
{{ Dimension('primary_entity__dimension_name') }} > 100
filter: |
{{ TimeDimension('time_dimension', 'granularity') }} > '2026-01-01'
filter: |
{{ Metric('metric_name', group_by=['entity_name']) }} > 100
Important: Filter expressions can only reference columns that are declared as dimensions or entities in the semantic model. Raw table columns that aren't defined as dimensions cannot be used in filters — even if they appear in a measure's expr.
This skill references dbt-autofix, a first-party tool maintained by dbt Labs for automating deprecation fixes and package updates.
After writing YAML, validate in two stages:
dbt parse (or dbtf parse for Fusion) to confirm YAML syntax and referencesdbt sl validate (dbt Cloud CLI or Fusion CLI when using the dbt platform)mf validate-configs (MetricFlow CLI)Important: mf validate-configs reads from the compiled manifest, not directly from YAML files. If you've edited YAML since the last parse, you must run dbt parse (or dbtf parse) again before mf validate-configs will see the changes.
Note: When using Fusion with MetricFlow locally (without the dbt platform), dbtf parse will show warning: dbt1005: Skipping semantic manifest validation due to: No dbt_cloud.yml config. This is expected — use mf validate-configs for semantic layer validation in this setup.
Do not consider work complete until both validations pass.
When modifying existing semantic layer config:
| Pitfall | Fix |
|---|---|
| Missing time dimension | Every semantic model with metrics/measures needs a default time dimension |
Using window and grain_to_date together | Cumulative metrics can only have one |
| Mixing spec syntax | Don't use type_params in latest spec or direct keys in legacy spec |
| Filtering on non-dimension columns | Filter expressions can only use declared dimensions/entities, not raw columns |
mf validate-configs shows stale results | Re-run dbt parse / dbtf parse first to regenerate the manifest |
MetricFlow install breaks dbt-semantic-interfaces | Install dbt-metricflow (not bare metricflow) to get compatible dependency versions |