In AI-powered applications, your users expect to interact through natural language (text or voice), which requires your AI agents to query operational databases and return accurate, explainable answers.
QueryData is Google Cloud's natural language data querying product. It combines fast, deterministic execution for your core business logic with the flexibility to generalize across natural phrasing and unanticipated questions. This approach delivers near-100% accuracy, low online latency, and certified explainability.
QueryData supports AlloyDB for PostgreSQL, Cloud SQL for PostgreSQL, Cloud SQL for MySQL, Spanner (GoogleSQL dialect), Firestore with MongoDB compatibility, and Bigtable.
Why naive LLM SQL generation fails in production
Connecting a large language model (LLM) directly to a database schema (standard text-to-SQL or NL2SQL) works well in a prototype, often reaching 80% to 90% accuracy on basic questions. In production, however, asking an LLM to generate SQL from scratch over raw schemas routinely breaks down for five reasons:
- Silent semantic failures: Unlike code generation, where syntax errors fail
loudly, an LLM facing an ambiguous question rarely says "I don't know."
Instead, it writes plausible-looking SQL that executes cleanly
(
200 OK) but returns a confidently wrong answer, such as omitting required status filters or using incorrect formulas and measurements. - Unwritten business logic missing from the schema: Schemas define tables and data types, not how your business operates. If a user asks a real estate app for "homes near good schools in Del Mar," the schema doesn't define what distance counts as "near," what rating cutoff makes a school "good," or how to weigh proximity against school quality. Without those rules, an LLM has to guess.
- Opaque private data and entity ambiguity: LLMs are trained on public facts, not the strings stored inside your private tables or how users misspell them (especially with voice input). In "Westwod's sold properties in the last month," a schema-only LLM can't tell that "Westwod" is a typo for "Westwood," or whether "Westwood" in your database is a city, a municipality, or a brokerage.
- The latency versus accuracy trap: Giving an agent raw SQL tools to explore tables, sample rows, and self-correct in a multi-turn loop pushes latency to more than 30 seconds per question, which is too slow for interactive apps. Conversely, stuffing business rules into a giant system prompt causes instruction conflicts, where fixing one query silently breaks others.
- Uncontrolled data exposure: In standard applications, backend code strictly controls which queries run and which rows a user can see. When an LLM generates SQL dynamically from untrusted user input, relying on prompt instructions to protect sensitive metrics or tenant data leaves the database vulnerable to prompt manipulation.
What a production-ready solution requires
Production applications require near-100% accuracy on core workflows, consistently fast online latency, transparent explainability, generalizability to unanticipated questions, and strict security where data access matters.
Meeting these requirements involves moving beyond open-ended SQL generation to three foundational capabilities:
- Offline domain context that is straightforward to curate: Context is the foundation of high accuracy. Rather than forcing an LLM to infer business rules and table relationships at runtime, a production system needs structured domain context prepared offline. Curating and maintaining that context must be automated so engineering teams aren't stuck hand-authoring brittle rules.
- Fast, deterministic online matching that generalizes and explains its work: Low online latency requires an engine that quickly matches questions to verified context, resolves database values, explains the exact business rules applied, and surfaces ambiguities to the user rather than guessing. At the same time, the system can't be a rigid report menu. It must generalize across phrasing variations, filter combinations, and unanticipated questions by using related context and schema metadata.
- Deterministic security boundaries: Because natural language interfaces connect untrusted user input to your database, security is paramount. A production solution can't rely on LLM prompts to enforce access rules. It must enforce deterministic controls at the database and context layer (including row-level privacy for multi-tenant applications) to prevent unauthorized data exposure.
How the QueryData product brings this together
The QueryData product is more than the QueryData API endpoint. It operates as
a unified two-part system that pairs design-time context engineering with fast,
deterministic runtime execution and generalization.
Design-time context engineering
To capture your domain logic offline, you pair your database with a context set and curate it by using the Context Engineering Agent:
- Structured domain context beyond raw schemas: Alongside your database's
table and column
descriptions, a context set stores precompiled domain
knowledge for your database. While domain context can take many forms,
context sets support three specialized context types:
- Query templates: Parameterized SQL patterns matched to generalized question patterns, paired with a certified intent explanation so your users can verify how QueryData interpreted core business questions.
- Query facets: Modular SQL filter predicates and database AI
operators (such as
ai.ifand vector search) that combine dynamically with templates so a compact context set covers hundreds of filter combinations. - Value searches: Fast, deterministic database lookups that resolve misspellings, map user terms to exact columns and values, and identify when a term matches multiple concepts.
- Automated curation and hill-climbing: Instead of authoring context files by
hand, you run the Context Engineering Agent in your CLI or IDE (such as
Antigravity or Claude Code) to automate the optimization loop:
- Generate a golden benchmark: Builds and expands representative question-SQL pairs from your database schema, seed queries, and application codebase.
- Automatically hill-climb: Evaluates the
QueryDataAPI by using Evalbench, diagnoses root-cause failure patterns, authors generalized context, and automatically uploads improved context sets from your CLI until accuracy converges. - Validate on a held-out test set: Evaluates the final context set once at the end of optimization against unseen question variations to confirm that accuracy generalizes to real-world traffic without overfitting.
Runtime query execution
In production, your agent harness (such as Agent Development Kit (ADK),
LangChain, Antigravity, or Claude Code) sends user questions to the QueryData
API endpoint in the
Conversational Analytics API,
either directly or through
MCP Toolbox for Databases:
- Fast, deterministic execution with the ability to generalize:
- Deterministic template and facet execution: When a question matches your
context set across any phrasing variation or filter combination, the
QueryDataAPI resolves database values and combines the verified SQL template with matched facets. It then executes the query and returns both the answer and a certified intent explanation with low latency. - Ambiguity detection: If a term in the prompt matches multiple valid
concepts in your private data, the
QueryDataAPI returns a disambiguation prompt so your agent can ask the user for clarification rather than guessing. - Generalization to unanticipated queries: When a question falls outside
predefined templates and facets, the
QueryDataAPI dynamically synthesizes SQL by using your database schema metadata, value searches, and related templates as guidance.
- Deterministic template and facet execution: When a question matches your
context set across any phrasing variation or filter combination, the
- Database-enforced security: To protect sensitive data against prompt manipulation, the QueryData product works with database-level access controls. For multi-tenant applications on AlloyDB and Cloud SQL, parameterized secure views embed mandatory, authenticated user filters directly into the database view definition so every query respects tenant isolation.
Pricing
You are charged at AlloyDB compute pricing for queries that run when you create context sets and use QueryData with your data agents or database data sources. There is no additional charge for creating and using context sets and QueryData during the Preview period. For more information, see Data Cloud Agent pricing.
What's next
- Learn how templates, facets, and value searches work together in Context sets overview.
- Automatically generate and hill-climb a context set in Build context sets with the Context Engineering Agent.
- Connect your application to the
QueryDataAPI in Integrate QueryData with an application. - Secure access using parameterized secure views to protect multi-tenant data.