dbt Semantic Layer: What It Is & How To Use It In 2026
The dbt Semantic Layer is dbt's metrics layer: you declare semantic models, entities, dimensions, measures and metrics in YAML, MetricFlow turns each metric request into SQL, and the dbt platform serves the result over JDBC, GraphQL and a Python SDK. For AI, it hands a language model a fixed menu of governed metrics, and the dbt MCP server is the quickest way to put that menu (plus discovery and SQL tools) inside Claude, Cursor or another MCP client. The limit is coverage: a metrics layer only answers questions that land on a metric someone has defined. So most teams also let the agent read the dbt project itself (models, docs, tests, lineage) and write SQL, and the real decision is where to draw the line between the two.
What the dbt Semantic Layer and MetricFlow are
MetricFlow is the engine: it reads your metric definitions and generates SQL for your warehouse's dialect. The dbt Semantic Layer is the hosted service around it on the dbt platform: the APIs, the gateway, caching and the integrations that let other tools ask for a metric by name. The building blocks:
- Semantic models map one dbt model to the entities, dimensions and measures it offers.
- Entities are join keys; MetricFlow uses them to join semantic models, so nobody hand-writes the join.
- Dimensions are the categorical and time attributes you group and filter by.
- Measures are aggregations, such as a sum or a count.
- Metrics are what people actually ask for. Simple metrics wrap one measure; ratio, derived, cumulative and conversion metrics combine or transform them.
Here is a small example in the classic spec, where semantic models and metrics sit in their own top-level YAML blocks:
semantic_models:
- name: orders
description: One row per order, net of refunds.
model: ref('fct_orders')
defaults:
agg_time_dimension: ordered_at
entities:
- name: order
type: primary
expr: order_id
- name: customer
type: foreign
expr: customer_id
dimensions:
- name: ordered_at
type: time
type_params:
time_granularity: day
- name: channel
type: categorical
measures:
- name: order_total
agg: sum
- name: order_count
expr: 1
agg: sum
metrics:
- name: revenue
label: Revenue
description: Order total, net of refunds.
type: simple
type_params:
measure: order_total
- name: orders
label: Orders
type: simple
type_params:
measure: order_count
- name: average_order_value
label: Average order value
type: ratio
type_params:
numerator: revenue
denominator: orders
dbt's latest YAML spec (dbt Core 1.12+ and Fusion) nests the semantic model under the model's own YAML and replaces measures with simple metrics defined on the model. The concepts carry over; check which spec your dbt version expects before you copy a snippet.
Clients don't query tables. They ask for metrics and dimensions, and MetricFlow works out the joins, grain and SQL. Over the JDBC interface, that request is SQL wrapped around a semantic_layer.query() call:
with monthly as (
{{
semantic_layer.query(
metrics=['revenue', 'average_order_value'],
group_by=[TimeDimension('metric_time', 'MONTH'), Dimension('order__channel')]
)
}}
)
select *
from monthly
order by metric_time__month
metric_time is MetricFlow's shared time dimension, which puts metrics from different semantic models on one time axis. order__channel is the dimension channel reached through the entity order.
Licensing and availability (as of October 2026)
Most confusion sits here, because "MetricFlow" and "the dbt Semantic Layer" are licensed differently.
Piece | License | Where you get it |
|---|---|---|
MetricFlow (definitions and SQL generation) | Apache 2.0 from version 0.209.0 (October 14, 2025); earlier versions were BSL, and AGPL before that | Open source; usable with dbt Core |
Semantic Layer service (gateway, APIs, integrations) | Proprietary | dbt platform Starter, Enterprise and Enterprise+ plans |
Caching and multiple credentials | Proprietary | Enterprise and Enterprise+ only |
Sources: dbt Labs' open-sourcing announcement at Coalesce 2025, the license history on PyPI, and dbt's architecture and FAQ pages.
- On dbt Core, you can define and compute metrics with open-source MetricFlow, but there is no hosted API for a BI tool or an AI agent to call unless you run and expose MetricFlow yourself.
- On the dbt platform, the free Developer plan is not on dbt's list. Paid plans include a monthly allowance of queried metrics, which an agent that asks a lot of questions uses up; check dbt's pricing page for the current numbers.
- Portability: dbt says it is aligning MetricFlow with the Open Semantic Interchange, now Apache Ossie; our OSI guide covers dbt's import and export paths.
Query interfaces: JDBC, GraphQL and the Python SDK
The dbt platform serves the Semantic Layer through three interfaces (overview):
- JDBC: an open-source JDBC driver over the Arrow Flight SQL protocol (driver 12.0.0 or later; ADBC also works), sending SQL that wraps
semantic_layer.query(). Best for BI tools and anything that speaks SQL. - GraphQL: list metrics, dimensions and entities, create a query and fetch its result. Best for applications and for reading the metric catalog.
- Python SDK (
dbt-sl-sdk): returns results as pyarrow tables. Best for notebooks and Python agents.
The dbt MCP server
dbt Labs publishes an open-source dbt MCP server that exposes dbt to any MCP client, in two forms (dbt docs):
- Local: runs on your machine with
uvx dbt-mcp, calls the dbt platform and can also run your local dbt. - Remote: hosted by dbt for data consumption, with a sign-in flow for Claude (dbt developer blog).
What it exposes
The main toolsets on dbt's available tools page (as of October 2026):
Toolset | Examples | Use |
|---|---|---|
Semantic Layer |
| Find and query governed metrics |
Discovery | Node details, lineage, exposures, search (alpha) | Read project metadata from the dbt platform |
SQL |
| Generate SQL from a question and run SQL on dbt platform infrastructure |
Admin API | Jobs and runs | Operate dbt platform jobs |
dbt CLI (local only) | dbt commands such as build, run and test | Work on the project from an editor or agent |
Tool names move between releases (several Discovery tools were deprecated in favor of a single get_node_details), so check the page above against the version you install.
Setting it up
For the local server, add it to your MCP client's config and pass connection settings as environment variables (setup guide, variable reference). A minimal Semantic Layer setup:
{
"mcpServers": {
"dbt": {
"command": "uvx",
"args": ["dbt-mcp"],
"env": {
"DBT_HOST": "cloud.getdbt.com",
"DBT_TOKEN": "<your dbt platform token>",
"DBT_PROD_ENV_ID": "<production environment ID>"
}
}
}
}
Other variables (DBT_DEV_ENV_ID, DBT_USER_ID, DBT_ACCOUNT_ID) switch on more tools, the SQL tools stay off until you set DISABLE_SQL=false, and DISABLE_TOOLS takes a comma-separated list of tools to turn off. The remote server skips the install: connect your client to dbt's hosted endpoint and sign in.
Limits and security considerations
execute_sqlneeds a personal access token. Service tokens don't work for it, so SQL runs with that person's development credentials, and it doesn't block write statements; give those credentials a least-privilege role (dbt docs).text_to_sqluses your dbt Copilot allotment. It is the only tool that does, and the remote server hides it if an admin turns AI features off (dbt docs).- Toolsets can disappear without an error. If a toolset's required variable is missing, the server disables it; a missing
DBT_HOSTremoves the Semantic Layer, Discovery and Admin API toolsets. If your agent "can't find any metrics", check the environment first. - Results go to your client's model. Check that LLM provider's retention terms before you point it at customer data.
- It hands over tools, not judgment. The client model decides which of several similar "revenue" metrics the person meant, nothing reviews that choice, and a correction made in one chat doesn't carry over. That suits analytics engineers in Cursor or Claude Code more than business users.
Two ways to put AI on dbt
An LLM on top of dbt can query only governed MetricFlow metrics (A), or read the dbt project and write SQL (B). They fail in different ways:
A: governed MetricFlow metrics only | B: the agent reads the dbt project and writes SQL | |
|---|---|---|
What the LLM sees | Metric names, dimensions and entities from the Semantic Layer | Models, model SQL, column docs, tests and lineage, plus the warehouse schema |
Who writes the SQL | MetricFlow; the LLM only picks metrics, dimensions and filters | The LLM, against your dbt models |
Questions it covers | Only those that map to a defined metric | Anything the models can answer, including one-off and row-level questions |
Consistency | Same definition every time | Depends on your docs; two answers can compute one metric two ways |
Typical failure | Can't answer, or picks the wrong one of several similar metrics | Plausible SQL with a wrong filter, grain or join |
What you maintain | Semantic models and metric YAML | Model and column docs, tests and written business rules |
dbt plan needed | Starter, Enterprise or Enterprise+ for the hosted APIs (as of October 2026) | None; works on dbt Core |
Best for | Board, finance and any number several tools must agree on | Exploratory, one-off and long-tail questions |
Option A also has an upkeep cost the table understates: every metric is defined twice, once in the model SQL and once in YAML, and someone has to keep them in step.
What the evidence says
The general case for and against a semantic layer, including the wrong half argument, how we took Dot from 10% to 90% on a DABstep slice without one, and why AI made the layer cheap, is in what a semantic layer is. The dbt-specific data point is Ramp: as we wrote in our Ramp Research write-up, Ramp's analyst agent answered more than 1,800 questions from about 300 people using dbt docs, Looker explores and Snowflake metadata, with no separate semantic layer. Domain owners write context as doc blocks inside the dbt project, so it is reviewed and versioned like code.
How to choose
- Metrics only when a small set of numbers must match across every tool (finance, board reporting, external metrics), you are already on a dbt platform plan, and your users mostly ask about those numbers.
- Project reading when you are on dbt Core, your MetricFlow coverage is thin, or most questions are exploratory. Invest in model and column descriptions first; they pay off for humans too.
- Both for most teams, in my view (I run an AI analytics company, so discount accordingly): metrics for the numbers that must agree, the project for everything else, and an agent that tells the user which one it used.
- Neither, in a sense, if what you want is dashboards defined in dbt YAML rather than an analyst. A dbt-native BI tool such as Lightdash is built for that; see Lightdash vs GetDot.
If you are choosing a semantic layer and are not committed to dbt's platform, we recommend Malloy instead: it can model the tables your dbt project builds, and GetDot reads it natively (why we recommend Malloy).
How GetDot works with dbt
GetDot connects to dbt in both ways, and you can turn on one or both (details on the dbt integration page and in our changelog).
It reads your dbt project (dbt Core or dbt Cloud)
- Dot parses the repository (any branch) in an isolated sandbox, without your dbt profile or warehouse credentials.
- From the manifest it takes each model's SQL, descriptions, column docs and tests, lineage, root sources (such as
stripeorshopify), materialization, tags, meta and contract status, and matches each model to the warehouse table it builds. - The repo re-syncs daily by default; when one file won't parse, Dot syncs the rest and says so on the connection card.
- Answer lineage draws the path from source tables through your dbt models to the exact SQL behind an answer.
It queries your dbt Semantic Layer (dbt platform)
- Dot reads the metric catalog over GraphQL, and the metrics' labels, meta and tags from dbt's metadata API.
- Each metric appears to the agent as its own table whose columns are the dimensions and entities you can slice it by, so the model never picks one metric out of a wide table of unrelated columns.
- Dot writes a
semantic_layer.query()request, so MetricFlow generates the SQL. Before filtering on a text dimension it looks up the values that exist, so "Germany" matches whatever your data stores. - If a question needs a metric or dimension the layer doesn't have, Dot names the missing fields instead of inventing a definition.
It shows up in your DAG
Dot exports its shared dashboards, and Dot itself, as dbt exposures (for example models/dot_exposures.yml), so before you change a model you can see which Dot dashboards depend on it. The Context Agent keeps the rest of the context reviewed: it proposes changes as diffs a person approves and tests Dot against answers you trust. When an answer rests on a choice your workspace doesn't settle, Dot marks it "Assumption made", and a correction becomes a proposal, so the next person asking gets the fixed answer.
Dot is also an MCP server: call Dot from Claude, ChatGPT, Cursor or Copilot with your own Dot permissions.
How to set it up
These steps follow the product's connection forms. Full docs: dbt Core setup.
- Connect the warehouse your dbt models build into (for example BigQuery, Snowflake or Postgres) under Settings, Connections.
- Add a dbt Repository connection: pick the repo through Dot's GitHub app, or paste a GitHub, GitLab or Bitbucket URL with an access token (optional for public repos).
- Choose the linked database connection from step 1, which Dot uses to match models to tables.
- Run the first sync and check how many models it parsed and matched.
- If you use the dbt Semantic Layer, add the dbt connection with your environment ID and a token that can read the Semantic Layer and metadata APIs, plus the GraphQL URL if your account is not on the default host.
- Ask a question in the web app, Slack or Teams, and open the SQL and lineage on the first few answers.
For how dbt compares with other layers, see semantic layer tools and Malloy vs LookML vs dbt vs Cube.
FAQ
Partly. MetricFlow has been open source under Apache 2.0 since October 2025, so you can use it with dbt Core; the hosted Semantic Layer comes with the dbt platform's Starter, Enterprise and Enterprise+ plans as of October 2026.
It gives MCP clients such as Claude and Cursor tools to list and query metrics, read models and lineage, generate and run SQL, operate jobs and, locally, run dbt commands. Run it with uvx dbt-mcp or use dbt's remote server.
No. An agent can read your models, docs, tests and lineage and write SQL, which is how Ramp's analyst works. The Semantic Layer adds deterministic computation for the metrics several tools must agree on.
It can draft semantic models and metrics from your dbt project and flag definitions that drifted from the SQL, which makes a semantic layer much cheaper to build. Review every definition anyway: the point of a definition is the decision behind it, and a draft can encode the same ambiguity you were trying to remove.
Both. Dot reads any dbt project from GitHub, GitLab or Bitbucket and re-syncs it daily; on a dbt platform plan with the Semantic Layer, it can also query your MetricFlow metrics.
Check what it stores, which LLM sees your data, and whose permissions apply. Dot parses your repo in a sandbox without your warehouse credentials, queries the warehouse in place without copying data, runs every LLM provider with zero data retention, and is SOC 2 Type II and GDPR compliant. It applies your warehouse's own permissions and row-level security; on a Semantic Layer connection, the access of the dbt token you connect applies, so scope it accordingly.
Want to see which of your dbt models Dot would match, and what it would say about them? Connect your repo for free; the Free plan includes 300 one-time credits with full Pro features.
Rick Radewagen
Rick is a co-founder of Dot, on a mission to make data accessible to everyone. When he's not building AI-powered analytics, you'll find him obsessing over well-arranged pixels and surprising himself by learning new languages.