A semantic layer turns text-to-SQL from SQL writing into metric picking: the model chooses governed metrics and dimensions, and an engine compiles the joins. In dbt Labs’ April 2026 benchmark, Claude Sonnet 4.6 scored 98.2% through the semantic layer against 90.0% writing SQL on the same tables, but only after three added models made every question answerable. Atlan’s AI Context Platform assembles those definitions from governed context and, through Context Engineering Studio, renders them as a Snowflake semantic view, Databricks metric views or dbt MetricFlow models. Agents can also read the same definitions over MCP (Model Context Protocol, the open standard AI agents use to reach tools and data), so the context layer, one governed record of what each metric means and who owns it, sits outside any single engine.
Coverage and upkeep decide the rest. The dbt benchmark authors, a vendor testing its own product, say the layer “can only answer questions that fall within the scope of what’s been modeled.” So a reliable semantic layer under a text-to-SQL agent is two jobs: model the questions your users actually ask, and keep each definition current as the business changes.
| Field | Detail |
|---|---|
| Persona | AI Builder; Analytics Engineer |
| Key regulations | Not regulation-specific; the metric owner’s own rules apply |
| Primary stakeholders | Head of data, AI platform lead, BI owner |
| Typical challenges | The LLM writes wrong joins; one metric defined three ways; questions outside the model; definitions that drift |
| Maturity | A warehouse and a first text-to-SQL agent; no governed metric layer yet |
| Best for | Choosing and sequencing a semantic layer under an agent |
How does a semantic layer work inside a text-to-SQL pipeline?
A semantic layer sits between the question and the warehouse, so the model selects defined metrics and dimensions and an engine writes the SQL. The definitions live in a semantic model: metrics, dimensions, entities and the relationships between them.
There are two ways to use it. On a compile route, the agent calls a metric interface and an engine builds the query. On a grounded route, a SQL-generating agent reads the model as context and still writes the SQL itself. The first constrains joins and aggregation; the second informs them.
According to dbt’s MetricFlow documentation (2026), MetricFlow “is a SQL query generation tool” that uses entity types to “avoid the construction of fan out and chasm joins.” Snowflake puts the same idea inside the database: per Snowflake’s semantic views overview, a semantic view is “a schema-level object,” created with TABLES, RELATIONSHIPS, FACTS, DIMENSIONS and METRICS clauses (Snowflake docs).
A worked example: one metric request
Here is what a compile-route request looks like. Snowflake’s querying docs show a query that names only a dimension and a metric, and leaves the joins to the view:
SELECT * FROM SEMANTIC_VIEW(
tpch_analysis
DIMENSIONS customer.customer_market_segment
METRICS orders.order_average_value
)
ORDER BY customer_market_segment;
The agent only fills in the names. Josh Klahr of Snowflake, in a recorded panel discussion, called a semantic view “a definitional object, and it has execution,” and argued that a metric name handed to a compilation engine may cost less than a long LLM-written SQL string. That cost point is his view; none of the studies below measured it.
| Step | Who does it | What can go wrong |
|---|---|---|
| 1. Question parsed | LLM | Ambiguous wording |
| 2. Metric and dimension chosen | LLM, against governed definitions | Metric not modeled, or the wrong metric picked |
| 3. Joins and aggregation compiled | Semantic layer engine | Too many entity hops |
| 4. SQL executed | Warehouse | Cost, latency |
| 5. Answer returned or declined | Agent | Silent fallback to free-form SQL |

