Case study
SQL RAG
A text-to-SQL agent that answers plain-English questions about BigQuery data, shows how it got there, and only ever reads.
The problem
Analysts spend a large share of their time turning recurring business questions into SQL, and business users wait on them. Generic LLMs write plausible-looking SQL that invents tables, gets joins wrong and returns numbers nobody can verify.
How it works
(01)
Retrieve
Find the most similar example queries in a vector index of known-good SQL.
(02)
Schema
Inject only the tables and columns those examples and the question need.
(03)
Generate
Gemini 2.5 Pro writes BigQuery SQL, with the conversation for follow-ups.
(04)
Validate
Deterministic checks: read-only, known tables and columns, a byte limit.
(05)
Execute
Run on BigQuery, then pick the chart and headline numbers from the result.
Results
Production version, at Walmart
Over Walmart BigQuery schemas and a 12K-query corpus. Internal.
- SQL accuracy
- faster query creation
- saved per 100 queries
This public demo
On BigQuery's public thelook_ecommerce dataset.
- orders to query
- example queries indexed
- question to chart
Design decisions
Show the work
Every answer has a trace: the example queries retrieved, the tables used, the model, tokens, and BigQuery time and bytes. People trust an answer they can check.
The LLM proposes, deterministic code decides
The model writes SQL; code decides whether it runs. Validation is rule-based, the query is read-only, and there's a cap on bytes billed.
Retrieval over prompt-stuffing
Similar, known-good queries teach the model the dataset's joins and conventions far better than a long schema dump, and keep the prompt small.
Charts without another model call
Which column is the label, measure or time axis is decided by tested, deterministic code, so charts are instant and never hallucinated.
Stack
- FastAPI
- FAISS
- OpenRouter: Gemini 2.5 Pro, text-embedding-3-small
- BigQuery
- React, Tailwind, Recharts
- Cloud Run + Vercel