Text to SQL LLM: Schema, Guard, Then Run

By William Zhu & the InfiniSynapse Data Team · Published: 2026-06-09 · Last updated: 2026-09-23 · Last verified: 2026-09-23 · About: Editorial standards · About / team · Contact: zhuhl@infinisynapse.com

Author credentials: William Zhu is cofounder of InfiniSynapse (GitHub @allwefantasy). Desk experience: reading generated SQL before it hits a warehouse, and rejecting queries that name a table the schema snapshot does not contain. No personal LinkedIn is published; GitHub and InfiniSynapse About are the identity signals.

COI / interest disclosure: We build InfiniSynapse, an AI-native analysis layer. Product mention appears only in the closing practice link. The five-step contract and the teaching query stand without a trial.

Fact-check / verification: The weekly-active SQL below is a teaching composite, not a customer extract. The catch-point chart is illustrative. The n=10 pilot figures are the same independence-labeled desk composite already used on this page (marker DESK-TTS-TITLE-20260805A), not a new survey. Corrections: zhuhl@infinisynapse.com · editorial corrections.

Version history: 2026-06-09 pattern guide · 2026-08-04 title pass · 2026-09-23 retarget to text to sql llm as schema, guard, then run. Marker: DESK-TTS-20260923A.

Media note: No hosted overview video. Use the five-step table, the wrong-join example, and the illustrative catch-point chart.

Table of Contents

1. TL;DR
2. How we check a run
3. What a text to SQL LLM does
4. Schema linking before the prompt
5. What the prompt must contain
6. Guard the query before it runs
7. When the SQL runs and the answer is still wrong
8. Public benchmarks versus your questions
9. A model step is not an agent
10. When not to fine-tune
11. Frequently Asked Questions
12. Conclusion

TL;DR

Direct answer: A text to sql llm turns one natural-language question into SQL only after three gates: link the relevant tables and columns, validate the statement, then dry-run it on a read-only role. A chat box that prints SQL and stops is not that pipeline.

Who this is for: platform and analytics reviewers who must decide whether a text to sql llm may touch a warehouse.

What you leave with: the five-step contract, a wrong-but-runnable query, and the fields that belong on the audit row.

Broader natural-language setup, including a Python sidecar, stays on natural language to SQL. This page owns the model step inside that setup.

How we check a run

We evaluate a text to sql llm by reading the SQL and the schema snapshot side by side. SQL is a language for tables, predicates, and joins. The model does not get a free pass because the statement parses. Google's write-up on techniques for improving text-to-SQL makes the same split: retrieve tables and columns first, then prompt, then judge the SQL. We keep that order and add a dry run before any full scan.

What we open first

The question, the schema slice that was actually sent, the generated statement, and the role it would use. If the slice is the entire catalog, the text to sql llm was not linked. If the role can write, the text to sql llm was not guarded.

What fails the run

A run fails when the statement names a table absent from the slice, when a join key is guessed, when there is no row cap, or when the result returns with no error and the metric is still the wrong one. Those last cases are why a green grid is not evidence. We log them as silent misses, not as model taste.

What a text to SQL LLM does

Key Definition: A text to sql llm is the model step that writes one SQL statement from a question plus a linked schema slice. It does not own metric meaning, warehouse permission, or the decision to publish a number.

Five steps

Copy this order into the ticket before anyone compares model brands. A text to sql llm that skips step 1 will look fluent on a demo schema and miss on yours.

What the model does not do

It does not certify a chart, choose a semantic-layer owner, or replace a gold question set. Public leaderboards stay on NL2SQL benchmark. Dialect differences stay on dialect-aware SQL generation. The model step is finished when the audit row exists. Publishing the number is a separate sign-off.

Schema linking before the prompt

Large warehouses have more columns than a prompt should hold. Extractive schema linking is the research version of a practical rule: for one question, most columns are noise. A text to sql llm that receives every column will still emit SQL. The SQL will often join a similarly named table.

Choose the tables

Start a text to sql llm from nouns in the question and from foreign keys, not from a vector hit on table descriptions alone. If two tables share a name stem (accounts, account_flags), both must be listed or the exclusion must be explicit. We require the linker to return table, column, and why. A text to sql llm with no "why" column cannot be reviewed when the join is wrong.

Drop the extra columns

For a text to sql llm, keep keys, the columns named by the question, and the columns named by the metric note. Drop the rest. PostgreSQL's SELECT reference is a reminder that a query can be valid and still scan columns nobody asked for. Linking is how you stop that before generation. Teams that stuff the full information schema into the prompt are paying for context, not for accuracy.

What the prompt must contain

Dialect, keys, and definitions

Name the dialect in the first line. State the join keys you allow. Paste the metric sentence a human already signed, for example "active means three sessions in seven days," not "use your judgment." IBM's structured query language overview is enough background for a reviewer who needs the vocabulary. The prompt is the contract. A text to sql llm will follow a confident wrong sentence if that is the only definition it sees.

Three checked pairs

Add up to three question–SQL pairs from the same schema, already executed and signed. Do not add pairs from another warehouse to "show the style." A text to sql llm copies join shape from those pairs. A borrowed shape is how a retail key lands on a subscription table. If you have no signed pairs yet, ship with zero examples and a human on the first twenty questions. Fake examples are worse than none.