From question to answer: where the semantic layer compiles the SQL. Source: Atlan
What the model still decides
The model reads the question and maps words such as “revenue in Q3 2026” to a metric, a time dimension and a filter. It also decides whether any defined metric fits at all, so a wrong pick still produces a clean, wrong number.
Ambiguous wording stays a model problem, which is why Snowflake’s Cortex Analyst docs list descriptions and synonyms in the semantic view alongside metrics. Owners and the reasons behind a definition sit outside any one engine, and that is where the context layer vs semantic layer line starts.
What the engine decides
The engine owns joins, grain and aggregation. MetricFlow restricts joins using declared entity types, so correct results still depend on those keys and grains being true in the data. That is the practical difference between a semantic layer and a data model: one describes tables, the other compiles business questions against them.
Teams that already run a semantic layer for analytics in BI hold many of these definitions, sometimes split from a separate metrics layer. Reusing them is the fastest start for a semantic layer for AI agents.
What does the evidence say about accuracy with and without a semantic layer?
Three 2026 studies measure what semantic definitions add to text-to-SQL, and each is limited in a way worth naming.
According to dbt Labs (2026), on 11 questions run 20 times each, GPT-5.3 Codex scored 84.1% writing SQL and 100.0% through the semantic layer. Both arms had the same three added models, and the authors note they loaded the entire schema as context for text-to-SQL, which is impractical for larger datasets.
Rumiantsau and Fokeev (2026) gave three frontier models a semantic-layer document, which raised accuracy on 100 Contoso Retail questions in ClickHouse from 45.5 to 50.5% (schema only) to 67.7 to 68.7%, a gain of “+17 to +23 percentage points” (p < 0.01). That was a document in the prompt, not a compiled metric engine.
In a single-author preprint, Qing Ye (2026) found that semantic content raised accuracy on hard DABStep data-analysis tasks for four models: 13.9% to 55.1%, 22.6% to 56.6%, 22.9% to 68.4% and 37.0% to 77.4%. Retrieval scaffolding without that content added 0 to 5 points on two flash models and 14 to 15 on two frontier models, so scaffolding matters on frontier models, just less than content. The author’s rule: “semantics first, scaffolding second, pre-computed macros only where an agent demonstrably fails to derive.”
| Study | Setup | Result | Caveat |
|---|---|---|---|
| dbt Labs (Apr 2026) | ACME Insurance benchmark, 11 questions x 20 runs, remodeled with three added models | Text-to-SQL 90.0% (Sonnet 4.6) and 84.1% (GPT-5.3 Codex); semantic layer 98.2% and 100.0% | Vendor testing its own product; 11 questions |
| Rumiantsau and Fokeev (Apr 2026) | 100 questions, Contoso Retail in ClickHouse, three models | 45.5 to 50.5% schema only; 67.7 to 68.7% with the document | A document, not a compile engine |
| Ye (Sep 2026) | DABStep hard tasks, four models | Content: up to 77.4%; scaffolding alone: 0 to 5 points (flash), 14 to 15 (frontier) | Single-author preprint |
How it differs from schema-only text-to-SQL
Schema-only prompting fails in the ways described in text-to-SQL for enterprise: wrong joins, wrong columns, one metric read three ways. Who should use which pattern depends on who can check the answer, covered in text-to-SQL vs a semantic layer for self-serve analytics.
Only Ye separates definitions from the retrieval around them, and the definitions moved accuracy far more. Write them before you tune retrieval; that ordering is where context engineering and a semantic layer meet.
What happens when a question is not modeled?
The unmodeled question is where text-to-SQL accuracy is decided, because a semantic layer answers only what has been modeled. On the original, highly normalized ACME schema, dbt Labs (2026) measured the semantic layer at 72.7% across all questions against 64.5% for text-to-SQL.
What the hop split showed
Split by whether a question needed too many entity hops for MetricFlow, the 2026 run showed the layer at 100% on the rest and 0% on those: the data existed, but the model’s shape put it out of reach. In the same 2026 run, text-to-SQL scored 70.0% (Sonnet 4.6) and 100.0% (GPT-5.3 Codex) on the hop-heavy questions. An LLM then created three dbt models joining a few tables, which made all 11 questions answerable through the layer. Text-to-SQL improved too, which the authors read as better modeling helping both approaches.
Jason Ganz, Director of Community, Developer Experience & AI at dbt Labs, and Benoit Perigaud, Staff Developer Experience Advocate at dbt Labs, describe the trade for requests outside the model: the Semantic Layer “tells you” when a request falls outside it, while text-to-SQL “will cheerfully give you a wrong number.”
That holds for unsupported requests on a compile route. A supported request built on a wrong metric or a wrong definition still compiles, and a grounded route can still write a plausible wrong query. Decide in advance what your agent does when no metric matches.
Add models for the questions people actually ask
Log every refusal and sort it. Only a missing metric, a missing dimension or a join path with too many hops is a modeling ticket; ambiguity, permissions and transient errors go to other queues.
In the dbt benchmark, closing the gap took three additional models for 11 questions, though model count says little about the grain and testing work behind each one. The do you need a semantic layer test applies per question, not per warehouse.
Keep a labeled fallback
A refusal is safe but unhelpful when the user needs a number today. Where the metric is low-stakes, route the question to free-form SQL with the same read-only permissions and scan limits, and say in the answer that no governed metric was used. For high-stakes metrics, ask or decline. The context engineering for an AI analyst pattern covers what that agent needs to read before it writes SQL on its own.
LLMs can write SQL for the hop-heavy questions, yet they still need approved definitions to read a business question correctly, which is why the semantic layer is not dead. Coverage is the price of governed accuracy.
Which semantic layer routes can a text-to-SQL agent query?
Five documented warehouse and BI routes let an agent query governed definitions, and they work differently. Some compile a metric request (MetricFlow, semantic view queries); others generate SQL, DAX or KQL grounded in the model (Cortex Analyst, the Fabric data agent, Looker Conversational Analytics).
| Route | What the official page states | Status per the page | Source |
|---|---|---|---|
| Snowflake semantic views, read by Cortex Analyst | “Cortex Analyst uses Semantic Views to understand your data and generate accurate SQL queries”; a view can also be queried with a SEMANTIC_VIEW clause or by name in FROM |
Querying semantic views generally available in release 9.25 (August 2025). The Cortex Analyst page states “Snowflake recommends transitioning to Cortex Agents” | Cortex Analyst docs; querying docs; release notes 9.25 |
| dbt Semantic Layer and MetricFlow | “AI tools like Claude and ChatGPT can connect to the Semantic Layer through the dbt MCP server” | dbt platform Starter, Enterprise and Enterprise+ plans | dbt Semantic Layer docs |
| Looker Conversational Analytics | “Grounded in the Looker semantic modeling layer”; uses “the LookML definitions of your data” as its source of truth | Overview page, Looker docs | Looker docs |
| Microsoft Fabric data agent | NL2SQL for lakehouses and warehouses, NL2DAX for Power BI semantic models, NL2KQL for KQL databases; up to five data sources | Generally available | Microsoft Learn |
| Unity Catalog metric views | Lists Genie Agents among the surfaces that query metric views | Relationships between metric views labeled Beta | docs.databricks.com/aws/en/uc-semantics/metric-views |
Where each route fits your stack
On Snowflake, semantic views are the object Cortex Analyst reads; Cortex Analyst vs text-to-SQL shows where the two meet. On dbt, the dbt Semantic Layer compiles MetricFlow definitions and an MCP server for dbt gives agents access.
A Looker agent reads LookML, which raises the question of LookML vs a universal semantic layer. Fabric’s NL2DAX reads whatever your Power BI semantic model vs a dedicated semantic layer choice gives it. On Databricks, the Unity Catalog semantic layer holds metric views, and how to create Databricks metric views walks the setup.
Pick the route your team already runs; the best semantic layer tools cover the wider field when no route exists yet. Every route reads only the definitions it is given, so a team that defines the same metric in a BI model and a warehouse view has two definitions to keep in step.
What goes wrong with a semantic layer in text-to-SQL?
Most failures come from definitions that drift, joins nobody modeled and a layer treated as finished.
| Mistake | Symptom | Fix |
|---|---|---|
| Treating the layer as finished | Answers stay confident while the business has changed how it counts | An owner and a review date per metric |
| Modeling the schema, not the questions | Refusals on multi-hop questions (dbt Labs: 0% until three models were added) | Add the few models those questions need |
| Treating a prompted document as finished | Accuracy reached 67.7 to 68.7% in the paired benchmark, with the model still writing the SQL | Measure a compiled metric interface on the same questions before choosing |
| Building retrieval before content | 0 to 5 points from scaffolding alone on flash models, 14 to 15 on frontier ones (Ye, 2026) | Write the definitions first |
The stale-definition row follows from how compilation works, not from a study: an engine compiles whatever definition it holds, so an outdated one still returns a number and raises no error. No study here tested the owner-and-review fix either.
The other three rows are measured. No study here ran a document arm and a compiled arm on the same questions, so whether compilation closes the rest of the paired benchmark’s gap is still an open test. Teams choosing an open-source semantic layer face the same four risks, because none of them is about the engine. Track unsupported requests separately from wrong answers to supported ones.
How Atlan keeps text-to-SQL definitions governed
Atlan’s AI Context Platform assembles the definitions a semantic layer reads from context your team and Context Agents keep current in Atlan, then renders them for the engine your team already runs.
According to Atlan’s Context Engineering Studio docs, Context Engineering Studio assembles a context repository for one use case and renders it as a semantic view for Snowflake Cortex Analyst, metric views for Databricks Genie and MetricFlow models for dbt. “Agents that read it over MCP get the same definition without a deploy.” The repository links to Atlan assets instead of copying them, and when a source changes, you regenerate the repository to pull the update. So a changed metric definition reaches each engine on the next regenerate and deploy, and MCP readers see it after the regenerate, with no deploy.
Reading context over MCP is the pattern behind Atlan MCP and an MCP semantic layer for AI agents. Workday describes its work with Atlan in those MCP terms:
"Atlan captures Workday's shared language to be leveraged by AI via its MCP server. As part of Atlan's AI labs, we're co-building the semantic layer that AI needs."
Joe DosSantos, VP, Enterprise Data and Analytics, Workday
What Atlan’s own benchmark measured
According to Atlan AI Labs (2026), adding governed context to the schema lifted the query win rate from 16.1% to 22.2%, a 38% relative gain, over 174 queries and 522 evaluations on a Formula One dataset. Medium-complexity queries improved 2.15x and simple ones 1.15x, while complex ones held flat at 1.00x. Like dbt’s test, this is a vendor testing its own approach, and it measured added context in the prompt, not a compiled semantic layer.
One shared repository, part of a wider enterprise context layer, cuts duplicated authoring; matching answers across engines still need synced versions and the same test questions on each.
How do you add a semantic layer to a text-to-SQL agent?
Start with the questions people already ask, model those, then test and keep the definitions current.
- List the questions the agent gets asked most. Pull them from BI usage, Slack and the agent’s own logs, not from the schema. Twenty or so is enough to start.
- Model the metrics, dimensions and entities those questions need. Add only the joins they require.
- Name an owner and a test for each definition. The owner approves each change; the test checks the number against a known answer before the change reaches any engine.
- Decide what happens on an unmodeled question. Decline, ask, or route to labeled free-form SQL.
- Run the paired test. Compare your current production agent with the layer on the same questions, several runs each. Score each run as correct, wrong or refused against known answers, and hold back paraphrases and questions you did not model.
- Re-run the test on every change. Any change to a metric, schema or policy triggers it, with a monthly review as the floor.
Where to go after step 2
The build vs buy semantic layer decision comes after step 2, once you know how many models the real questions need. The talk-to-data agent blueprint shows where the layer sits in the full agent, and how to prepare data for natural-language analytics covers the table work behind step 2. When your BI tool and your agent read the same synonyms and agent instructions, a context layer for natural-language analytics keeps them in one place.
Steps 3 and 6 never finish. Owners, tests and reviews are the part of context engineering that keeps a definition true after launch, so an enterprise context layer implementation plan should staff them from the start.
See how one context repository becomes a Snowflake semantic view, Databricks metric views and dbt MetricFlow models in Atlan’s Context Engineering Studio guide.
FAQs about semantic layers for text-to-SQL
Seven questions practitioners ask before putting a semantic layer under a text-to-SQL agent.
1. Does a semantic layer improve text-to-SQL accuracy?
Yes, on the questions it covers. In dbt Labs’ April 2026 benchmark, Claude Sonnet 4.6 scored 98.2% through the semantic layer against 90.0% writing SQL on the same remodeled tables. A 2026 paired benchmark found a semantic-layer document in the prompt added 17 to 23 points over schema-only prompts. Questions outside the model still decide what users see.
2. How does a semantic layer work with an LLM?
The LLM reads the question and picks a defined metric, dimensions and filters. On a compile route, such as MetricFlow or a SEMANTIC_VIEW query in Snowflake, an engine turns that selection into SQL using the joins someone declared. On a grounded route, such as Cortex Analyst, the model still writes the SQL, guided by the semantic view.
3. Is text-to-SQL still useful with a semantic layer?
Yes, for questions nobody has modeled yet. In dbt Labs’ 2026 test, text-to-SQL scored 70.0% (Claude Sonnet 4.6) and 100.0% (GPT-5.3 Codex) on questions that needed too many entity hops for MetricFlow, where the semantic layer scored 0% until three models were added. Keep it as a labeled fallback, so the user knows no governed metric was used.
4. What does a semantic layer not cover?
A semantic layer answers the questions that have been modeled, and only those. A question that needs a new metric, a join path nobody declared or a business rule that lives in someone’s head falls outside it. Plan for those: decline, ask a clarifying question, or route to free-form SQL with a visible label.
5. Do I need a semantic layer or just better column descriptions?
Descriptions help the model choose; a semantic layer moves the hard part from writing SQL to picking a defined metric. In a 2026 ablation on hard DABStep tasks, semantic content lifted one model from 13.9% to 55.1%, while retrieval scaffolding without that content added 0 to 5 points on flash models and 14 to 15 on frontier models. Start with definitions for your most-asked metrics.
6. Which semantic layers can an LLM query through MCP?
dbt documents that AI tools such as Claude and ChatGPT can connect to the dbt Semantic Layer through the dbt MCP server, on the Starter, Enterprise and Enterprise+ plans. Atlan’s Context Engineering Studio renders one context repository for Snowflake, Databricks and dbt, and agents that read it over MCP get the same definition without a deploy.
7. How do I test a text-to-SQL agent on a semantic layer?
Run the same real questions through your current agent and through the layer, several runs each. Compare the returned numbers with known answers, and count correct, wrong and refused results separately. Include paraphrases and questions you have not modeled, or the test only measures your modeling.
Sources
- Semantic Layer vs. Text-to-SQL: 2026 Benchmark Update, dbt Developer Blog (2026)
- Semantic Layers for Reliable LLM-Powered Data Analytics: A Paired Benchmark of Accuracy and Hallucination Across Three Frontier Models, arXiv (2026)
- Which Part of the Context Layer Does the Work? Separating Semantic Content from Retrieval Scaffolding in Text-to-SQL Agents, arXiv (2026)
- About MetricFlow, dbt Docs
- dbt Semantic Layer, dbt Docs
- Overview of semantic views, Snowflake Documentation
- Using SQL commands to create and manage semantic views, Snowflake Documentation
- Querying semantic views, Snowflake Documentation
- Cortex Analyst, Snowflake Documentation
- Release notes 9.25, Snowflake Documentation
- Conversational Analytics in Looker overview, Google Cloud
- Fabric data agent concepts, Microsoft Learn
- Unity Catalog metric views, Databricks Documentation: docs.databricks.com/aws/en/uc-semantics/metric-views
- What is Context Engineering Studio?, Atlan Documentation
- How We Proved Metadata Delivers 38% Better AI Accuracy, Atlan (2026)