Manage context sets in Spanner Studio

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 Spanner Studio when you want a visual interface in the Google Cloud console to manage context set files. When you create a context set in Spanner Studio, Spanner 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 Spanner 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 Spanner 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 Spanner 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:

Prepare a Spanner instance

Required roles and permissions

  • Add an IAM user or service account to the instance. For more information, see Apply IAM roles.
  • Grant the roles/spanner.databaseReader, roles/serviceusage.serviceUsageConsumer, and roles/geminidataanalytics.queryDataUser roles to the IAM user 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 at the project level. For more information, see Context sets permissions.
  • Grant roles and permissions to the IAM user at the project-level for the required databases.

Create a context set

To create a context set, perform the following steps:

  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, next to Context sets, click View actions.

  5. Click Create context set.

  6. In Context set name, provide a unique context set name. In Spanner 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.

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

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

  9. 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 Spanner Studio validates name uniqueness in that region.

  10. Click Create.

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 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. Click View actions next to the context set you want to edit.

  5. Click Edit context set.

  6. Optional. Edit Context set description.

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

  8. Click Save.

Delete a context set

To delete a context set, perform the following steps:

  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. Click View actions next to the context set you want to delete.

  5. Click Delete context set.

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

  7. Click Confirm to delete the context set.

What's next