The dbt Semantic Layer lets you define metrics once in YAML inside your dbt project, and MetricFlow compiles any metric-plus-dimension request into SQL for your warehouse. The engine is open source (Apache 2.0) and free to run locally. Serving those metrics to BI tools and AI agents through dbt’s APIs requires a paid dbt platform plan, starting with Starter at $100 per user per month.

A lot has changed in the past year. MetricFlow went open source, dbt v2 reached general availability, and dbt introduced a new YAML spec that retires measures. Most tutorials, including the ones ranking above this page, still show the old syntax. This guide is updated for October 2026: what you get on each plan, a copy-paste MetricFlow walkthrough on the latest spec, and what the 2026 benchmark says about using the semantic layer with AI agents.

What the dbt Semantic Layer Is (and What MetricFlow Does)

The dbt Semantic Layer is dbt’s take on a semantic layer: a governed set of metric definitions that lives in your dbt project. You describe entities, dimensions, and metrics in YAML, and every downstream tool queries metrics by name instead of writing its own SQL. MetricFlow is the engine underneath. It reads those definitions, works out the joins, and generates SQL for your warehouse.

Semantic Models, Entities, Dimensions, and Metrics

• Semantic model: Metadata attached to one dbt model that tells MetricFlow how to use it. (The term means something different in Power BI; see what a semantic model is across tools.)

• Entities: The join keys. A primary entity identifies rows in this model; a foreign entity points to another model. MetricFlow uses them to build joins automatically.

• Dimensions: What you group and filter by, either categorical (plan tier, region) or time (ordered_at).

• Metrics: What you measure. In the latest spec, a simple metric declares its own aggregation (agg: sum) and expression, so the separate measures block is gone.

How a Metric Request Becomes SQL

A BI tool or agent asks for revenue grouped by metric_time__month. The dbt platform’s service layer passes the request to MetricFlow. MetricFlow looks up the metric, finds the join path through entities, and compiles optimized SQL for your warehouse dialect. The warehouse runs it, and the result comes back with the governed definition attached.

Common misconception: the dbt Semantic Layer does not translate natural language. It compiles metric requests into SQL. Turning “how did revenue trend last quarter?” into a metric request is the job of an LLM or agent sitting on top.

Is the dbt Semantic Layer Free? What You Get on Each Plan

Partly. The open-source pieces (MetricFlow and the semantic interface spec) are free everywhere. The hosted service layer and APIs are proprietary and paid. dbt’s architecture docs and pricing page break it down:

What Counts as a “Queried Metric”

Billing is per metric, not per query. Under dbt’s billing rules, each successful API request counts at least one, and each calculated metric counts. So dbt sl query --metrics revenue,gross_sales counts as two. Compiling SQL with --compile counts too. Errors and metadata requests don’t.

This matters if you plan to put an agent on top. A single agent conversation that explores five metrics across three follow-ups can consume 15 queried metrics, so a team asking hundreds of questions a week can exhaust the Starter allowance quickly. That’s our inference from the billing rules, not a dbt figure, but it’s worth modeling before you roll out.

Does dbt Core Support the Semantic Layer?

Yes for authoring and local querying, no for the APIs. Install dbt-metricflow, define metrics in your project, and query them with mf commands. You can’t serve them to BI tools or agents through dbt’s APIs without a platform plan.

A note on naming: dbt Core is now “dbt v1.” The Rust-based Fusion engine reached general availability as plain “dbt” (v2) in September 2026, with an Apache 2.0 distribution called dbt OSS. dbt Cloud is now “the dbt platform.”

What Changed in 2025–2026

If you last looked at the dbt Semantic Layer in 2024, four things are different:

1. MetricFlow is open source. It was relicensed from BSL to Apache 2.0 on October 14, 2025. As dbt put it, “Metrics should not be probabilistic or depend on an LLM guessing each calculation.”

2. dbt v2 is GA. It parses large projects several times faster than v1.12, and it supports the latest semantic layer spec.

3. A new YAML spec. Supported in dbt v1.12+ and v2, the latest metrics spec nests semantic_model under each model, moves entities and dimensions under columns, replaces measures with simple metrics, and deprecates type_params.

4. OSI became Apache Ossie. The Open Semantic Interchange, launched by Snowflake, Salesforce, dbt Labs, and others in September 2025, entered the Apache Incubator as Apache Ossie in July 2026. dbt v1.12 can already read Ossie documents as an alternative to native YAML.

Here’s the difference in practice:

# LEGACY (dbt ≤ 1.11): what most tutorials still show
semantic_models:
-name: customers
model: ref('customers')
measures:
-name: lifetime_spend_pretax
agg: sum
metrics:
-name: lifetime_spend_pretax
type: simple
type_params:
measure

