The Mental Model
MetricFlow powers the dbt Semantic Layer by using semantic model and metric definitions to generate SQL dynamically for requested metrics and dimensions.
You define the rules once. MetricFlow acts like a careful translator that writes the SQL for each question using those rules.
Dataset reference: ecommerce tables and grain assumptions.
Review a semantic query plan
Use this conceptual plan to review a MetricFlow query. It is a design checklist, not a version-specific YAML configuration.
| Definition | Example | Review question |
|---|---|---|
| Entity | order and customer | Which side is unique? |
| Measure | Sum of net_amount | Is the input already at order grain? |
| Time dimension | order_date | Which timezone and day boundary apply? |
| Group-by dimension | customer country | Current country or country at order time? |
Compile a query for the same two-country fixture from the previous lesson and inspect the joins in the generated SQL. Compare its result with the hand-checked totals before exposing it to dashboards. Central generation makes a definition reusable; an incorrect definition can still produce consistently incorrect results.
Acceptance check: no many-to-many join is introduced, and adding a second measure does not change the first measure's total.
Interactive Check
Question: Why is generated SQL safer than each dashboard author writing their own revenue SQL?
Reveal the answer
The generated SQL comes from one governed metric definition, so all tools use the same calculation, joins, and time rules.
Practice: Read a Semantic Model YAML
Identify entities, measures, dimensions, and metrics in a simplified YAML snippet.
Use the guided lab below to record your result, assumptions, and the check that would catch an incorrect result.