What is the dbt Semantic Layer (and when you don't need it)

The dbt Semantic Layer moves metric definitions out of BI tools and into the dbt project. You describe tables once in YAML (their keys, the columns people group by, and the metrics), and MetricFlow, the engine behind it, writes the SQL for each question when it is asked. Tableau, Google Sheets, a Python script and an AI agent asking for “revenue by country” all get the same number from the same definition.

Copy and paste

The smallest useful definition, in the latest YAML spec:

models:
  - name: orders
    semantic_model:
      enabled: true
    agg_time_dimension: order_date
    columns:
      - name: order_id
        entity:
          type: primary
          name: order
      - name: customer_id
        entity:
          type: foreign
          name: customer
      - name: order_date
        granularity: day
        dimension:
          type: time
    metrics:
      - name: revenue
        type: simple
        agg: sum
        expr: amount

With a customers semantic model whose primary entity is customer and which has a country dimension, this query works without any join written by you:

dbt sl query --metrics revenue --group-by customer__country    # dbt platform
mf query --metrics revenue --group-by customer__country        # dbt Core with MetricFlow

customer__country      revenue
-------------------  ---------
DE                         990
IT                        1240

What happens behind the query

MetricFlow finds that revenue lives in orders, that country lives in customers, and that the customer entity connects them. It generates and runs this SQL:

SELECT
  customers_src_10000.country AS customer__country
  , SUM(orders_src_10000.amount) AS revenue
FROM "shop"."main"."orders" orders_src_10000
LEFT OUTER JOIN
  "shop"."main"."customers" customers_src_10000
ON
  orders_src_10000.customer_id = customers_src_10000.customer_id
GROUP BY
  customers_src_10000.country

Nothing is materialized in advance. Every combination of metrics, dimensions, time grains and filters is computed on request, from the tables your dbt models already build.

The pieces

• Semantic models: a dbt model plus its entities (keys) and dimensions (attributes and dates). See how to create your first semantic model.
• Metrics: simple aggregations, and ratios, cumulative, derived and conversion metrics built on them.
• A time spine: a calendar table that time-based metrics need; see how to create a time spine model.
• MetricFlow: the open-source engine that turns a request into SQL. With dbt Core it runs locally through the mf command.
• The dbt platform service: the hosted Semantic Layer, with JDBC, GraphQL and Python APIs, the integrations (Tableau, Google Sheets, Excel, Power BI and others), caching and exports.

What it costs and where it runs

The hosted Semantic Layer needs a dbt platform Starter, Enterprise or Enterprise+ plan, and dbt Labs bills it by “queried metrics”. It supports Snowflake, BigQuery, Databricks, Redshift, Postgres and Trino. Caching and multiple credentials are Enterprise features.

Without a plan you can still define everything and query it locally with MetricFlow, which is how the examples on this site are tested. What you don’t get is the APIs, so BI tools can’t query it live.

When you don’t need it

• One BI tool, one team. If every report lives in one Tableau site or one Power BI model, and nobody else asks for the numbers, the tool’s own semantic model already gives you one definition per metric.
• A handful of fixed reports. A mart table with the metric at the grain the report needs is simpler to build, test and explain. The Semantic Layer pays off when people slice the same metrics in many ways you can’t predict.
• An unsupported platform, such as Microsoft Fabric at the time of writing.
• No dbt platform plan, but a BI tool that needs live metrics. Local MetricFlow can’t serve them.

A middle way is to define the metrics in the Semantic Layer anyway and write the results to tables with exports: the definition is governed in dbt, and any tool can read the table.

When it pays off

• The same metric appears in several tools and the numbers have started to disagree.
• Analysts keep building the same joins and filters in BI workbooks.
• You want AI assistants to answer metric questions from governed definitions: the dbt MCP server exposes the Semantic Layer to them.

Next steps

• How to set up the dbt Semantic Layer in dbt Cloud
• How to organise semantic model and metric YAML files

The YAML and the query were tested with dbt Core 1.12 and MetricFlow 0.213 on DuckDB; plans, platforms and services come from the dbt documentation (October 2026).