Guard the query before it runs

Read-only role and a row cap

The role used for generation's output can select, not insert, update, or drop. Put a row cap on the dry run. Reject a second statement in the same string. Database engine permissions are the pattern: the model is not a principal, the role is. A text to sql llm that shares an analyst's write login will eventually run a statement someone did not mean to approve.

Dry run on a sample

Execute the text to sql llm statement against a bounded sample or a LIMIT before the full scan. Compare row count and one grouped total to the last accepted run when the question repeats. If the dry run errors, send the database message back once. If it succeeds and the metric note is unmatched, stop anyway. Success is not the pass rule. The pass rule is "the statement matches the linked slice and the signed definition." Budget 10 minutes for that comparison on a new question. Repeats should be shorter once the audit row exists.

When the SQL runs and the answer is still wrong

Teaching composite, not a customer warehouse. Question: "Weekly active accounts by plan tier for the last quarter, excluding internal test accounts."

A prompt-only text to sql llm often returns runnable SQL that treats last_login as active and filters internal users by email domain. The team's definition is three sessions in seven days, and internal accounts live in account_flags, not in the email string. The statement parses. The chart plots. The number is still wrong.

-- Wrong, but it runs. Teaching composite only.
SELECT plan_tier, COUNT(DISTINCT account_id)
FROM accounts
WHERE last_login >= CURRENT_DATE - INTERVAL '90 days'
  AND email NOT LIKE '%@internal.example'
GROUP BY plan_tier;

The guarded version loads the signed active rule, joins account_flags, and refuses the email heuristic. That is the difference a text to sql llm pipeline has to show a reviewer. On the earlier desk composite (n=10 pilots, independence labeled), prompt-only week-1 charts failed first pass in 7 of 10 cases, and wrong metric or join showed up in 6 of 10. After linking plus a guarded run, private gold-set exact match moved from 61% to 84%, and median review time moved from 22 minutes to 9. Those figures are that composite, not a market study. Re-measure them on your own questions.

How the catch points split

The chart is illustrative. It is not the n=10 composite. It shows where three error classes should die if the pipeline is real.

If invented tables still reach the warehouse, linking is decorative. If missing row caps reach the warehouse, the guard is not in the path. Read the chart as a placement test for the text to sql llm, not as a vendor score.

Public benchmarks versus your questions

Spider and BIRD measure a text to sql llm on public databases. They are a useful ceiling check and a poor acceptance test. A text to sql llm can score well there and still miss account_flags in your catalog. Freeze thirty questions from last quarter's real asks, with gold SQL a person already ran. Score exact match and execution match on that set. How to build the scorecard is on evaluate text to SQL accuracy. Do not procure from a leaderboard row.

Use the same thirty questions when the schema changes. A model swap that lifts the public number and drops two of your thirty is a regression. The text to sql llm under test is the whole path, including the linker, not the model name on the invoice.

A model step is not an agent

A text to sql llm writes one statement. An agent may look at the sample, change the statement, or stop and ask. Those are different products. The comparison lives on SQL agent vs text-to-SQL. Buy the model step when a reviewer will read every statement. Buy the agent when the same question repeats and a person only signs exceptions.

Where the agent starts

The agent starts after step 4 in the table above, not instead of it. If the agent can skip linking, you have a chat box with a tool. Context for that linking decision is either a semantic layer or retrieved SQL. The tradeoff is on semantic layers vs SQL RAG. Neither one replaces the read-only role.

When not to fine-tune

Fine-tune after the linker and the three checked pairs are stable. If columns move every week, a fine-tune memorizes last month's names. Fix the slice and the examples first. The fine-tune page is text to SQL fine tuning. A text to sql llm that fails because the prompt omitted the metric sentence will fail the same way after training.

Ship the five steps on one schema and one dialect. Add a second dialect only when the first thirty questions hold for two sprints. That sequence is slower than a demo and faster than a quarter of silent charts.

Frequently Asked Questions

What has to happen before the model writes SQL?

Link tables and columns, and put the signed metric sentence in the prompt. Generation on the full catalog is the failure mode, not a shortcut.

Why can a query succeed and still be wrong?

The database checks syntax and types. It does not check whether last_login matches the business word "active." Compare the statement to the metric note, not only to the error log.

Are Spider or BIRD scores enough to pick a model?

No. Use them as a public ceiling. Accept or reject on your own thirty questions with gold SQL. A public gain that drops your set is a regression.

When should a person still read the statement?

On the first twenty questions, on any metric that changed this month, and whenever the dry run disagrees with the last accepted total. Repeats with an unchanged slice can rely on the audit row.

Conclusion

A text to sql llm is a gated writer of one SQL statement: link the schema, fill the prompt with dialect and signed definitions, then dry-run as a read-only role and store the audit row. The runnable wrong query on weekly active accounts is the test. If that statement can reach the warehouse, the pipeline is still a chat box. Structural papers and public leaderboards stay in their lanes. This order is the one a second person can rerun next week.

InfiniSynapse can host the audit row and the read-only path when the warehouse, not a file, is the source. It does not replace your metric owner. The five steps above stand without a trial.