Define a MetricFlow semantic model in YAML with primary, foreign, and unique entity types to enable automatic join resolution
domain: docs.getdbt.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Create a YAML file alongside your dbt model and add a semantic_models block with a name, model ref, and description
Under entities, declare one primary entity (type: primary) with the column that uniquely identifies each row, then add foreign entities (type: foreign) referencing join keys to other semantic models
Add a unique entity (type: unique) for columns that are unique per row but are not the primary key of the semantic model when needed
Define measures with agg (e.g., sum, count_distinct) and dimensions with type: categorical or type: time to complete the semantic model
Run dbt parse and then dbt sl list metrics to confirm MetricFlow resolves the semantic graph without errors
Known gotchas
Each semantic model should have exactly one primary entity; MetricFlow uses entity types to infer join cardinality and will raise an error if multiple primary entities exist in one model
MetricFlow avoids fan-out and chasm joins automatically based on entity types, so misclassifying a foreign key as primary can produce silently incorrect aggregations
Entity names must match exactly across semantic models for MetricFlow to wire up the join graph; a typo in the name will result in unresolvable dimensions at query time
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?