Manage context sets in Cloud SQL Studio

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms, and the Additional Terms for Generative AI Preview Products. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

When you use the context engineering agent, it can create and upload context sets automatically from your CLI. This document describes how to create, edit, and delete context sets in Cloud SQL for MySQL Studio when you want a visual interface in the Google Cloud console to manage context set files. When you create a context set in Cloud SQL Studio, Cloud SQL Studio stores it in the project's default context set group for the selected region and links it to the current database. Context set names (and their derived context set IDs) must be unique within the project's default context set group for a given region, across all databases and instances. In Cloud SQL Studio, creating a context set with a name whose derived ID already exists fails validation; to overwrite its contents while keeping its database associations, edit the existing context set instead. Uploading directly through the context engineering agent or the Dataplex API with an existing context set ID replaces its contents and, if specified, its database associations.

The Context sets list in Cloud SQL Studio shows only context sets in the default context set group across all supported regions that are linked to the current database. Context sets created for another database, or created through the API without linking the database resource in databases (or in a custom context set group), don't appear in the Cloud SQL Studio list.

To learn about context sets, see Context sets overview.

Before you begin

Complete the following prerequisites before creating or uploading a context set.

Context sets can be created in the us-central1, us-east1, europe-west4, and asia-southeast1 regions.

Enable required services

Enable the following services for your project:

• Data Analytics API with Gemini
• Gemini for Google Cloud API
• Knowledge Catalog API

Prepare a Cloud SQL instance

• Make sure that you have access to an existing Cloud SQL instance or create a new one. For more information, see Create instances for Cloud SQL.
• Ensure that you create a database in your instance where you will create the tables. For more information, see Create a database on the Cloud SQL instance.

Required roles and permissions

• Enable IAM database authentication on the instance by setting the cloudsql_iam_authentication database flag to on (cloudsql_iam_authentication=on). For more information, see Configure existing instances for IAM database authentication.
• Add an IAM user or service account at the instance level. For more information, see Add an IAM policy binding to a user, service account, or group.
• Grant the roles/cloudsql.studioUser, roles/cloudsql.instanceUser, roles/serviceusage.serviceUsageConsumer, and roles/geminidataanalytics.queryDataUser roles to the IAM user or service account at the project level. For more information, see Add IAM policy binding for a project.
• To create, upload, and manage context sets, grant the Dataplex Catalog Editor (roles/dataplex.catalogEditor) or Dataplex Catalog Admin (roles/dataplex.catalogAdmin) role to the IAM user or service account at the project level. For more information, see Context sets permissions.
• You must have a privileged user grant database privileges to the IAM user or service account.
  
  GRANT SELECT ON DATABASE_NAME.* TO 'IAM_USERNAME'@'%';
  
  Replace DATABASE_NAME with the name of your database and IAM_USERNAME with the IAM username without the @ and domain suffix (for example, [e-mail] becomes user, resulting in 'user'@'%').
  
  For more information, see Grant database privileges to an individual IAM user or service account.

Grant executesql permission to Cloud SQL instance

To grant the executesql permission to Cloud SQL instance and enable the Cloud SQL Data API, run the following command:

gcloud sql instances patch INSTANCE_ID --project=PROJECT_ID --data-api-access=ALLOW_DATA_API

Replace the following:

• PROJECT_ID: The ID of your Google Cloud project.
• INSTANCE_ID: The ID of your Cloud SQL instance.

To perform steps in this tutorial, sign in to Google Cloud, and then authenticate to the database using IAM authentication.

Create a context set

To create a context set, perform the following steps:

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

   Go to Cloud SQL

2. Select an instance from the list.

3. In the navigation menu, click Cloud SQL Studio.

4. Sign in to Cloud SQL Studio using IAM authentication.

5. In the Explorer pane, next to Context sets, click View actions.

6. Click Create context set.

7. In Context set name, provide a unique context set name. In Cloud SQL Studio, the name must be 4 to 30 characters long and cannot begin with whitespace; Studio derives the context set ID by converting the name to lowercase and replacing non-alphanumeric characters with hyphens (-), and the derived context set ID must be unique within the project's default context set group for the selected region. For example, the context set name querydata_e2e_test has the context set ID querydata-e2e-test. When you upload a context set directly using the context engineering agent or the Dataplex API, the context set ID is case-sensitive, cannot contain slashes (/), and is not restricted to 4 to 30 characters or alphanumeric characters, hyphens, and underscores.

8. Optional. In Context set description, add a description for your context set.

9. Optional. To upload a context set file, click Browse in the Upload context set file section, and select the context set file.

10. Optional. To choose a region for the context set, click Show Advanced Options and select a region in Select a location (defaults to us-east1 on each creation). If you choose a region other than us-east1, select the region before entering the context set name so Cloud SQL Studio validates name uniqueness in that region.

11. Click Create.

Note: Creating a context set from Cloud SQL Studio can take up to a few minutes while Cloud SQL Studio processes the context set. Creating or uploading a context set through the context engineering agent or the Dataplex API typically completes in a few seconds.

Build context sets

If you created an empty context set in Studio, or want to update an existing one, follow the steps in Build and optimize context sets with the context engineering agent to generate and optimize a context set file. The context engineering agent can create and upload your context set directly from the CLI, or you can edit your context set in Studio to upload the context set file manually.

Edit a context set

To edit a context set, perform the following steps:

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

   Go to Cloud SQL

2. Select an instance from the list.

3. In the navigation menu, click Cloud SQL Studio.

4. Sign in to Cloud SQL Studio using IAM authentication.

5. Click View actions next to the context set you want to edit.

6. Click Edit context set.

7. Optional. Edit Context set description.

8. Click Browse in the Upload context set file section, and select the context set file.

9. Click Save.

Delete a context set

To delete a context set, perform the following steps:

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

   Go to Cloud SQL

2. Select an instance from the list.

3. In the navigation menu, click Cloud SQL Studio.

4. Sign in to Cloud SQL Studio using IAM authentication.

5. Click View actions next to the context set you want to delete.

6. Click Delete context set.

7. In the Delete context set confirmation dialog, enter the ID of the context set.

8. Click Confirm to delete the context set.

Note: Deleting a database does not delete its context sets. To avoid orphaned context sets that still expose schema details, delete them before you delete the database.

What's next

• Learn more about context sets.
• Learn how to test QueryData in Cloud SQL Studio.
• Learn how to build and optimize context sets with the context engineering agent.
• Learn how to integrate QueryData with an application.