dbt Semantic Layer and MetricFlow, compared with a semantic layer in code
How dbt defines metrics after the 2026 spec changes, how they are queried and priced, which warehouses they run on, and how the same model looks when it is defined in application code instead.
Definition
What are the dbt Semantic Layer and MetricFlow?
The dbt Semantic Layer is dbt Labs’ service for defining metrics in YAML next to your dbt models and querying them by name, from BI tools, spreadsheets, notebooks and AI agents. You ask for revenue by customer country; it writes the joins and the SQL.
MetricFlow is the engine underneath: it reads the YAML and compiles metric requests into SQL for your warehouse. MetricFlow is open source under Apache 2.0. The hosted Semantic Layer, with its APIs and integrations, is part of the paid dbt platform.
How it works
Semantic models, metrics and queries
A semantic model sits on top of one dbt model. It names the table’s entities (primary, foreign, unique or natural keys, which is how MetricFlow finds joins) and its dimensions (categorical or time). Metrics come in five types: simple, ratio, cumulative, derived and conversion.
The latest spec, used by the dbt platform, dbt v2 and dbt v1.12, deprecates measures in favour of simple metrics, moves the semantic model inside each model entry and puts entities and dimensions under columns. dbt-autofix deprecations --semantic-layer migrates older YAML. dbt v1.12 can also read semantic models from Apache Ossie (OSI) files.
The customer__country group-by assumes a customers model with a primary entity named customer and a country dimension. Add --compile (dbt) or --explain (mf) to see the generated SQL.
Facts to know
Where the dbt Semantic Layer stands in late 2026
New names
In September 2026 dbt renamed the Fusion engine to “dbt” (v2). The Apache-licensed subset is dbt OSS, and the 1.x line is dbt v1, or dbt Core.
Open-source engine
MetricFlow is Apache 2.0 from version 0.209.0. Without a platform plan you can define and query metrics from the CLI, but you get no APIs or integrations.
Paid APIs
GraphQL, JDBC and the Python SDK come with Starter ($100 per user per month, 5,000 queried metrics a month) and above. Caching is Enterprise only.
ClickHouse
Not supported by the hosted Semantic Layer. MetricFlow merged experimental ClickHouse SQL on September 29, 2026; it is not released, and FINAL for ReplacingMergeTree is out of scope.
The same model in code
The orders model as a code-defined semantic layer
Here is the same model as a hypequery dataset: one file in your application repo, imported by the backend that serves your product. It adds the one thing the dbt version leaves to the warehouse, a tenant key, so each request only sees one customer’s rows.
| dbt / MetricFlow | hypequery | Notes |
|---|---|---|
| Semantic model | Dataset | One per table. source is the table. |
| Primary and foreign entities | Relationships: belongsTo, hasOne | Declared on the dataset; to-one joins run one hop deep. |
| Categorical and time dimensions | dimension.string(), dimension.timestamp(), timeKey | The time key plays the part of agg_time_dimension. |
| Simple metric (agg + expr) | measure.sum(), measure.count() and friends | TypeScript checks declared measure names in queries, not backing column names; those are checked when the query runs. |
| Ratio and derived metrics | measure.derived() | Formulas use symbolic helpers such as divide() and nullIfZero(), not SQL strings. |
| Cumulative metrics | measure.cumulative(), trailing(), toDate() | Running totals, trailing windows and month-to-date. |
| Conversion metrics | No direct equivalent | Write the funnel as its own dataset or query. |
| metric_time__month | by: 'month' | Grains from minute to year. |
| Saved queries | A function or a Serve endpoint | Named, versioned with the code that calls it. |
| Semantic Layer APIs | Serve HTTP API, React hooks, MCP server | Run in your own backend. |
Comparison
dbt Semantic Layer vs a semantic layer in code
Checked against dbt’s docs and pricing page on November 10, 2026.
| dbt Semantic Layer | Code-defined (hypequery) | |
|---|---|---|
| Where definitions live | YAML in the dbt project, next to the models that build the tables | TypeScript or Python in your application repo |
| Who usually owns them | Analytics engineers | Application engineers |
| How consumers query | GraphQL, JDBC (Arrow Flight SQL) and Python APIs; integrations for Tableau, Power BI, Excel, Google Sheets, Hex, Sigma and others; dbt MCP server | Direct calls in your backend, a typed HTTP API, React hooks and an MCP server |
| Databases | Hosted: Snowflake, BigQuery, Databricks, Redshift, Postgres, Trino. MetricFlow merged experimental ClickHouse support on September 29, 2026; it is not in a release yet | ClickHouse, including FINAL for ReplacingMergeTree tables |
| Per-customer data | Queries run with the credentials configured for the Semantic Layer; rows are restricted by warehouse policies on those credentials | A tenant key on the dataset, filled from the authenticated session; a query without it fails |
| Types | Validated when the project is parsed | Checked by the TypeScript compiler from dataset to response row |
| What you run | The dbt platform hosts the APIs. MetricFlow alone gives you a CLI, not an API | A library inside your existing backend |
| Price | Starter $100 per user per month with 5,000 queried metrics a month; Enterprise 20,000. MetricFlow is free | Apache 2.0, free |
An honest answer
When the dbt Semantic Layer is the better choice
- Your tables are already built in dbt on a supported warehouse, and analytics engineers own the metrics.
- The consumers are BI tools and spreadsheets: Tableau, Power BI, Excel, Google Sheets, Hex, Sigma.
- You need conversion metrics, which a code-defined layer does not model directly.
- Metrics are for internal reporting, where warehouse credentials and policies are the right access model.
Define metrics in code when they serve your own product: customer-facing dashboards, a public API or an in-app agent, where each request belongs to one customer and your backend already knows which one. Many teams use both: dbt builds the tables, and the application layer defines what customers see. The TypeScript vs dbt guide covers that split on ClickHouse.
Questions
dbt Semantic Layer FAQ
What is the dbt Semantic Layer?
The dbt Semantic Layer lets you define metrics in YAML on top of your dbt models and query them by name through APIs and BI integrations. dbt works out the joins. It is a paid feature of the dbt platform and is powered by MetricFlow.
Is MetricFlow open source?
Yes. dbt Labs announced at Coalesce in October 2025 that MetricFlow would be relicensed under Apache 2.0, and releases from 0.209.0 onward are Apache 2.0. Earlier versions were AGPL and then BSL. The hosted dbt Semantic Layer that runs on top of it remains proprietary.
What does the dbt Semantic Layer cost?
It is included from the Starter plan, $100 per user per month, which allows 5,000 queried metrics a month. Enterprise and Enterprise+ are custom priced and allow 20,000. The free Developer plan does not list it. You can run MetricFlow from the command line for free, without the APIs.
Does the dbt Semantic Layer support ClickHouse?
Not the hosted Semantic Layer: dbt lists Snowflake, BigQuery, Databricks, Redshift, Postgres and Trino. Open-source MetricFlow merged experimental ClickHouse support on September 29, 2026, after its latest release, and that change leaves out FINAL handling for ReplacingMergeTree tables.
What changed in the new dbt metrics spec?
Measures are deprecated and replaced with simple metrics, the semantic model sits inside each model entry, entities and dimensions move under columns, and type_params is gone. dbt-autofix deprecations --semantic-layer migrates existing YAML.
Can AI agents query dbt metrics?
Yes. The dbt MCP server, self-hosted or remote, exposes Semantic Layer tools to MCP clients such as Claude. Which tools are available depends on the APIs your dbt plan includes.
Guides
More on semantic layers
What is a semantic layer
What a semantic layer is, the five places one can live, and how dbt MetricFlow, Snowflake semantic views, Databricks metric views and OSI compare with a layer defined in code.
Read
Snowflake semantic views
CREATE SEMANTIC VIEW, the SEMANTIC_VIEW() query and Cortex Analyst, compared with a semantic layer defined in code.
Read
Databricks metric views
Unity Catalog metric views in YAML, the MEASURE() function and Genie, compared with a semantic layer defined in code.
Read
Open Semantic Interchange (OSI)
The vendor-neutral spec for exchanging semantic models: who is behind it, what the format covers and what it leaves out.
Read
ClickHouse semantic layer
Define datasets, measures and tenant keys for ClickHouse in TypeScript or Python.
Read
hypequery vs Cube
A code-first library compared with a standalone semantic layer service.
Read
Sources
Vendor pages used for this page, all read on November 10, 2026.
- dbt docs
- docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl
- docs.getdbt.com/docs/build/about-metricflow
- docs.getdbt.com/docs/build/latest-metrics-spec
- docs.getdbt.com/docs/build/metrics-overview
- docs.getdbt.com/docs/build/metricflow-commands
- docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc
- docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations
- docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs
- docs.getdbt.com/docs/dbt-ai/about-mcp
Next step
Define a semantic layer in your own codebase
hypequery datasets are TypeScript or Python files: dimensions, measures, joins and a tenant key, served to your API, React hooks and AI agents over MCP. Open source, for ClickHouse.