# LEGACY (dbt ≤ 1.11): what most tutorials still show
semantic_models:
-name: customers
model: ref('customers')
measures:
-name: lifetime_spend_pretax
agg: sum
metrics:
-name: lifetime_spend_pretax
type: simple
type_params:
measure

# LEGACY (dbt ≤ 1.11): what most tutorials still show
semantic_models:
-name: customers
model: ref('customers')
measures:
-name: lifetime_spend_pretax
agg: sum
metrics:
-name: lifetime_spend_pretax
type: simple
type_params:
measure

# LEGACY (dbt ≤ 1.11): what most tutorials still show
semantic_models:
-name: customers
model: ref('customers')
measures:
-name: lifetime_spend_pretax
agg: sum
metrics:
-name: lifetime_spend_pretax
type: simple
type_params:
measure

# LATEST (dbt v1.12+ and v2)
models:
-name: customers
semantic_model:
enabled:true
metrics:
-name: lifetime_spend_pretax
type: simple
agg: sum
expr

# LATEST (dbt v1.12+ and v2)
models:
-name: customers
semantic_model:
enabled:true
metrics:
-name: lifetime_spend_pretax
type: simple
agg: sum
expr

# LATEST (dbt v1.12+ and v2)
models:
-name: customers
semantic_model:
enabled:true
metrics:
-name: lifetime_spend_pretax
type: simple
agg: sum
expr

# LATEST (dbt v1.12+ and v2)
models:
-name: customers
semantic_model:
enabled:true
metrics:
-name: lifetime_spend_pretax
type: simple
agg: sum
expr

To migrate an existing project, run dbt-autofix deprecations --semantic-layer, review the diff, then dbt parse and mf validate-configs. One limitation: cross-project references are still only supported in the legacy spec.

MetricFlow Walkthrough: From Zero to Your First Metric Query

This walkthrough uses dbt Labs’ own jaffle-shop reference project, which already uses the latest spec. The YAML below is taken from that repo, trimmed for length.

Step 1: Install MetricFlow

python -m venv venv && source venv/bin/activate
python -m pip install "dbt-metricflow[dbt-snowflake]"   # swap in your adapter, e.g. dbt-bigquery
git clone <https://github.com/dbt-labs/jaffle-shop.git> && cd

python -m venv venv && source venv/bin/activate
python -m pip install "dbt-metricflow[dbt-snowflake]"   # swap in your adapter, e.g. dbt-bigquery
git clone <https://github.com/dbt-labs/jaffle-shop.git> && cd

python -m venv venv && source venv/bin/activate
python -m pip install "dbt-metricflow[dbt-snowflake]"   # swap in your adapter, e.g. dbt-bigquery
git clone <https://github.com/dbt-labs/jaffle-shop.git> && cd

python -m venv venv && source venv/bin/activate
python -m pip install "dbt-metricflow[dbt-snowflake]"   # swap in your adapter, e.g. dbt-bigquery
git clone <https://github.com/dbt-labs/jaffle-shop.git> && cd

Use Python 3.10–3.12. Note that jaffle-shop’s dbt_project.yml sets require-dbt-version: ">=2.0.0". If you’re running dbt v1.12, adjust that line.

Step 2: Add a Time Spine

MetricFlow needs a time spine (at minimum, a daily one) for cumulative metrics, offsets, and conversion metrics. jaffle-shop builds one with dbt.date_spine and declares it like this:

models:
-name: metricflow_time_spine
description: Time spine model used by MetricFlow for temporal joins and aggregations.
time_spine:
standard_granularity_column: date_day
columns:
-name: date_day
granularity

models:
-name: metricflow_time_spine
description: Time spine model used by MetricFlow for temporal joins and aggregations.
time_spine:
standard_granularity_column: date_day
columns:
-name: date_day
granularity

models:
-name: metricflow_time_spine
description: Time spine model used by MetricFlow for temporal joins and aggregations.
time_spine:
standard_granularity_column: date_day
columns:
-name: date_day
granularity

models:
-name: metricflow_time_spine
description: Time spine model used by MetricFlow for temporal joins and aggregations.
time_spine:
standard_granularity_column: date_day
columns:
-name: date_day
granularity

Step 3: Define a Semantic Model and Simple Metrics

Simple metrics live on the model they aggregate. From models/marts/order_items.yml:

