Test QueryData

This document describes how to test QueryData for Spanner Graph by calling the QueryData method of the Conversational Analytics API, and how to update the context set file. You can test QueryData's ability to generate Graph Query Language (GQL) queries from natural language questions. If a generated GQL query isn't accurate, you can update the context set file.

To learn about context sets for Spanner Graph, see Context sets overview.

Before you begin

  • Make sure that your Spanner database has the FinGraph property graph schema and sample data configured. For instructions on creating the FinGraph schema and inserting the sample data, see Set up and query Spanner Graph.
  • Make sure that a context set is already created and the context set file is uploaded to the database. For more information, see Manage context sets in Spanner Studio.
  • Install and initialize the Google Cloud CLI.

Find the existing context set ID

To test QueryData with your context set, or to connect a data application to QueryData, you need the context set ID.

  1. In the Google Cloud console, go to the Spanner page.

    Go to Spanner

  2. Select an instance from the list, and then select a database.

  3. In the navigation menu, click Spanner Studio.

  4. In the Explorer pane, click View actions next to the context set you're using.

  5. Click Edit context set.

  6. Note the context set ID in Context set ID. The context set ID format is similar to projects/my-project/locations/us-central1/contextSets/fingraph-assistant.

Test QueryData using HTTP POST

To test QueryData for Spanner Graph, send a QueryData HTTP POST request that includes the graph_ids field and your context set ID:

  1. Create a file named request.json with the following content:

    {
      "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
      "context": {
        "datasource_references": {
          "spanner_reference": {
            "database_reference": {
              "engine": "GOOGLE_SQL",
              "project_id": "PROJECT_ID",
              "instance_id": "INSTANCE_ID",
              "database_id": "DATABASE_ID",
              "graph_ids": ["FinGraph"]
            },
            "agent_context_reference": {
              "context_set_id": "CONTEXT_SET_ID"
            }
          }
        }
      },
      "generation_options": {
        "generate_query_result": true,
        "generate_natural_language_answer": true,
        "generate_explanation": true
      }
    }

    Replace the following:

    • PROJECT_ID: your Google Cloud project ID.
    • INSTANCE_ID: your Spanner instance ID.
    • DATABASE_ID: your Spanner database ID.
    • CONTEXT_SET_ID: the complete context set ID that you noted in Find the context set ID.
  2. Send the request:

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "x-goog-user-project: PROJECT_ID" \
      "https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/global:queryData" \
      -d @request.json
    
  3. In the response, review the generatedQuery field (GRAPH FinGraph MATCH ...) for accuracy, and review the queryResult field for the returned rows.

To test other questions, change the prompt value in request.json and send the request again. To see how QueryData behaves without authored context, remove the agent_context_reference object.

To check that QueryData uses your context set, ask a question that depends on it (such as "Who owns the rainy day account?") and compare the responses with and without the agent_context_reference object. Without the context set, QueryData might filter on 'rainy day' and return no rows. With the context set, it filters on 'Rainy Day Fund' and returns Dana.

Download and update the existing context set

If your test responses show that the generated GQL query for a natural language question needs improvement, download the existing context set file. You can then review and update the GQL query templates, facets, or value searches, and upload the updated context set file to the context set.

To download and update a context set, perform the following steps:

  1. In the Explorer pane, click View actions next to your context set.
  2. Click Download context file.
  3. Follow the steps in Build context sets using the context engineering agent to update the context set with additional natural language-to-GQL query pairs.
  4. In the Explorer pane, click View actions next to the context set you're using.
  5. Click Edit context set.
  6. Click Browse in the Upload context set file section, and select the updated context set file.
  7. Click Save to update the context set.
  8. Test QueryData again to verify the generated GQL query.

After you are satisfied with the accuracy of your responses, you can use the QueryData endpoint to connect your application to the context set.

Connect QueryData to your application

Set the context set ID and target graph_ids in the QueryData method call to provide authored context and enable GQL query generation for Spanner Graph. For more information about using QueryData with database data sources, see Define data agent context for database data sources. For an example that connects an agent application to QueryData through a custom HTTP tool that calls the QueryData REST API, see Integrate QueryData with an application.

Example QueryData request with authored context

