A database schema is a document written in a private language. Column names are abbreviations of concepts the original engineers understood intuitively. Table relationships encode business rules that were never written down elsewhere. Naming conventions vary by team, by era, and by the preferences of whoever wrote the first migration. No two enterprise schemas look the same.
When an AI system is asked to query this schema, it faces a translation problem. Not from English to SQL — that part is well-studied. From the SQL the LLM knows from training to the specific SQL dialect, naming conventions, and semantic idioms of this particular organisation's database. These are not the same thing, and treating them as though they are is the root cause of most production text-to-SQL failures.
"The LLM was not trained on your database. It was trained on every database that was ever put on the internet. Yours is not on the internet."
The Vocabulary Problem
Every enterprise database has its own vocabulary. Consider the word "active." In a retail operations database, is_active = 1 might mean the store is currently open for trading. In a supplier database, STATUS = 'ACTIVE' might mean the supplier contract is in force. In an inventory system, there may be no concept of "active" at all — items are either in stock or not.
An LLM querying across all three sources must understand that "active" in the user's question maps to three different column names, three different data types, and three different business semantics. Getting one wrong produces a subtly incorrect result with no error message.
This is not a problem LLMs solve through general intelligence. It is a problem they solve through schema context: detailed descriptions of column semantics, sample values, and the business meaning of key distinctions, passed as part of the prompt for every query. The quality of this context determines the quality of the generated SQL far more than the capability of the model itself.
What Good Schema Context Looks Like
There is a significant difference between schema context that gives the model a fighting chance and schema context that sets it up to fail. The difference is not the amount of information — it is the specificity of semantic annotation.
Columns:
- STORE_ID INT
- STATUS VARCHAR(10)
- CITY VARCHAR(50)
- PHONE VARCHAR(20)
- STORE_ID: primary key (INT)
- STATUS: 'ACTIVE'|'CLOSED'|'TEMP_CLOSED'
→ use STATUS='ACTIVE' for open stores
- CITY: city name, no abbreviations
- PHONE: format '(NXX) NXX-XXXX'
The minimal context tells the model that a STATUS column exists. The semantic context tells it what values the column takes, which value answers the most common query about "active stores," and what the format of adjacent columns looks like. This is the difference between generating a query that might work and generating a query that is correct the first time.
Sample values as semantic anchors
Column names are often abbreviated or cryptic. acct_typ_cd might mean account type code — or account type category, or account tier classification. The name alone is insufficient. But if the sample values are 'PREMIUM', 'STANDARD', 'TRIAL', the semantics become clear immediately, both to the model and to the human reviewing the generated SQL.
Sample values serve another function: they reveal the actual data quality of the column. A column nominally of type VARCHAR(20) whose sample values are all uppercase with specific patterns tells the model far more about how to filter it than its type declaration alone.
Schema Fluency vs. Schema Knowledge
There is a distinction worth drawing between a system that knows a schema and one that is fluent in it. Schema knowledge is static: the model has been given the schema definition and can reference it. Schema fluency is dynamic: the system has observed patterns across many queries against the schema and has developed an accurate model of how the schema behaves in practice.
Fluency develops through usage. When a query for "active stores" consistently produces the most useful results when using STATUS = 'ACTIVE' rather than IS_OPEN = 1 (a column that also exists but is updated less frequently), the system learns this pattern. When users consistently correct queries that use ORDER BY STORE_ID to use ORDER BY STORE_NAME, the system learns that users prefer alphabetical store ordering over ID ordering even when they don't specify it.
Schema ingestion
System reads table definitions, column types, and constraint metadata. Base schema context established. No query history available — all queries go to the LLM generation path.
Pattern emergence
Common queries execute repeatedly. Users begin finalising queries they find correct. Override cache starts building. Sample value patterns observed across query results enrich semantic context.
Domain vocabulary
Org-specific terminology reliably mapped to schema elements. Correction loop fires less frequently. Most common queries served directly from override cache without LLM involvement.
Schema fluency
System understands idiomatic query patterns, implicit filters, and semantic conventions. Novel queries generate correctly on the first attempt for the large majority of cases. Schema changes are automatically reflected in context.
The Hallucination Boundary
LLMs trained on public code have seen thousands of database schemas. This training data creates strong prior expectations: common column names for common concepts, typical table structures, standard naming conventions. When the model's priors conflict with the actual schema, the model's priors frequently win — producing SQL that references columns that don't exist or tables named the way they would typically be named, not the way they actually are in this database.
This is hallucination, and it is the most common failure mode of text-to-SQL in production. The fix is not a more powerful model — it is stronger schema grounding that makes the actual schema more salient than the model's priors. Complete column lists, explicit "do not use this column" annotations for deprecated fields, and sample values that contradict common naming assumptions all help push model attention toward the real schema.
Deprecated and misleading columns
Most enterprise schemas have columns that exist for historical reasons, are populated inconsistently, or have been superseded by newer columns with cleaner semantics. An LLM that uses legacy_status because it infers its meaning from the name will produce subtly wrong results. Explicit schema annotations marking these columns as deprecated — and pointing to their replacements — prevent this class of error entirely.
Schema Evolution
A schema that was registered with the system six months ago may have changed significantly. Columns added, columns renamed, tables split, data types altered. Static schema context goes stale. A system that continues generating SQL against a schema snapshot from last quarter will produce an increasing rate of failures as the gap between the snapshot and reality widens.
Dynamic schema context — refreshed on a cadence calibrated to how frequently the source schema changes — ensures the model always operates against the current schema state. Schema change detection can flag when registered sources have changed, prompting context refresh rather than allowing silent staleness to accumulate.
This is particularly important for the query override cache. SQL stored months ago may reference columns that have since been renamed. Override cache invalidation triggered by schema change detection prevents confirmed-correct SQL from silently becoming incorrect as the underlying schema evolves.
Part of the Vertiscope AI research series on semantic query intelligence.