models:
-name: order_items
description: Items contained in each order. One row per order item.
semantic_model:
enabled:true
agg_time_dimension: ordered_at
columns:
-name: order_item_id
entity:
type: primary
name: order_item
-name: order_id
entity:
type: foreign
name: order_id
-name: ordered_at
granularity: day
dimension:
type: time
-name: is_food_item
dimension:
type: categorical
metrics:
-name: revenue
label: Revenue
type: simple
agg: sum
expr: product_price
-name: food_revenue
label: Food Revenue
type: simple
agg: sum
expr:"case when is_food_item then product_price else 0 end"

models:
-name: order_items
description: Items contained in each order. One row per order item.
semantic_model:
enabled:true
agg_time_dimension: ordered_at
columns:
-name: order_item_id
entity:
type: primary
name: order_item
-name: order_id
entity:
type: foreign
name: order_id
-name: ordered_at
granularity: day
dimension:
type: time
-name: is_food_item
dimension:
type: categorical
metrics:
-name: revenue
label: Revenue
type: simple
agg: sum
expr: product_price
-name: food_revenue
label: Food Revenue
type: simple
agg: sum
expr:"case when is_food_item then product_price else 0 end"

models:
-name: order_items
description: Items contained in each order. One row per order item.
semantic_model:
enabled:true
agg_time_dimension: ordered_at
columns:
-name: order_item_id
entity:
type: primary
name: order_item
-name: order_id
entity:
type: foreign
name: order_id
-name: ordered_at
granularity: day
dimension:
type: time
-name: is_food_item
dimension:
type: categorical
metrics:
-name: revenue
label: Revenue
type: simple
agg: sum
expr: product_price
-name: food_revenue
label: Food Revenue
type: simple
agg: sum
expr:"case when is_food_item then product_price else 0 end"

models:
-name: order_items
description: Items contained in each order. One row per order item.
semantic_model:
enabled:true
agg_time_dimension: ordered_at
columns:
-name: order_item_id
entity:
type: primary
name: order_item
-name: order_id
entity:
type: foreign
name: order_id
-name: ordered_at
granularity: day
dimension:
type: time
-name: is_food_item
dimension:
type: categorical
metrics:
-name: revenue
label: Revenue
type: simple
agg: sum
expr: product_price
-name: food_revenue
label: Food Revenue
type: simple
agg: sum
expr:"case when is_food_item then product_price else 0 end"

Step 4: Add Ratio, Derived, and Cumulative Metrics

Metrics built from other metrics go in a top-level metrics: key in the same file:

metrics:
-name: food_revenue_pct
description: The % of order revenue from food.
label: Food Revenue %
type: ratio
numerator: food_revenue
denominator: revenue

-name: revenue_growth_mom
description:"Percentage growth of revenue compared to 1 month ago. Excludes tax."
type: derived
label: Revenue Growth % M/M
expr: (current_revenue - revenue_prev_month)*100/revenue_prev_month
input_metrics:
-name: revenue
alias: current_revenue
-name: revenue
offset_window: 1 month
alias: revenue_prev_month

-name: cumulative_revenue
description: The cumulative revenue for all orders.
label: Cumulative Revenue (All Time)
type: cumulative
input_metric

metrics:
-name: food_revenue_pct
description: The % of order revenue from food.
label: Food Revenue %
type: ratio
numerator: food_revenue
denominator: revenue

-name: revenue_growth_mom
description:"Percentage growth of revenue compared to 1 month ago. Excludes tax."
type: derived
label: Revenue Growth % M/M
expr: (current_revenue - revenue_prev_month)*100/revenue_prev_month
input_metrics:
-name: revenue
alias: current_revenue
-name: revenue
offset_window: 1 month
alias: revenue_prev_month

-name: cumulative_revenue
description: The cumulative revenue for all orders.
label: Cumulative Revenue (All Time)
type: cumulative
input_metric

metrics:
-name: food_revenue_pct
description: The % of order revenue from food.
label: Food Revenue %
type: ratio
numerator: food_revenue
denominator: revenue

-name: revenue_growth_mom
description:"Percentage growth of revenue compared to 1 month ago. Excludes tax."
type: derived
label: Revenue Growth % M/M
expr: (current_revenue - revenue_prev_month)*100/revenue_prev_month
input_metrics:
-name: revenue
alias: current_revenue
-name: revenue
offset_window: 1 month
alias: revenue_prev_month

-name: cumulative_revenue
description: The cumulative revenue for all orders.
label: Cumulative Revenue (All Time)
type: cumulative
input_metric

metrics:
-name: food_revenue_pct
description: The % of order revenue from food.
label: Food Revenue %
type: ratio
numerator: food_revenue
denominator: revenue