The following example shows a QueryData request using the spanner_reference database data source for the FinGraph property graph. You must provide graph_ids inside spanner_reference.database_reference so that QueryData targets your property graph and generates GQL queries. The agent_context_reference.context_set_id field links to the pre-authored context stored in the database:

{
  "parent": "projects/my-project/locations/global",
  "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
  "context": {
    "datasource_references": {
      "spanner_reference": {
        "database_reference": {
          "engine": "GOOGLE_SQL",
          "project_id": "my-project",
          "instance_id": "my-instance",
          "database_id": "fin-graph-db",
          "graph_ids": [
            "FinGraph"
          ]
        },
        "agent_context_reference": {
          "context_set_id": "projects/my-project/locations/us-central1/contextSets/fingraph-assistant"
        }
      }
    }
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

The request body contains the following fields:

  • parent: Optional. The project and location of the request, in the format projects/PROJECT_ID/locations/LOCATION. Use the same project and location as in the request URL.
  • prompt: The natural language question from the end user.
  • context: Contains information about the data sources.
    • datasource_references: Specifies the data source. This field is an object, not a list.
      • spanner_reference: Required when querying a Spanner database.
        • database_reference: Specifies information related to your Spanner database and property graphs.
          • engine: The dialect of the database. Set to GOOGLE_SQL for Spanner Graph databases.
          • project_id: The project ID of the Spanner instance.
          • instance_id: The instance ID of the Spanner instance.
          • database_id: The ID of the Spanner database.
          • graph_ids: Required for Spanner Graph. A list of property graph names in the database to query (for example, ["FinGraph"]). Providing graph_ids instructs QueryData to generate GQL queries against the specified property graphs. If you omit graph_ids, QueryData only generates relational SQL queries against the underlying tables instead.
        • agent_context_reference: Links to authored context in the database.
          • context_set_id: The complete context set ID of the context stored in the database, such as projects/my-project/locations/us-central1/contextSets/fingraph-assistant.
  • generation_options: Configures the type of output to generate.
    • generate_query_result: Set to true to execute the generated GQL query and return the query results.
    • generate_natural_language_answer: Optional. If set to true, generates a natural language answer summarizing the query results.
    • generate_explanation: Optional. If set to true, generates an explanation of the GQL query.
    • generate_disambiguation_question: Optional. If set to true, generates disambiguation questions if the natural language prompt is ambiguous.

Example QueryData response

The following example shows a successful response from a QueryData call against the FinGraph property graph. The REST API returns field names in camelCase, such as generatedQuery and queryResult. Because GQL generation is nondeterministic, the generated query, column names, and answer text can differ between calls.

{
  "generatedQuery": "GRAPH `FinGraph` MATCH (p:`Person` {`name`: 'Dana'})-[:`Owns`]->(src:`Account`)-[t:`Transfers`]->(dst:`Account`) MATCH (p_recipient:`Person`)-[:`Owns`]->(dst) RETURN DISTINCT p_recipient.`name` AS recipient_name, dst.`id` AS recipient_account_id, t.`amount` AS transfer_amount",
  "intentExplanation": "To find everyone Dana transferred money to, we identify the person named Dana and locate the accounts they own. We trace the transfer relationships from Dana's accounts to any destination accounts, identifying the specific amounts sent and the IDs of those receiving accounts. Finally, we find the individuals who own those receiving accounts to present their names along with the account details and transfer amounts.",
  "queryResult": {
    "columns": [
      {
        "name": "recipient_name",
        "type": "STRING"
      },
      {
        "name": "recipient_account_id",
        "type": "INT64"
      },
      {
        "name": "transfer_amount",
        "type": "FLOAT64"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "Alex"
          },
          {
            "value": "7"
          },
          {
            "value": "500"
          }
        ]
      },
      {
        "values": [
          {
            "value": "Lee"
          },
          {
            "value": "16"
          },
          {
            "value": "200"
          }
        ]
      }
    ],
    "totalRowCount": "2"
  },
  "naturalLanguageAnswer": "Based on the transaction records, Dana transferred money to the following recipients:\n\n*   **Alex**: Account ID **7**, with a transfer amount of **500**\n*   **Lee**: Account ID **16**, with a transfer amount of **200**"
}

What's next