> [!WARNING]
>
> **Preview**
>
>
> This feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the
> [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1), and the
> [Additional Terms for Generative AI
> Preview Products](https://cloud.google.com/trustedtester/aitos).
>
> Pre-GA features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

> [!WARNING]
> **PostgreSQL interface note:** The examples in this topic are intended for GoogleSQL-dialect databases. This feature doesn't support PostgreSQL interface.

QueryData lets you interact with your data using conversational language and
*data agents* that you build to help you query your data. Data agents are
AI-powered assistants and applications that can understand user intent, query
your operational data, and return accurate, grounded answers. QueryData
generates queries for your database using context sets, which are collections of
curated query templates, business logic, and schema information. This context allows
QueryData to translate natural language questions into accurate queries for your
target use cases.

## When to use QueryData

QueryData is ideal for applications such as:

- **Customer service automation**: Handle high-volume inquiries like "Where is my order?" or "What is my current balance?".
- **E-commerce shopping assistants**: Help users navigate large product catalogs with natural language queries like "Show me running shoes under $100."
- **Field operations tools**: Allow mobile employees to query inventory levels, part availability, or service ticket details in real-time.

## Core concepts

To reliably translate conversational questions into database queries, QueryData
relies on the following key concepts:

### QueryData and the Conversational Analytics API

The `QueryData` endpoint in the
[Conversational Analytics API](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/overview.md.txt#key_api_operations)
is an agentic tool that enables programmatic natural language to SQL
query generation for your databases. Within a conversational application or
multi-agent workflow, the `QueryData` endpoint handles schema interpretation and
query synthesis. Your agent harness (such as Antigravity,
Agent Development Kit (ADK), or LangChain) manages the conversation history, user
state, and tool orchestration to contextualize the user's input before sending a
natural language request to the `QueryData` endpoint.

### Context sets

A *context set* is a collection of database-specific knowledge, curated query
patterns, and business rules associated with your database instance. Instead of
relying solely on general LLM knowledge or raw table schemas, QueryData uses
context sets to understand the nuances of your data model and
organization-specific terminology.

A context set contains three primary building blocks:

- **Query templates**: Curated pairs of representative natural language questions and their corresponding, pre-validated SQL queries. Templates provide canonical examples that define how specific business intents map to SQL statements.
- **Query facets**: Modular SQL predicates and filter conditions (such as date ranges, threshold calculations, or business flags). Facets allow QueryData to dynamically combine multiple filtering criteria into a query without needing separate templates for every combination.
- **Value searches** : Semantic and string-matching queries that ground informal phrases to exact values stored in database columns. Value searches help resolve ambiguities (for example, mapping "Bay Area" to `San Francisco`, or "Heathrow" to `London Heathrow Airport`) using exact matches, trigram string similarity, or semantic vector embeddings.

## How QueryData works

When your agent or application sends a natural language request (such as a
user's question that the agent has contextualized with conversation history or
user state), QueryData performs the following steps:

1. **Value resolution**: QueryData runs value search queries against the database to map entities in the prompt (such as names, cities, or categories) to specific database column values.
2. **Intent matching and disambiguation**: QueryData matches the contextualized request against the curated query templates and facets that you defined in the context set. If the request is underspecified or ambiguous, then QueryData can return a disambiguation question so that your agent or application can ask the user for clarification.
3. **Query synthesis**: Using the matched template structure, applied facets, and resolved values, QueryData synthesizes a complete SQL query for your database engine.
4. **Query execution**: The generated query executes against the database to return results.

## Author and manage context sets

To author and manage context sets, do the following:

1. **Author context** : Define the query templates, facets, and value searches for your database. For more information, see [Context sets overview](https://docs.cloud.google.com/gemini/data-agents/querydata/spanner/context-sets-overview.md.txt). You can also use the [context engineering agent](https://docs.cloud.google.com/gemini/data-agents/querydata/spanner/build-context-sets.md.txt) to automate context creation.
2. **Manage in Google Cloud console**: Create and manage context sets in Spanner Studio to make them available for query generation.
3. **Integrate with your applications** : Connect your applications or AI agents to QueryData using [MCP Toolbox](https://github.com/googleapis/mcp-toolbox) or direct API calls.

## Pricing

You are charged at
[Spanner compute pricing](https://cloud.google.com/spanner/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](https://cloud.google.com/products#product-launch-stages) period. For
more information, see
[Data Cloud Agent pricing](https://cloud.google.com/products/data-agents/pricing).

## What's next

- Learn how to [test QueryData in Spanner Studio](https://docs.cloud.google.com/gemini/data-agents/querydata/spanner/inspect-data-agent.md.txt).
- Learn how to [create and manage context sets](https://docs.cloud.google.com/gemini/data-agents/querydata/spanner/manage-data-agents.md.txt).
- Learn how to [build context sets with the context engineering agent](https://docs.cloud.google.com/gemini/data-agents/querydata/spanner/build-context-sets.md.txt).