You need a semantic layer once any metric that matters is computed in 2 or more places. An AI agent reading raw tables with no shared definition counts as one. One team on one BI tool can run on its data model. In Atlan, the Context Layer for AI, Context Agents draft those definitions for owners to certify.
A semantic layer holds definitions, not data: metrics, dimensions, entities and approved join paths, written once and compiled into SQL for the tools that query it. It reads from the data model rather than replacing it, the core difference between a semantic layer and a data model. Atlan treats the timing as a count taken from your own stack.
| Quick fact | Answer |
|---|---|
| What decides it | How many places compute each metric that matters |
| Threshold | 2 or more places for any metric that matters |
| AI agents | Count as a consumer of every metric they are asked about, unless they read a shared definition |
| Possible verdicts | V1 model is enough, V2 needed now, V3 fix the model first |
| Where to start | 1 to 3 metrics, each with a named business owner |
| What it does not decide | Which tool serves the definitions |
What decides whether you need a semantic layer?
Atlan’s heuristic decides it, metric by metric, in the exact words its published semantic layer need check agent skill uses:
One team on one BI tool can run on the data model, with measures defined in that tool. Once two or more consumers (BI tools, notebooks, AI agents) compute the same metric, each rebuilds the logic and the numbers drift. Any metric that matters and is computed in two or more places needs one shared definition now. An AI agent that reads tables directly counts as a consumer of every metric it is asked about, because it rebuilds the logic from column names on every prompt.
The rule asks for one shared definition; a semantic layer is the usual home for it once several tools and agents slice a metric different ways. It needs five inputs.
| ID | Decision input | What to collect | If unknown |
|---|---|---|---|
| I1 | BI tools | Every BI tool that shows a metric to someone | Ask |
| I2 | Other consumers | Notebooks, apps and AI agents that read or compute metrics, and the tables each reads | Ask |
| I3 | Metrics and owners | The metrics that matter, roughly how many, and the business owner of each | Ask; write “no owner” where there is none, never guess one |
| I4 | Where defined | For each metric, every place its logic lives: warehouse model, each BI tool, notebook or app code, an agent prompt | Ask; this input decides the answer |
| I5 | Grain | The grain of the tables those metrics read, such as one row per order or per month | Optional; ask if the verdict is V2 |
I4 decides most answers. A place is anywhere a metric’s logic is written: its filters, edge cases and aggregation. The warehouse model is one place. A BI tool that only sums a finished net_revenue column reads that definition; one that re-applies the refund rule in its own measure is a second place.
A BI tool that calls its own model a semantic model still holds that tool’s copy. Products sold as a metrics layer vary, so check whether yours defines entities and join paths. A KPI in a business glossary describes a metric without computing it, so it is not a place. It counts as a shared definition an agent can read only when it carries everything step S4 lists, because the count measures executable business context.
How to apply the count, metric by metric
The count turns “our numbers disagree” into a per-metric verdict.
| ID | Step | Rule |
|---|---|---|
| R1 | Count computations | For each metric, count the distinct places in I4 that compute it. A BI tool reading a shared definition does not count; a BI tool with its own measure does |
| R2 | Add the agents | Add one for each agent in I2 that reads the metric’s tables and has no shared definition to read. An agent prompt already counted in R1 is not counted twice |
| R3 | Per-metric verdict | Count of 1 stays on the model. Count of 2 or more needs a shared definition |
| R4 | Overall verdict | V1, V2 or V3, from the table below |
| ID | Verdict | When it applies | First move |
|---|---|---|---|
| V1 | The model is enough | Every metric that matters has a count of 1 | Write down where each metric lives and who owns it |
| V2 | A semantic layer is needed now | Any metric that matters has a count of 2 or more | Define the top 1 to 3 drifting metrics once |
| V3 | Fix the model first | The copies disagree because of the data, such as duplicate orders or the wrong grain | Declare the grain, remove duplicates, rerun the count |
R2 is the easiest step to miss. An analyst who sees a column called amt asks a colleague whether it is gross or net, which is tribal knowledge at work. An agent reading the tables guesses, so one question can return different numbers across sessions. An agent that queries a certified view or metric interface reads a shared definition, and R2 adds nothing for it. That split is the difference between text-to-SQL and a semantic layer: one guesses on each prompt, the other reads one definition.
Two studies tested a written document in the prompt, not a semantic layer that compiles SQL. According to Painter and colleagues in JAMIA Open (2025), one model’s pass rate on 60 historical pharmacovigilance questions rose from 8.3% with the database schema alone to 78.3% with the business context document. According to Rumiantsau and Fokeev (2026), whose affiliation is a semantic-layer vendor, a 4 KB markdown document improved accuracy by 17 to 23 percentage points across three frontier models on 100 retail questions, reaching 67.7% to 68.7%. Almost a third of answers stayed wrong, so AI agent accuracy still needs testing once a definition exists.
Check the data before calling a disagreement a definition problem, because a semantic layer cannot repair bad records. Run each copy’s logic on one day of the same order-level table. If the results agree, the drift comes from the rows each copy reads, and that metric is V3.
Which metrics drift first?
Copies drift at different speeds; rank them on five signals.
| ID | Signal | Why it drifts sooner |
|---|---|---|
| D1 | Copies | More independent computations mean more chances to differ. Four BI tools each holding a revenue measure are four copies |
| D2 | Read by an agent with no definition | It recomputes on every prompt, so it can diverge on any question, and no dashboard shows the change |
| D3 | No owner | When no one owns a definition, every team writes its own copy. Revenue usually needs an owner in finance |
| D4 | A contested edge | Refunds in or out, gross or net, what counts as active. Each copy settles the edge its own way |
| D5 | Logic outside the warehouse | A measure inside a BI tool or notebook lives only there, so a change to it does not reach the other copies |
Revenue and active customers usually drift first: everyone reads them, and each has a contested edge. If sales means bookings and finance means net revenue, own them as two metrics. Dashboards and agents differ most on D2, the core split in a semantic layer for BI versus AI agents: a dashboard copy drifts when someone edits it, an agent copy on the next prompt.
No tool fixes D3: a shared definition with no owner encodes the disagreement.
When does the answer flip?
A semantic layer verdict holds only as long as the five stack inputs behind it do.
| ID | From | To | What moves it |
|---|---|---|---|
| F1 | V1 model is enough | V2 needed now | One finance team on one BI tool connects an AI agent to the order tables. Revenue now has a count of 2 |
| F2 | V2 needed now | V1 model is enough, for now | Four BI tools look like V2, but no metric appears in more than one, so every count is 1. Watch for the first metric that shows up in a second tool or an agent |
| F3 | V2 needed now | V3 fix the model first | Two dashboards disagree because one reads a monthly pre-aggregated table and the other reads order-level rows with duplicates |
F1 is the flip agents create: the tables did not change, but the agent settles refunds and gross versus net on its own. A semantic layer for AI agents gives it a definition; text-to-SQL for enterprise data shows what it does without one.
F3 is the expensive mistake: a layer on top encodes both problems. Kimball’s rule is that the grain must be declared before choosing dimensions or facts, and atomic grain is the lowest level at which a business process captures data. A monthly pre-aggregated table cannot answer a daily or order-level question.
What is the smallest first step?
For a V2 verdict (a semantic layer is needed now), start small. Every shared definition needs an owner and someone to review each change.
- S1. Take the top 1 to 3 metrics from the D1 to D5 ranking.
- S2. Name a business owner for each. If no one will own it, stop: that is the first step.
- S3. Check the grain of each table. Order-level rows roll up to day, week or month.
- S4. Write each definition once, in full: the aggregation, filters, time grain, the entity it counts, the join path, and how the contested edge is settled.
- S5. Point one consumer at it, retire that consumer’s local copy, and check the two numbers match before moving the next consumer. Start with the agent if there is one, because it drifts fastest.
For V1, write down where each metric is defined and who owns it, so a second consumer is visible the day it appears. For V3, fix the grain first; Kimball wrote in 2003 that the most frequent design error is not declaring the grain of the fact table.
Tool choice is a separate decision, and it can start small: a governed warehouse view that every consumer reads gives a simple metric one place. MetricFlow is distributed under the Apache 2.0 license from version 0.209.0 after a license change. S4 stays the same whichever engine compiles it, and context engineering builds on it.
How Atlan approaches the semantic layer decision
Atlan starts from the copies your stack already holds: the Enterprise Data Graph brings query history, BI logic and pipeline code into one place, so the copies of “revenue” in those sources are visible before anyone writes another.
Context Agents read query history, BI tile SQL and semantic sources across your estate for context bootstrapping. Context Engineering Studio then “assembles a repository from context that’s already governed in Atlan rather than starting from scratch”, and the documentation calls that context repository “a portable semantic layer.” Domain experts then review each draft, settle each contested edge, and certify the definition.
Per the same documentation, agents that read it over MCP get the same definition without a deploy. Context Repos are model-agnostic and reach agents through the Model Context Protocol (MCP), an open protocol. An agent reading that certified definition has a shared definition to read, so R2 adds nothing for it. Whether its SQL follows the definition is still a test you run, most of all in estates with more than one semantic layer.
The project README says Apache Ossie “was formerly known as Open Semantic Interchange (OSI)”, and the open specification entered the Apache Incubator on 2026-06-22. Check what your tools read and write before counting on context portability across a context layer, data catalog and semantic layer.
Real stories from real customers: Co-building the semantic layer for AI
Workday describes its semantic layer work with Atlan as co-development inside Atlan’s AI labs.
"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
The second consumer decides it
A ten-tool estate with no shared metrics can stay on its model, and a single finance team needs a shared definition the week it connects an agent to its order tables.
Owners and certified definitions are what a context layer carries to every agent. Access is a separate check: an agent reading tables directly can see rows a dashboard filters out, so confirm its path applies the same access rules.
Run the count on your top five metrics. If one already has a count of 2, the open question is which metric goes first.
FAQs about whether you need a semantic layer
1. Do I need a semantic layer if I only use one BI tool?
Usually not yet. If one team reports from one BI tool and defines each metric once there, the data model is enough until a notebook or AI agent computes one of them.
2. Do AI agents need a semantic layer?
Yes, when an agent reads raw tables: without a shared definition it rebuilds each metric from column names on every prompt. In a vendor-authored April 2026 benchmark, adding a written semantic document raised accuracy by 17 to 23 percentage points across three models, though about a third of answers stayed wrong. It tested a document in the prompt, not a semantic layer that compiles SQL.
3. Can a semantic layer fix wrong numbers?
Only when the definitions are what is wrong. If the model loads duplicate orders or a table is pre-aggregated to the wrong grain, a semantic layer will compute revenue consistently and still report the wrong number.
4. Is a metrics layer enough instead of a full semantic layer?
Sometimes. Products sold as metrics layers vary. A first definition needs the entity it counts and its join path as well as the aggregation, so check that yours defines both.
5. Should I define every metric at once?
No. Start with the one to three metrics most likely to drift, name an owner for each, and move one consumer at a time.
6. Which semantic layer tool should I choose?
Decide after the count. It tells you which metrics need a shared definition and who owns each; tool choice then depends on where your consumers run and which formats they read.
Sources
- semantic-layer-need-check, Atlan agent skill (first-party)
- Automating pharmacovigilance evidence generation: using large language models to produce context-aware structured query language, Jeffery L. Painter et al., JAMIA Open, 2025
- Semantic Layers for Reliable LLM-Powered Data Analytics: A Paired Benchmark of Accuracy and Hallucination Across Three Frontier Models, Michael Rumiantsau and Ivan Fokeev, arXiv:2604.25149, 2026
- Grain, Kimball Dimensional Modeling Techniques
- Declaring the Grain, Ralph Kimball, Kimball Group, 2003
- MetricFlow allows you to define, build, and maintain metrics in code, GitHub
- Specification, Model Context Protocol, version 2026-07-28
- Apache Ossie (incubating), GitHub
- Incubation Status Template, Apache Incubator (Ossie project status page)
- What is Context Engineering Studio?, Atlan Documentation (first-party, accessed 2026-11-03)
