What is a semantic layer, and why do AI agents need one?
A semantic layer defines each business metric once, in code. Without one, AI agents guess what your metrics mean, and the answers change every time.
A semantic layer is the part of your data stack where every business metric is defined once, in code, and signed off. When a person, a dashboard or an AI agent asks for “net new ARR” or “active customers”, the semantic layer answers with the same definition every time. AI agents need one because without it they read raw tables and guess what your metrics mean, and the guess changes from question to question.
What does a semantic layer actually do?
It sits between your cleaned-up data and the tools that ask questions of it. Instead of each tool writing its own SQL, every tool asks the semantic layer for a metric by name, and the semantic layer turns that request into the right query.
In practice it holds three things:
- Metric definitions. What counts as revenue, which customers count as active, how churn is calculated, and which filters always apply.
- Relationships. How customers, subscriptions, invoices and accounts join together, so nobody has to remember the join logic.
- Access. One interface, usually an API, that dashboards, spreadsheets and AI agents can all call.
The point isn’t the technology. It’s that a definition is written down once, agreed by the people who own the number, and reused everywhere.
Why do AI agents get metrics wrong without one?
Point a capable model at a warehouse full of raw tables and ask “what was ARR last month?” It has to decide which table holds subscriptions, whether trials count, how to treat a mid-month upgrade, and what currency to use. It will make reasonable-sounding choices. It may make different ones tomorrow.
The problem isn’t that the model is careless. Your business rules aren’t in the data. They live in people’s heads, in a finance spreadsheet, or in a dashboard filter nobody remembers adding. An agent can’t follow a rule it can’t see.
A semantic layer makes those rules visible. The agent stops guessing and starts asking: “give me net_new_arr for October.” The answer comes back with the definition attached, so you can see exactly what was counted.
Isn’t a BI tool enough?
Many BI tools have a modeling layer of their own, and for dashboards that can work well. The catch is that those definitions usually live inside that one tool. An AI agent in Claude, ChatGPT or Slack can’t easily reach them, and a second tool ends up redefining the same metrics slightly differently.
A dedicated semantic layer, such as Cube, keeps the definitions outside any single front end. Dashboards, notebooks and agents all read from the same place. Connecting agents through an MCP server means they ask for certified metrics rather than writing their own SQL.
What does it take to set one up?
A semantic layer is the third step in a short chain. You can see the whole picture in how it works:
- A warehouse where your CRM, billing, product and ad data land in one place.
- Clean, tested models (usually in dbt) that turn raw tables into a reliable picture of the business.
- Certified metrics in the semantic layer, each one written down and signed off.
- Your agents, connected so they ask the semantic layer instead of the raw tables.
If you already have a warehouse or dbt, the work builds on top of it. What we deliver at each step is laid out in what you get.
How do you know the answers are right?
By checking them against a number you already trust. Before a metric is certified, its result should match the source of record: billing totals should match your billing system, and customer counts should match your CRM. Where they differ, the difference should be explained and agreed, not hidden.
That reconciliation step is what turns “the agent gave me a number” into “the agent gave me our number.”
FAQ
Do I need a data warehouse before adding a semantic layer?
Yes. A semantic layer describes data that already sits somewhere queryable. If your data still lives only inside SaaS tools, the first step is landing it in a warehouse such as Redshift, BigQuery or Snowflake.
Is a semantic layer the same as a metrics dictionary?
They’re related. A metrics dictionary is the written, human-readable list of definitions. The semantic layer is where those definitions are implemented in code. Ideally the dictionary is generated from, or checked against, the semantic layer so the two never drift apart.
Can my team maintain it without outside help?
They should be able to. Metric definitions are code in your own repository, running in your own cloud account. Good documentation means a new analyst can read a definition, change it and see the effect.