-name: revenue_growth_mom
description:"Percentage growth of revenue compared to 1 month ago. Excludes tax."
type: derived
label: Revenue Growth % M/M
expr: (current_revenue - revenue_prev_month)*100/revenue_prev_month
input_metrics:
-name: revenue
alias: current_revenue
-name: revenue
offset_window: 1 month
alias: revenue_prev_month

-name: cumulative_revenue
description: The cumulative revenue for all orders.
label: Cumulative Revenue (All Time)
type: cumulative
input_metric

For a rolling or month-to-date version of a cumulative metric, add window: 7 days or grain_to_date: month (not both).

Step 5: Validate and Query Locally (Free)

dbt parse                       # builds semantic_manifest.json
mf validate-configs
mf list metrics
mf list dimensions --metrics revenue
mf query --metrics revenue,food_revenue_pct --group-by metric_time__month
mf query --metrics revenue --group-by metric_time --order-by -metric_time --limit 10 --compile

dbt parse                       # builds semantic_manifest.json
mf validate-configs
mf list metrics
mf list dimensions --metrics revenue
mf query --metrics revenue,food_revenue_pct --group-by metric_time__month
mf query --metrics revenue --group-by metric_time --order-by -metric_time --limit 10 --compile

dbt parse                       # builds semantic_manifest.json
mf validate-configs
mf list metrics
mf list dimensions --metrics revenue
mf query --metrics revenue,food_revenue_pct --group-by metric_time__month
mf query --metrics revenue --group-by metric_time --order-by -metric_time --limit 10 --compile

dbt parse                       # builds semantic_manifest.json
mf validate-configs
mf list metrics
mf list dimensions --metrics revenue
mf query --metrics revenue,food_revenue_pct --group-by metric_time__month
mf query --metrics revenue --group-by metric_time --order-by -metric_time --limit 10 --compile

The --compile flag prints the SQL MetricFlow generates, which is the fastest way to build trust with skeptical analysts. On the dbt platform, the same commands are dbt sl validate, dbt sl list metrics, and dbt sl query, and each successful query counts toward your plan’s queried metrics.

Step 6: Deploy and Connect

Run a deploy job so the dbt platform has your semantic manifest, then create Semantic Layer credentials with a least-privileged service token. From there, connect BI tools through the native integrations or an agent through the dbt MCP server.

The Five MetricFlow Metric Types

Simple metrics can only be defined on a model. The other four go at the top level when they span models. If you’re weighing a dedicated metrics layer vs a full semantic layer, MetricFlow is both: metrics defined on top of semantic models.

Connecting BI Tools and AI Agents

The dbt platform offers 12 native integrations, including Power BI, Tableau, Google Sheets, Excel, Hex, Mode, Omni, and Sigma (preview). There’s no native Looker integration. Custom tools can connect through JDBC, ADBC, GraphQL, or the Python SDK.

For AI agents, the path is the dbt MCP server. It runs locally (uvx dbt-mcp) or as a remote server, and it exposes semantic layer tools such as list_metrics, get_dimensions, query_metrics, and get_metrics_compiled_sql. An agent in Claude, Cursor, or VS Code can then ask for a metric by name and get governed SQL back rather than writing its own.

Does a Semantic Layer Make AI Agents Accurate? What the 2026 Benchmark Shows

dbt Labs reran its 2023 benchmark in April 2026 on the same insurance dataset, with 11 questions run 20 times each:

• On questions the semantic layer could answer, it scored 100% with both Claude Sonnet 4.6 and GPT-5.3 Codex, compared with 62.5% and 51.2% for text-to-SQL.

• Across all questions before extra modeling, it scored 72.7%, compared with 64.5% for text-to-SQL. The semantic layer refused questions that needed too many entity hops, which is exactly where a data ontology earns its keep.

• After adding three dbt models, the semantic layer reached 98.2% and 100%. Text-to-SQL also improved, to 90.0% and 84.1%.

The headline isn’t that the semantic layer is perfect. It’s how it fails. In dbt’s words, the semantic layer “never returns invalid data. Text-to-SQL will cheerfully give you a wrong number.” Keep the caveats in mind: 11 questions, one dataset, and a vendor-run test.

The real constraint is coverage. A semantic layer is exact on what you’ve modeled and silent on everything else. Most agent questions in the first months land in “everything else.”

When the dbt Semantic Layer Is the Wrong Tool

The dbt Semantic Layer is excellent for governed, board-level metrics. It’s a poor fit when:

• Your warehouse isn’t supported. It works with Snowflake, BigQuery, Databricks, Redshift, Postgres, and Trino, but not Microsoft Fabric.

• You rely on cross-project references. These still require the legacy YAML spec.

• Coverage is low. If only a fraction of the questions people ask map to modeled metrics, an agent will refuse most of them.

