Semantic Layers for LLMs: What AI Agents Actually Need From Context

Dashboard-era semantic layers break for AI agents. What LLMs need instead: file-based context, synced to Git, that you own and any agent can read.

An AI agent needs three things from a semantic layer that a dashboard never did: the join paths that make a question answerable, the definitions that make an answer correct, and a way to read both before it writes a single line of SQL. A classic BI semantic layer supplies the first two but keeps them inside a vendor's platform, where no other agent can reach them. The version that works for LLMs is file-based context — SQL, Markdown, and Python in version control, sitting next to your dbt project — that any agent can load, and that stays yours if you change tools.

This article covers what a semantic layer actually does for an LLM, why the dashboard-era version breaks when agents start using it, how the main approaches compare, and how to build context that a model can read on day one and still trust in month three.

What a Semantic Layer Does — and What Changed When Agents Arrived

A semantic layer maps warehouse tables into business concepts. Instead of fct_orders joined to dim_customers on a surrogate key, you get "orders" and "customers," and a question about revenue resolves to one agreed calculation. For most of the last decade that layer existed to keep dashboards consistent: a human built a model, a human dragged fields onto a canvas, and the layer stopped two dashboards from disagreeing about gross margin.

An LLM does not drag fields. It reads. Whatever it can read at the start of a session is the entire universe it reasons about, and anything it cannot read it will infer from column names — confidently, and often wrong. That single change reframes the whole problem: a semantic layer for agents is less a modelling tool and more a governed context layer whose job is to be legible to a machine.

The Three Things an Agent Cannot Infer From a Schema

Join paths. A warehouse with two hundred tables has thousands of syntactically valid joins and a handful of correct ones. Nothing in the DDL says which fact table is the grain of truth for revenue, or that subscriptions must be joined through the account table rather than directly to users.
Business definitions. Churn, active customer, qualified lead, net revenue, and "last quarter" all have a specific meaning inside your company and a different one everywhere else. A model that guesses will produce a number that looks reasonable and cannot be reconciled with the board deck.
The filters nobody wrote down. Test accounts, internal orgs, refunded orders, the region code that changed after a migration, the two months of double-counted events. These are invisible in the schema and fatal to an answer. They are the single most common reason an agent's SQL runs cleanly and returns the wrong number.

Give an agent those three things and text-to-SQL stops being a party trick. Withhold them and you get plausible SQL, which is worse than no SQL, because someone senior now has to check every answer. That review burden is the real cost of ungoverned context.

Why Dashboard-Era Semantic Layers Break for LLMs

The Sync Treadmill

dbt changes weekly. The semantic layer YAML, the agent's system prompt, and the dashboards that depend on both change on someone's schedule. One-way syncs make it worse: the moment your definitions live in a different system from your transformations, drift is guaranteed and only discovered when two numbers disagree in a meeting. A semantic layer that lives in the same repository as the models it describes gets reviewed in the same pull request — drift becomes a merge conflict instead of a surprise.

Context Lock-In

Most platforms store semantic definitions inside their own database, exposed through their own API. That is a reasonable product decision and a bad position for the buyer. The definitions are the expensive part — months of accumulated agreement about what your business means — and if they only exist inside one vendor's platform, they cannot be used by Claude, by an internal agent, by a data science notebook, or by whatever you buy in two years. Context is your biggest asset; it should be yours.

Context That Starts at Zero

A raw warehouse MCP server (Snowflake's, BigQuery's, or a Postgres connector) hands an agent a schema and lets it explore. It works, and it means every session begins by rediscovering the join logic, the test-data filter, and the churn definition — burning tokens and time, and taking a fresh chance to get it wrong. Arriving with context is faster and leaner than rediscovering it, which is exactly the gap a semantic layer for agents is meant to close. If you are evaluating this path, our breakdown of warehouse MCP servers is a useful starting point.

Four Approaches to Semantic Context for LLMs, Compared

Approach	Where context lives	Who else can use it	Main failure mode
Raw warehouse MCP (Snowflake, BigQuery, Postgres)	Nowhere — schema only	Any MCP client	Rediscovers joins and definitions every session; no shared definition of a metric
BI-vendor semantic layer or metrics API	Inside the vendor platform	Usually that vendor's own surfaces	Context lock-in; other agents cannot read it; often gated behind a sales contract
DIY prompt harness plus YAML	A repo you maintain by hand	Whatever you wire up	Someone owns the harness forever; YAML drifts from dbt
File-based context layer synced to Git	Plain SQL, Markdown, and Python files in your repo	Any agent, with or without the vendor's MCP	Requires review discipline — definitions still need a human to approve them

None of these is universally correct. A team running three tables in Postgres does not need a context layer. A team with a real warehouse, a growing request queue, and colleagues already pasting questions into Claude will hit all four failure modes in the first quarter.

What File-Based, Git-Synced Context Looks Like in Practice

This is the approach Querio takes, and it is deliberately unglamorous. Joins, metrics, definitions, and trusted queries are stored as plain SQL, Markdown, and Python files, synced to GitHub — in the same repository as your dbt project. There is no proprietary format to learn and no export step, because the files are the source of truth.

