QueryData lets you interact with the property graph data in your Spanner database using conversational language and build data agents. QueryData generates Graph Query Language (GQL) queries from natural language questions based on the schema of your property graphs. To improve accuracy for your use cases, you can also provide context sets—a collection of query templates, query facets, and value searches that captures your domain-specific business logic and the questions that your users ask. For more information about context sets, see Context sets overview.
When to use QueryData
QueryData for Spanner Graph is ideal for applications such as the following:
- Conversational assistants over graph data: A support or analyst assistant answers "Did any money sent from account 7 come back to it within 60 days?" by having QueryData generate and run the multi-hop GQL query.
- Investigation copilots for fraud, risk, and compliance: Analysts explore ownership and transfer networks through follow-up questions, while a context set keeps terms such as high-risk transfer consistent across every answer.
- Knowledge-graph reasoning agents: Agents built with ADK or an MCP client call QueryData as a tool to ground their reasoning in the relationships stored in your graph, such as which accounts a person controls through intermediaries.
Core concepts
To reliably translate conversational questions into GQL queries, QueryData relies on the following key concepts:
QueryData and the Conversational Analytics API
The QueryData endpoint in the Conversational Analytics API is an agentic tool that enables programmatic natural language to GQL (NL2GQL) query generation for the property graphs in your Spanner database. Within a conversational application or multi-agent workflow, the QueryData endpoint handles schema interpretation and query synthesis for the property graphs that you list in the graph_ids field of each request. 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. Instead of relying solely on general LLM knowledge or the raw property graph schema, QueryData uses context sets to understand the nuances of your graph model and organization-specific terminology, such as what your business considers a high-risk transfer in a banking finance graph. The examples in this guide use the FinGraph property graph schema and sample dataset. To create the FinGraph schema and insert the sample data, see Set up and query Spanner Graph.
A context set contains three primary building blocks:
- Query templates: Curated pairs of representative natural language questions and their corresponding, pre-validated GQL queries. Templates provide canonical examples that define how specific business intents map to GQL statements (for example, how "Which accounts received transfers from Dana's account?" maps to a
GRAPH FinGraph MATCHquery that traversesOwnsandTransfersedges). - Query facets: Reusable GQL clauses (such as graph patterns, filter conditions, date ranges, amount thresholds, or business conditions such as blocked accounts). 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, written as
SELECTstatements overGRAPH_TABLE, that ground value phrases in a user's question to the exact values stored in node and edge properties. Value searches help resolve ambiguities (for example, mapping "rainy day" to the account nicknameRainy Day Fund, or "Czech Republic" to the stored valueCzech_Republic) using exact matches, 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:
- Value resolution: QueryData runs value search queries against your Spanner database to map value phrases in the prompt (such as a person's name, an account nickname, or a country) to specific node and edge property values.
- 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.
- Query synthesis: Using the schema of the property graphs listed in
graph_ids, the matched template structure, applied facets, and resolved values, QueryData synthesizes a complete GQL query. - Query execution: The generated GQL query executes against your Spanner database to return results.
Author and manage context sets
To author and manage context sets, do the following:
- Author context: Define the query templates, facets, and value searches for your property graph. For more information, see Context sets overview. You can also use the context engineering agent to automate context creation.
- Manage in Google Cloud console: Create and manage context sets in Spanner Studio to make them available for query generation.
- Integrate with your applications: Connect your applications or AI agents to QueryData using direct REST API calls, with the target property graphs listed in
graph_ids.
What's next
- Learn about context sets for Spanner Graph.
- Learn how to test QueryData for Spanner Graph.
- Follow the tutorial to integrate QueryData with an application.