Text-to-SQL — AI Glossary

Reference details

Related terms

• Table Question Answering
• AI Data Analyst
• Code Generation

How it works

1. Schema is supplied as context: table names, column names and types, primary and foreign keys, and ideally a sentence per table saying what it holds. The model cannot infer that 'dt' is a date or that 'cust_ref' joins to 'customers'.
2. Schema linking narrows the context before generation. Full schemas exceed useful context length and dilute attention, so relevant tables are selected by embedding or keyword match against the question first.
3. The model generates SQL, usually with few-shot examples in the target dialect, because dialect differences in date functions, string handling and window syntax are where generic SQL fails.
4. A validation pass parses the SQL and checks that referenced tables and columns exist. This catches hallucinated column names before they reach the database, and is cheaper than executing.
5. Execution against a read-only connection with a row limit and a timeout is the real guardrail. Generated SQL is untrusted input, and a cross join on two large tables is a denial-of-service you wrote yourself.
6. Self-correction feeds the database's error message back for a bounded number of retries, which fixes syntax and name errors reliably — and does nothing for a query that runs successfully and answers the wrong question.

Example: Why execution accuracy is the only honest metric

Consider 100 questions. String-matching generated SQL against reference SQL might mark 60 correct, because `WHERE status = 'active' AND region = 'EU'` and `WHERE region = 'EU' AND status = 'active'` are different strings and identical queries. Execution accuracy — run both, compare result sets — might mark 78 correct on the same output, since 18 of the 40 'wrong' queries return the right rows by a different route. The 18-point gap is scoring methodology, not capability. The dangerous residue is the reverse case: a query that executes cleanly, returns plausible rows, and silently answers a different question — an inner join dropping customers with no orders where the question asked about all customers. Those are correct by syntax, correct by execution, and wrong by intent, and no automated metric catches them. That is why production text-to-SQL shows the generated SQL to the user rather than only the answer.

Commonly confused with

Text-to-SQL is not table question answering, though they overlap. Text-to-SQL generates a query executed by a database engine, so it scales to tables of any size and inherits the engine's exact aggregation. Table QA feeds the table contents to the model as text, which works on small tables, needs no database, and cannot reliably sum a column of 10,000 rows. The choice follows the data size and whether an engine exists: a spreadsheet attached to a chat is table QA, a warehouse is text-to-SQL.

When to use it

Reach for it when:

• A real database exists and users need aggregate answers that the engine should compute rather than the model.
• The schema is stable and documented, so linking and few-shot examples can be built once.
• Queries are mostly within a known family — filters, groupings, joins across documented keys.
• The generated SQL can be shown to the user, making the model's interpretation of the question reviewable.

Reach for something else when:

• Against a write-capable connection, ever. Read-only, row-limited and timed-out is the baseline, since generated SQL is untrusted.
• On undocumented schemas with cryptic column names, where the model's guesses about meaning are unverifiable.
• Where silently wrong answers are costly and no one reviews the SQL. Join semantics are the common failure and they execute cleanly.
• For small attached tables with no database behind them, where table QA is simpler and has no injection surface.

Continue your research

Use these connected ModelRefs sections to compare alternatives, inspect implementation paths, and review the evidence and governance boundaries relevant to Text-to-SQL — AI Glossary.

• Browse models
• Review providers
• Inspect benchmarks
• Explore workflows
• Learn AI concepts
• Read decision guides
• Review trust and methodology
• Start a decision path