Define data agent context for database data sources

Authored context is guidance that data agent owners can provide to shape the behavior of a data agent and to refine the API's responses. Effective authored context provides your Conversational Analytics API data agents with useful context for answering questions about your data sources.

This page describes how to provide authored context for database data sources using the QueryData method. For database data sources like AlloyDB, GoogleSQL for Spanner, Cloud SQL, and Cloud SQL for PostgreSQL, you provide authored context by first defining and storing the context in the database and then referencing it in your QueryData call.

Providing high accuracy context enables the API to generate more accurate and relevant SQL queries and answers.

Before you begin

A data agent with the agent context uploaded to it for a database exists. For more information, see Data agents for AlloyDB, Data agents for GoogleSQL for Spanner, and Data agents for Cloud SQL, and Data agents for Cloud SQL for PostgreSQL.
Enable the Cloud SQL Data API for your instance as follows:
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
Replace INSTANCE_ID with the ID of your Cloud SQL or Cloud SQL for PostgreSQL instance.

You must also grant database privileges to an IAM user or service account. For more information, see Grant database privileges to an individual IAM user or service account in Cloud SQL and Grant database privileges to an individual IAM user or service account in Cloud SQL for PostgreSQL.

Providing context with `QueryData`

When calling the QueryData method, you provide the data source and context information within the QueryDataRequest.context.datasourceReferences field. For database sources, you must use one of the following:

alloydb for AlloyDB for PostgreSQL,
spanner_reference for GoogleSQL for Spanner
cloud_sql_reference for Cloud SQL and Cloud SQL for PostgreSQL

Within these references, you specify the database and tables using the databaseReference field. To include authored context, you must also provide an agentContextReference that points to a context_set_id.

Example `QueryData` request with authored context

The following example shows a QueryData request using alloydb. The agent_context_reference.context_set_id field is used to link to pre-authored context stored in the database.

AlloyDB

{
  "parent": "projects/cloud-db-nl2sql/locations/us-central1",
  "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "alloydb": {
          "database_reference": {
            "project_id": "cloud-db-nl2sql",
            "region": "us-central1",
            "cluster_id": "sqlgen-magic",
            "instance_id": "sqlgen-magic-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

GoogleSQL for Spanner

{
  "parent": "projects/cloud-db-nl2sql/locations/us-central1",
  "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "spanner_reference" {
          "database_reference" {
            "engine": "GOOGLE_SQL"
            "project_id": "cloud-db-nl2sql"
            "region": "us-central1"
            "instance_id": "evalbench"
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

Cloud SQL & Cloud SQL for PostgreSQL

{
  "parent": "projects/cloud-db-nl2sql/locations/us-central1",
  "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "cloud_sql_reference": {
          "database_reference": {
            "engine": "MYSQL"
            "project_id": "cloud-db-nl2sql",
            "region": "us-central1",
            "instance_id": "sqlgen-magic-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "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:

prompt: The natural language question from the end user.
context: Contains information about the data sources.
- datasource_references: Specifies the data source type.
  - alloydb: Required when querying the database. This field changes based on the database you are querying.
    - database_reference: Specifies information related to your database instance.
      - engine:
      - project_id: The project ID of the database instance.
      - region: The region of the database instance.
      - cluster_id: The cluster ID of the database instance.
      - instance_id: The instance ID of the database.
      - database_id: The ID of the database.
    - agent_context_reference: Links to authored context in the database.
      - context_set_id: The agent context ID stored in the database. For more information about how to find the context set ID, see Find the agent context ID in AlloyDB, Find the agent context ID in GoogleSQL for Spanner, Find the agent context ID in Cloud SQL, and Find the agent context ID in Cloud SQL for PostgreSQL.
generationOptions: Configures the type of output to generate.
- generate_query_result: Set to true to generate and return the query results.
- generate_natural_language_answer: Optional. If set to true, generates a natural language answer.
- generate_explanation: Optional. If set to true, generates an explanation of the SQL query.
- generate_disambiguation_question: Optional. If set to true, generates disambiguation questions if the query is ambiguous.

Example `QueryData` Response

Here is an example of a successful response from a QueryData call:

{
  "generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n  COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n  ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n  \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
  "query_result": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

Define data agent context for database data sources Stay organized with collections Save and categorize content based on your preferences.