Context engineering for analytics: why your LLM needs more than a database connection

Gartner called it in mid-2025: prompt engineering was out, context engineering was in. The term stuck because it names something practitioners had already figured out: most agent failures aren't model failures. They're context failures.

Nowhere is this more measurable than analytics. We run a platform that sits between LLMs and company databases, which means we see exactly what happens when a model has a connection but no context. Across 76,000+ AI-generated SQL queries in our logs, 71% of all errors were "invalid identifier": the model referencing a table or column that doesn't exist. Not because the model is bad at SQL. Because it was guessing at what the database means.

A database connection gives the model access. Context engineering is everything that turns access into understanding.

Why text-to-SQL disappointed

Text-to-SQL was supposed to be solved. The benchmarks looked great. Then teams pointed models at real production schemas and watched them fail in ways the benchmarks never measured.

A benchmark schema has tables named customers and orders with columns like total_amount. A real production schema has usr_acct, ord, and sub, with three revenue-ish columns and business logic nobody wrote down: refunded orders don't count, test accounts get excluded, the status column has seven values and only two mean "completed."

We watched this play out in a single logged session: a user asked for average order value, and Claude worked through six wrong column guesses before finding the real one. The connection worked perfectly the entire time. What was missing was everything around the connection. (We broke this session down in our guide to connecting AI to company data.)

What context an analytics LLM actually needs

Four layers, in order of how often teams skip them:

1. Schema semantics. Not just table and column names, but what they mean. sts is a status enum with these values. crt_at is the creation timestamp; use it for reporting, not upd_at. This table is deprecated; use the other one.
2. Metric definitions. "Revenue" is a formula someone decided, not a column the model can find. Same for active users, churn, take rate. Without a definition, every conversation re-derives the metric, and two people asking the same question get different numbers.
3. Business concepts. The vocabulary that maps how people talk to how data is stored. When someone says "enterprise customers," which filter is that? When they say "this quarter," is your fiscal year offset?
4. Permissions as context. This one is counterintuitive: access control isn't just governance, it's context narrowing. Every table you hide from the agent is a table it can't get confused by. A model choosing between 12 relevant tables is more accurate than one choosing between 200.

Notice what's not on the list: better prompts. A system prompt that says "be careful with SQL" does nothing. Context is data about your data, and it has to be assembled and maintained somewhere.

The part everyone underestimates: context goes stale

The first version of context is easy. You write table descriptions, define your metrics, done. Then the schema changes.

A column gets renamed in a warehouse cleanup. A saved query written three months ago now references a column that doesn't exist. The error it throws, "invalid identifier," is indistinguishable from the model hallucinating a column name. We wrote about this in our error analysis: a meaningful share of what looks like hallucination is actually stale context, and the fix is completely different.

This is where manually curated context systems go to die. The doc was accurate in January. By June, three tables were added, one was renamed, and the person who wrote the doc left. The model is now confidently wrong, which is worse than being obviously wrong.

The practical answer has two parts. First, schema sync has to be automatic: Contextflo re-syncs schemas daily, so the model's picture of what tables and columns exist doesn't drift from reality. Second, the semantic layer on top, descriptions, definitions, saved queries, has to be watched: the system flags where context has gone stale or definitions are missing, so the data team fixes what matters instead of re-auditing everything.

Context engineering as a discipline, not a project

The teams that get durable value from AI analytics treat context the way they treat code:

• It has an owner (usually whoever owns the data)
• It's generated from the source where possible, not hand-written
• It's updated when the schema updates
• It's shared: one context, every user, every conversation
• It's scoped: each user's context includes only what they're allowed to see

The teams that struggle treat context as a one-time setup task, a big Notion doc pasted into a Claude Project. That works for exactly one person for about a month.

What Contextflo does

Contextflo does the context engineering for you. It connects to your database and to your context sources, the schema, your source code, your internal documents, and extracts metadata for every table and column from them. It holds your metric definitions and business concepts, scopes context per user through access controls, and serves it on demand to whatever model your team uses, Claude, ChatGPT, or whatever comes next.

The context is the durable asset. Models will keep changing. What your data means doesn't change with them.

Here is a more in-depth look at Contextflo and how it works.