Text-to-SQL vs the semantic layer

There are two ways an analytics agent can turn a plain-English question into an answer. It can write SQL from scratch against your raw tables, which is text-to-SQL. Or it can query a semantic layer, where the metrics and relationships are already defined and the agent just picks from them. The choice matters more than it sounds, because it is the main thing that decides whether the numbers are right.

Here is the short version. Text-to-SQL is flexible and works on any schema, but it guesses, and on real data it guesses wrong often enough to be risky. A semantic layer is more accurate and consistent, but someone has to build and maintain it. The best agents use both, and knowing when each applies is the useful part.

What text-to-SQL does

Text-to-SQL takes your question and the database schema and generates a SQL query. Ask for “active users last month” and it looks at the tables, picks the ones it thinks are right, writes the joins and filters, and runs it.

The appeal is obvious. It works on any warehouse with no setup. Point it at a schema and it answers. This is why almost every analytics agent ships with text-to-SQL, and why the research has moved fast. Benchmarks like BIRD and Spider 2.0 measure exactly this, and techniques like DIN-SQL show that decomposing the problem and letting the model correct itself raises accuracy a lot.

The problem is what happens on a real warehouse. “Active” is not a column. “Last month” could be calendar or trailing 30 days. The user table might be one of four. The model fills those gaps with a guess, and the query still runs and still returns a number. Uber’s QueryGPT and Pinterest’s text-to-SQL work both ended up building heavy retrieval and context systems around the model for exactly this reason. The model alone was not enough.

What a semantic layer does

A semantic layer sits between the raw tables and the question. It is where someone defines, once, what “revenue” means, which table is canonical for users, and how “active” is calculated. The agent does not write raw SQL against your tables. It picks from metrics and dimensions that are already correct, and the layer compiles that into SQL.

The upside is accuracy and consistency. “Revenue” returns the same number whether it is asked by the agent, a dashboard, or a notebook, because it is defined in one place. Benn Stancil calls this the context layer, the shared place an organization’s business logic lives so every tool, including agents, works from the same definitions.

The cost is that someone has to build it. Metrics, dimensions, and relationships have to be modeled. Tools like dbt, Cube, and others exist to do this, but it is real work, and a semantic layer only covers the questions it was modeled for.

What the benchmarks say

This is not just theory. dbt Labs ran a head-to-head benchmark in 2026 and found the semantic layer reached 98 to 100 percent accuracy on a 15-table dataset, while text-to-SQL landed around 84 to 90 percent. The reason was not that text-to-SQL wrote broken queries. It was that it wrote plausible queries that quietly used the wrong join or the wrong filter.

Omni made the same argument from the field. Text-to-SQL fails silently and confidently on enterprise data, and a governed semantic layer is what removes the ambiguity. Cube framed it as why agentic AI needs a semantic core. The pattern across all of them is the same. The model is fine. The missing piece is defined meaning.

When to use each

They are not really competitors. They cover different questions.

Use the semantic layer for anything that has to be right. Board metrics, revenue, KPIs, anything someone will make a decision on. These should be defined once and served from the layer, not regenerated on every query.

Use text-to-SQL for exploration. Ad hoc questions, one-off pulls, digging around in tables nobody has modeled yet. Here the flexibility is worth the lower accuracy, because the stakes are lower and a human is usually in the loop.

The strongest agents route between the two. A question about a defined metric goes through the semantic layer. A question about something unmodeled falls back to text-to-SQL, ideally with the schema context and a correction loop to catch obvious mistakes. This is a context engineering problem more than a model problem. Open-source agents like nao are built around giving the agent that defined context, so it reaches for a metric when one exists and writes SQL only when it has to.

The takeaway

If you are choosing a tool or building an agent, do not ask whether it does text-to-SQL. They all do. Ask what it does when the question touches a metric that matters. An agent that leans on a semantic layer for those, and falls back to text-to-SQL for exploration, is the one you can trust with a number. You can see how the current tools handle this on the compare page.

Is text-to-SQL or a semantic layer more accurate?

A semantic layer is more accurate for defined metrics. In dbt’s 2026 benchmark it reached 98 to 100 percent versus 84 to 90 percent for text-to-SQL, because the layer removes the ambiguity that text-to-SQL has to guess at. Text-to-SQL is more flexible for exploring unmodeled data, where lower accuracy is an acceptable trade.

Do you need a semantic layer to use an analytics agent?

No, but you need one for the answers that have to be right. An agent can run on text-to-SQL alone, and that is fine for exploration. For metrics people make decisions on, a semantic layer is what keeps those answers consistent and correct.

Can an analytics agent use both text-to-SQL and a semantic layer?

Yes, and the best ones do. They send questions about defined metrics through the semantic layer and fall back to text-to-SQL for anything unmodeled. Routing between the two, with schema context and a correction loop, is what separates a reliable agent from a demo.