MetricFlow is the SQL generation engine behind the dbt semantic layer. Metrics are defined once in YAML and MetricFlow translates them into warehouse-native SQL. Setting up a working semantic layer requires several moving parts, each documented in a dedicated note below.
Setup sequence
MetricFlow installation and setup — Where to start. Adapter-specific pip packages for dbt Core, the built-in dbt Cloud path, and the two project-level prerequisites (time spine config, semantic manifest) that need to be in place before anything else works.
MetricFlow time spine — A continuous date table that MetricFlow joins against for cumulative metrics and time series gap filling. Required for any metric that uses rolling windows or grain_to_date. Worth setting up early even if you don’t have those metrics yet.
MetricFlow semantic model components — The building blocks of a semantic model: entities (join keys that connect models), dimensions (columns you group and filter by), and measures (aggregations that feed metrics). One semantic model per mart model. Everything else in the semantic layer depends on getting these right.
MetricFlow Metric Types — The five metric types MetricFlow supports: simple, cumulative, derived, ratio, and conversion. Each solves a specific problem. Ratio metrics exist specifically to avoid the sum-of-ratios error that derived metrics produce silently when grouped by a dimension.
MetricFlow CLI querying — How to query metrics from the terminal with mf query (Core) or dbt sl query (Cloud). The Jinja dimension reference syntax for filters, controlling time granularity, and how to validate configs before querying.
Metric Organization in dbt Projects — Where to put your semantic model and metric YAML files. Co-located structure for small projects, parallel subfolder structure for larger ones. The one-primary-entity rule and why semantic models should reference mart models instead of intermediates.
Going further
Once the basics are working:
MetricFlow Advanced Patterns — Period-over-period comparisons with offset_window, filtered segment metrics using the Dimension() Jinja syntax, and handling null gaps in time series output.
Metrics as Code — The broader practice: why keeping metric definitions in version-controlled YAML changes the governance model, what the PR review workflow looks like for metric changes, and how this feeds AI-powered analytics tools with a governed vocabulary.
Semantic Layer Architecture — Context on where MetricFlow sits in the landscape alongside Snowflake Semantic Views and Databricks Metric Views, and why the semantic layer is the prerequisite for reliable AI-generated queries.