Semantic layer vs context layer: what AI agents need first
Joe Reis's 2026 State of Data Engineering Survey asked 1,101 data professionals how they model data. Just 5.4% said they use canonical or semantic models. The same group ranked semantics, ontologies, and knowledge graphs third among the topics they most want training on.
The appetite makes sense: coding agents can write data models and SQL quickly, but they still need a governed answer to what revenue means, how a customer is defined, which source wins, and which exceptions apply.
And this is where semantic layers and context layers enter the conversation. The terms overlap, and different parties draw the boundary differently. A useful distinction is that a semantic layer governs business meaning close to the data, while a context layer assembles that meaning with the wider rules and state an agent needs for the task in front of it.
Both layers store and deliver business decisions, while neither can make a decision for you that the organization has never resolved.
A semantic layer gives AI agents governed metrics, not business judgment
A semantic layer defines metrics, dimensions, entities, relationships, joins, and access rules so dashboards and AI agents query a governed model of the business instead of reasoning directly over raw tables.
When an agent receives a request for net revenue by region, the semantic layer constrains the formula, available dimensions, join paths, filters, and permissions. The agent still has to interpret the request, but it does not have to invent the calculation behind the metric.
In practice, semantic-layer capabilities show up in tools such as dbt Semantic Layer, Snowflake semantic views, Databricks metric views, Cube, AtScale, and Power BI semantic models. Microsoft renamed Power BI datasets to semantic models in November 2023 to better reflect the modeling capabilities behind its reports.
Self-service does not guarantee one shared definition. A large BI environment can hold many semantic models, each carrying measures shaped by a report author's understanding of the business. A semantic layer gives an approved definition a durable place to live. It cannot determine which of several competing definitions the business intends to approve.
That limit matters more when an AI agent becomes a consumer. A person may notice that two revenue numbers look suspicious. An agent can treat the selected definition as authoritative and keep moving.
A context layer adds the rules and state around the semantic model
A context layer assembles semantic definitions, lineage, ownership, policy, freshness, provenance, operational state, and supporting documents so an AI agent receives the context relevant to its current task.
The term is still settling. Some vendors describe a context layer as a superset of the semantic layer. Others use it for the runtime system that retrieves and packages context for an agent. The boundary matters less than the questions the architecture can answer: Which definition applies here? Who approved it? Is the source current? What policy limits its use? What happened before this event?
In May 2026, Gartner advised data and analytics leaders to establish a context layer as core infrastructure for agentic AI, arguing that schema-based models lack the business context and data meaning agents need.
Current platform designs show why the distinction is not clean. Databricks describes Unity Catalog semantics as the human-modeled layer of Genie Ontology, then combines that governed material with context inferred from assets and usage to form a unified context layer. The semantic layer sits inside the wider context available to the agent.
A context layer may also draw from data catalogs, lineage systems, policy engines, source documentation, tickets, query history, and agent memory. APIs and MCP can deliver that material at runtime. They provide access to context; they do not resolve conflicting business requirements on their own.
Semantic layer vs context layer at a glance
Semantic layer | Context layer | |
|---|---|---|
Primary job | Give metrics, dimensions, entities, and relationships a governed definition and query path | Assemble the semantic, operational, and governance context an agent needs for a specific task |
Typical contents | Metrics, dimensions, joins, calculations, filters, entities, and access rules | Semantic definitions, lineage, ownership, provenance, policies, freshness, valid time, documents, and operational state |
Where it usually lives | A BI, metrics, warehouse, or data-platform modeling layer | Across catalogs, governance systems, documents, semantic models, and runtime services, exposed through an agent-facing layer |
Primary consumers | Dashboards, analysts, applications, and AI agents | AI agents and other context-aware applications |
Revenue example | The approved formula and aggregation behavior for net revenue | Which approved definition applies to this period and use case, who owns it, where it came from, and whether the source is current |
What it cannot do | Decide which unresolved definition of revenue is right | Decide which unresolved definition of revenue is right |
The most useful mental model is nested, not parallel. The semantic layer governs meaning close to the data. The context layer delivers that meaning with the surrounding evidence, policy, and state the agent needs to use it correctly.
Neither layer can make an unresolved business decision
A layer can only serve context that exists.
Some context can be harvested from schemas, documentation, lineage, dashboards, query history, and source systems. Those sources can show which fields exist, how tables connect, who queried them, and which definitions appear in current reports. They can also recover some of the knowledge in people's heads once somebody has expressed it.
Other context only exists after business discovery forces a decision. Finance and Sales may use different revenue definitions. Two systems may disagree on customer status. A policy may describe returns but omit how to treat a backdated adjustment. No amount of metadata can name the authoritative rule until an owner does.
Consider a revenue definition that changed two quarters ago. The semantic layer can hold the current formula. The context layer can show who owns the metric, which reports still use the old formula, and when the new policy took effect. If no record establishes which definition Finance approved for board reporting, both layers preserve an unresolved conflict.
Decision precedents can only be stored after a decision has been made.
Coding agents make this gap expensive because they turn interpretation into implementation. If two sources disagree and nobody has established which one is authoritative, the agent still needs a path to keep building. A plausible choice can become transformation logic, tests, and downstream metrics before anyone notices that the agent made a business decision.
You cannot code your way to better business context.
A semantic layer is only as accurate as the model beneath it
Resolved business rules still need a data model capable of answering the intended questions.
In April 2026, dbt Labs reran its semantic layer versus text-to-SQL benchmark against the ACME Insurance dataset. The test used 11 natural-language questions, each run 20 times. After dbt added three models to expose relationships that the normalized source schema made difficult to traverse, the results were:
- Claude Sonnet 4.6: 90% for text-to-SQL and 98.2% for the dbt Semantic Layer
- GPT-5.3 Codex: 84.1% for text-to-SQL and 100% for the dbt Semantic Layer
Before that modeling change, questions requiring too many entity hops remained outside the semantic layer's scope. The semantic layer failed explicitly rather than returning a plausible wrong number. Adding the three models made every question answerable through the semantic layer and improved text-to-SQL at the same time.
Both approaches got better when the data underneath them became easier to reason over. The data model sets the ceiling. Source data quality sets the floor. A semantic layer or context layer cannot compensate for missing relationships, broken facts, or business rules that never made it into the model.
A spec gives business decisions a home before they become code
A spec records the decisions the data model, semantic layer, context layer, and coding agent need to share.
For a data pipeline, that means more than a summary of meetings or a folder of source material. A build-ready spec captures:
- Definitions with an owner and an authoritative source
- Transformation rules, entity mappings, and source precedence stated precisely enough to implement
- Edge cases with their expected treatment, including returns, backdated changes, currency, and late-arriving records
- Open decisions routed to the right owners before implementation
- Validation criteria tied to figures and outcomes the business trusts
Generating the spec often surfaces decisions the team never made explicit. A missing owner, conflicting date rule, undocumented exception, or absent validation target becomes visible before a coding agent fills the gap with an assumption.
The spec is not another runtime layer. It is the versioned record of discovery, evidence, approved resolutions, and validation criteria that feeds every layer downstream. This is the role of spec-driven development in analytics engineering: give a person or coding agent a stable target for the build and a way to check whether the result matches the business requirement.
Autopilot Spec turns complex business requirements from meetings, dashboards, documents, spreadsheets, and systems of record into a structured specification for data coding agents. It surfaces conflicts and missing decisions, records the approved resolutions, generates validation criteria, and packages the result for tools such as Claude Code, Cursor, Copilot, dbt Wizard, Snowflake CoCo, and Databricks Genie.
This is how a semantic layer gets an authoritative definition to govern, and how a context layer gets a decision it can trace and deliver.
Build in this order: resolve, specify, model, govern, deliver
- Resolve the business requirements. Gather the evidence, surface conflicts, and ask a named owner to decide which rule applies.
- Write the decisions into a spec. Record the source, approved definition, edge cases, and validation criteria so the decision survives the build.
- Model the data for the required outcomes. Shape the data so the questions, entities, and relationships in the spec are answerable.
- Govern stable meaning in the semantic layer. Encode approved metrics, dimensions, joins, and access rules once.
- Deliver relevant context to the agent. Combine semantic definitions with lineage, provenance, policy, freshness, and operational state for the task at hand.
This sequence is iterative. New evidence may send the team back to resolve a rule or revise the spec. The point is to stop an unresolved requirement from quietly becoming production logic.
Spec your data pipeline before you build with AI. See Autopilot Spec.