• YAML sprawl is already a problem. Every metric is another definition to own, review, and keep in sync with upstream changes.

• Queried-metric volume is unpredictable. Agent workloads multiply metric calls, which affects cost on Starter.

If several of these apply, compare alternatives like the Cube semantic layer or the other options in our semantic layer tools comparison.

Don’t Have a Semantic Layer Yet? You Can Still Ship a Reliable Agent

The 2026 benchmark points to a practical setup: governed metrics where you have them, and a context layer everywhere else. That’s how Upsolve Data Models works:

• Already on MetricFlow? Bring your dbt project into Upsolve, and your models and metrics become agent context.

• Not yet? No semantic layer is required. Register your warehouse tables with descriptions and keys (essentially a data dictionary your agent can read), encode canonical definitions in a versioned system prompt, and mark columns as selectable so allowed values are pre-cached nightly.

Either way, the agent uses one definition of each metric, and you add definitions as real questions expose gaps.

Frequently Asked Questions

Is the dbt Semantic Layer free?

Partly. MetricFlow and the metric spec are open source under Apache 2.0, so defining metrics and querying them from the command line is free. The APIs, BI integrations, and exports require a dbt Starter plan ($100/user/month with 5,000 queried metrics) or Enterprise (20,000 queried metrics, plus caching).

Does dbt Core support the semantic layer?

Yes for authoring and local querying. Install dbt-metricflow, define metrics in YAML, and use mf commands. dbt Core (now called dbt v1) can’t serve metrics through dbt’s APIs or integrations; that requires a dbt platform plan.

Is dbt MetricFlow open source?

Yes. dbt Labs relicensed MetricFlow under Apache 2.0 on October 14, 2025, as part of its commitment to the Open Semantic Interchange (now Apache Ossie). Earlier versions were under BSL and AGPL licenses.

What is the difference between MetricFlow and the dbt Semantic Layer?

MetricFlow is the open-source engine and spec that compiles metric definitions into SQL. The dbt Semantic Layer is the hosted service on the dbt platform that adds APIs, integrations, exports, caching, and governance on top of MetricFlow.

Which data warehouses does the dbt Semantic Layer support?

Snowflake, BigQuery, Databricks, Redshift, Postgres, and Trino. Microsoft Fabric isn’t supported, per dbt’s FAQ.

How is the dbt Semantic Layer different from Snowflake semantic views?

The dbt Semantic Layer defines metrics in your dbt project and works across several warehouses. Snowflake semantic views are native database objects that only cover data in Snowflake, used mainly by Cortex Analyst and SQL. Both participate in Apache Ossie, which aims to let definitions move between them. The same trade-off applies to Databricks metric views.

Sources

1. dbt Labs: Open-sourcing MetricFlow for governed metrics (Oct 14, 2025). https://www.getdbt.com/blog/open-source-metricflow-governed-metrics

2. dbt Labs: Pricing. https://www.getdbt.com/pricing

3. dbt Docs: Semantic Layer vs. Text-to-SQL: 2026 Benchmark Update (Apr 7, 2026). https://docs.getdbt.com/blog/semantic-layer-vs-text-to-sql-2026

4. dbt Docs: Semantic Layer architecture. https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-architecture

5. dbt Docs: How pricing works (queried metrics). https://docs.getdbt.com/docs/platform/billing/how-pricing-works

6. dbt Docs: dbt v2 is GA (Sep 2026). https://docs.getdbt.com/blog/dbt-v2-is-ga

7. dbt Docs: Latest metrics spec. https://docs.getdbt.com/docs/build/latest-metrics-spec

8. dbt Labs: OSI is now Apache Ossie (Jul 2026). https://www.getdbt.com/blog/osi-is-now-apache-ossie

9. dbt Labs: jaffle-shop reference project. https://github.com/dbt-labs/jaffle-shop

10. dbt Docs: MetricFlow time spine. https://docs.getdbt.com/docs/build/metricflow-time-spine

11. dbt Docs: MetricFlow commands. https://docs.getdbt.com/docs/build/metricflow-commands

12. dbt Docs: Metrics overview. https://docs.getdbt.com/docs/build/metrics-overview

13. dbt Docs: Available Semantic Layer integrations. https://docs.getdbt.com/docs/platform-integrations/avail-sl-integrations

14. dbt Docs: About the dbt MCP server. https://docs.getdbt.com/docs/dbt-ai/about-mcp

15. dbt Docs: Semantic Layer FAQs. https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs

16. GitHub: dbt-labs/metricflow. https://github.com/dbt-labs/metricflow

17. Upsolve AI: Data Models. https://upsolve.ai/features/data-models