What Is the dbt Semantic Layer? MetricFlow Explained

The dbt Semantic Layer is the part of dbt where data teams define business metrics such as revenue, active customers, or churn rate once, in YAML next to their dbt models, and then query them the same way from BI tools, spreadsheets, and AI agents. It is powered by MetricFlow, the engine that reads those definitions and writes the SQL, including the joins, for each request.

The problem it solves is familiar to anyone who has seen two dashboards disagree. When every BI tool and every analyst recalculates "revenue" on their own, the definitions drift. The dbt Semantic Layer moves the calculation into the dbt project, where it is version-controlled and reviewed like the rest of the transformation code, so a change to a metric reaches every tool that asks for it.

What Is the dbt Semantic Layer?

In dbt's own words, the Semantic Layer removes duplicate coding by letting data teams define metrics on top of existing models while it handles the joins automatically. In practice it has three parts:

• Definitions in the dbt project. Semantic models describe how a dbt model can be joined and sliced, and metrics describe the calculations. Both live in YAML files reviewed through Git, next to the SQL models they describe.
• MetricFlow. The engine that turns a request such as "revenue by region by month" into correct SQL for the warehouse.
• Semantic Layer APIs and integrations. The interfaces that let tools outside dbt ask for metrics by name instead of writing their own SQL.

Defining and querying metrics through the hosted Semantic Layer requires a dbt Starter, Enterprise, or Enterprise+ account on the dbt platform. Since June 2026 dbt Labs has been part of the merged company Fivetran + dbt Labs, and the Semantic Layer continues as part of the dbt platform. For the general concept behind it, see what a semantic layer is and the narrower metrics layer.

What Is MetricFlow?

MetricFlow is the engine behind the dbt Semantic Layer. It reads the YAML definitions and builds a semantic graph: semantic models are the nodes, and the relationships between them are the edges. When someone asks for a metric grouped by a dimension, MetricFlow walks the graph to find a valid join path and generates the SQL. Because joins are derived from declared entity types (primary and foreign keys) rather than written by hand, it avoids fan-out and chasm joins, the two classic ways a self-service query double-counts.

The building blocks are:

• Semantic models, each mapped to one dbt model.
• Entities, the join keys that let MetricFlow move from one semantic model to another.
• Dimensions, the time and categorical attributes you group and filter by.
• Metrics, the business calculations.

The current specification (dbt v1.12 and later) supports five metric types:

How Metrics Are Defined in YAML

In the current specification a semantic model is declared inside the YAML of the dbt model it describes, and metrics can sit next to it. A shortened example adapted from dbt's documentation:

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

Because the definition is code, it follows the same workflow as a dbt model: a pull request, a review, CI, and a deployment. Starting with dbt v1.12, semantic models can also be defined as Apache Ossie documents, the open interchange format described below.

dbt Semantic Layer Integrations

dbt lists twelve native integrations for the Semantic Layer: Power BI, Tableau, Google Sheets, Microsoft Excel, Omni, Dot, Hex, Klipfolio PowerMetrics, Mode, Push.ai, Sigma (in preview), and Steep. Any BI tool can also use exports, and custom applications can query metrics through four interfaces:

• JDBC and ADBC for SQL-speaking tools.
• GraphQL for applications that want to list and query metrics programmatically.
• The Python SDK for notebooks and data apps.

For AI, the dbt MCP server exposes Semantic Layer tools to MCP clients such as Claude and ChatGPT, so an assistant can list the available metrics and query them instead of writing SQL against raw tables. The server runs either self-hosted or as a remote server hosted by dbt; both support the Semantic Layer, and the tools available in the remote version depend on the dbt plan. This is the main reason the dbt Semantic Layer has become part of AI discussions: an agent that asks MetricFlow for "net revenue" gets the governed calculation rather than its own guess. More on that pattern in a context layer for dbt.

Open Source MetricFlow and Apache Ossie

At Coalesce in October 2025, dbt Labs relicensed MetricFlow under Apache 2.0 (version 0.209.0 and later), including the code that defines metrics, generates multi-dialect SQL, and represents semantic metadata. dbt Labs tied the move to the Open Semantic Interchange (OSI), the vendor-neutral initiative for exchanging semantic models between tools that Snowflake launched in 2025 with partners including dbt Labs and Salesforce.

In July 2026 OSI was accepted into the Apache Incubator and renamed Apache Ossie to avoid confusion with other projects that use the OSI acronym. The coalition has grown from 17 launch partners to more than 50 organizations, including Snowflake, Databricks, Salesforce, and dbt Labs. For dbt users the practical effect is that metric definitions are becoming portable: dbt v1.12 can read semantic models defined as Ossie documents, and platforms such as Snowflake semantic views and Databricks metric views are aligning with the same standard.

dbt Semantic Layer vs Context Layer

The dbt Semantic Layer and a context layer are often mentioned together, and they answer different questions. The semantic layer answers "how is this metric calculated?" A context layer answers "what does this term mean, who owns it, where does the data come from, and can I trust it?" The full comparison is in context layer vs semantic layer; for dbt specifically it looks like this:

The two work best together. The metric formula stays in dbt, where engineers maintain it. The business definition it implements, the person who approves it, and the lineage to the reports that use it live in the context layer, which also covers data that never passes through dbt.

How Dawiso Works With the dbt Semantic Layer

Dawiso sits in the context layer role described above. It reads metadata from more than 30 sources, dbt among them: the dbt integration connects to a dbt Cloud account and retrieves objects and their relations through the dbt metadata API, on a schedule you set, and dbt is a direct source of lineage in Dawiso. That lineage can follow a value from the warehouse through dbt to the Power BI report that shows it.

On top of that metadata, the business glossary holds the definition a metric is meant to implement, for example "Gross Profit Margin is net revenue minus cost of goods sold, divided by net revenue", together with the owner who approved it. AI tools that support MCP, such as Claude and Cursor, can query Dawiso through the Dawiso MCP Server and get the definition, owner, and lineage along with the number. In a stack with the dbt Semantic Layer, that means MetricFlow calculates the metric and Dawiso tells the agent, and the people reviewing its answer, what that metric means and where it comes from. For how this compares with other options, see the best semantic layer tools.

Conclusion

The dbt Semantic Layer brings metric definitions into the same Git workflow as the transformations that produce the data, and MetricFlow makes those definitions queryable from BI tools, spreadsheets, and AI agents. With MetricFlow open source and Apache Ossie emerging as a shared format, the definitions are also becoming portable between platforms. What the semantic layer leaves open is the business side: who approved a definition, what it means outside the dbt project, and how it connects to everything else in the data estate. That is the job of the context layer around it.

Sources

• dbt Docs - dbt Semantic Layer
• dbt Docs - About MetricFlow
• dbt Docs - Available Semantic Layer integrations
• dbt Docs - About the dbt MCP server
• dbt Labs - dbt Labs affirms commitment to Open Semantic Interchange by open sourcing MetricFlow (October 2025)
• GitHub - dbt-labs/metricflow (license history)
• Apache Ossie - Ossie enters the Apache Incubator (July 2026)
• Fivetran - Fivetran + dbt Labs complete merger (June 2026)
• Dawiso Help - Sources of data lineage