The Agent Proposes, Humans Approve

Context does not get written in one sitting. It accumulates from real questions. When the agent works out a join or a metric definition while answering something, it proposes saving it — "save this as a reusable definition?" — and only a logged-in user can approve and commit it. That keeps the loop honest in both directions: the agent surfaces the knowledge, a human decides whether it is right, and the commit history shows who agreed to what. Month three is genuinely better than week one, because month three has three months of approved decisions in it.

It Travels

Because the context is files in your repository, it keeps working with Claude Code or any other agent — even without Querio's MCP server in the loop. That is the practical test for lock-in: if you turned the vendor off tomorrow, would the definitions still be usable by something else? If the answer is no, you are renting your own business logic.

Permissions Follow the Person, Not the Agent

Agent access is where governance usually falls over. Querio's MCP uses OAuth, so a query issued inside Claude inherits that individual user's data permissions rather than running as a shared service account. Combined with read-only encrypted warehouse credentials and role-based access control, this means opening analytics to an assistant does not quietly open the warehouse to everyone. If you are setting this up, we have a step-by-step guide to connecting Claude to a data warehouse over MCP.

Lineage Learned From Real Usage

Column-level lineage built from how queries are actually written tells you which definitions matter and which are decorative. It also tells you what breaks when a dbt model changes — the difference between a semantic layer you maintain speculatively and one that tells you where the risk is.

How to Build a Semantic Layer Agents Can Actually Use

Start with the ten questions you answer every week. Not the data dictionary. The recurring asks — revenue by plan, churn by cohort, pipeline by source — are where consistency pays off first, and they are small enough to finish.
Write down the filters, not just the metrics. "Exclude internal accounts, exclude orders with status refunded, use created_at in UTC" is more valuable to an agent than a beautifully formatted metric tree. Filters are the invisible logic; capture them explicitly.
Put it in the repo next to dbt. Same repository, same pull requests, same reviewers. If a model change alters a definition, both move in one commit and both get reviewed by the person who understands them.
Make approval a review, not a ticket. If adding a definition requires filing a request with the data team, the context layer stops growing in week two. Let the agent draft, let a human merge.
Test it like code. Keep a fixed set of questions with known-correct answers and rerun them when definitions change. Text-to-SQL accuracy is measurable; treat it as a regression suite rather than a vibe. Our note on metrics for testing text-to-SQL accuracy covers the mechanics.
Prune. Stale definitions are worse than missing ones, because the agent trusts them. Delete what usage data says nobody asks for.

Is Your Semantic Layer Agent-Ready? A Short Checklist

Can an agent read the whole thing without an interactive UI or a proprietary SDK?
Does it live in version control, in the same repo as your transformations?
Does it capture filters and join paths, not only metric formulas?
Can a second, unrelated agent use it tomorrow if you switch vendors?
Is there a human approval step between "the agent learned something" and "this is now the company definition"?
Do agent queries inherit the asking user's permissions?
When the model does not have the data, does the system say so instead of producing a number?

That last point matters more than any modelling detail. An analytics agent that answers only from what is actually in the data — and says "I don't have this" when it is not there — is the difference between a semantic layer that reduces review work and one that adds to it.

Frequently Asked Questions

What is the difference between a semantic layer and a context layer?

A semantic layer traditionally means the modelled mapping of tables to business entities and metrics — the part that keeps dashboards consistent. A context layer is broader: it includes those definitions plus the join paths, filters, trusted queries, and written explanations an agent needs to reason correctly. In practice the distinction is about audience. Semantic layers were designed for a query builder; context layers are designed to be read by a model. See our comparison of a metrics layer versus a semantic layer for the modelling side of this.

Do I still need dbt if I have a semantic layer for AI?

Yes. They solve different problems. dbt transforms and tests the data; the semantic or context layer describes what the resulting tables mean and how to use them. Keeping both in the same repository is what stops them drifting apart — the sync treadmill is caused by separation, not by having two tools.

Can an AI assistant like Claude use my semantic layer directly?

It can, over MCP, provided the layer is exposed in a form the assistant can read and the connection carries the user's permissions. This is why file-based context is useful beyond any one product: files can be loaded by an MCP server, by Claude Code reading the repo, or by an internal agent, without a re-implementation for each.

How much context is too much?

Context competes with the question for the model's attention, so more is not automatically better. Prioritise the definitions and filters that change answers, prune what usage shows nobody asks about, and prefer precise short descriptions over long prose. A tight, current layer outperforms an exhaustive, stale one.

What happens when a metric definition changes?

With file-based context it is a pull request: someone changes the definition, a reviewer approves it, and every surface that reads the repo — notebooks, dashboards, Slack answers, MCP calls from inside Claude — picks up the new logic from the same source. The audit trail of who changed what and when is the commit history, which is usually what an auditor or a confused stakeholder actually wants.

If you are weighing this against building your own harness, the maintenance question is the one to sit with: the model is the same for everyone, so the harness is the product. Querio's MCP and API are free to start with 100 questions a month and no payment details required, which is enough to test whether context-first answering behaves differently on your schema than schema-only exploration does.