Data residency

This page explains how the Conversational Analytics API supports data residency. Data residency refers to the physical location of your data and the commitments to store and process your data within a specific geographic area to meet regulatory or policy requirements. To control the location of your data, you specify a regional service endpoint for your API requests.

In this document, location refers to a Google Cloud region or multi-region where data resides, and your data has the same meaning as "Customer Data" in the Data Location section of the Service Specific Terms.

Data residency commitments for the Conversational Analytics API vary based on whether your agent connects to BigQuery or to Looker.

Data residency scope

The Conversational Analytics API helps you meet data residency requirements by providing controls over the location of customer data in different states:

  • Data is at rest when it is stored in persistent storage, rather than actively being processed or transmitted.
  • Data is in use when it is in memory, such as when machine learning (ML) models process data to generate a response or when the service executes a query. For the Conversational Analytics API, data residency commitments for data in use are specific to jurisdictional ML processing and don't provide comprehensive residency for all states of data in use.
  • Data is in transit when it is entering or exiting the Google network perimeter.

Data residency commitments for the Conversational Analytics API apply to DataAgent resources (including customer configurations, context, system instructions, and example queries) and Conversation resources (including message content and state history). These commitments don't apply to service data, such as resource identifiers and labels, or to data in transit.

Supported data locations

The Conversational Analytics API supports global, regional, and multi-regional locations. When you use a regional or multi-regional endpoint, you control the location where your data is stored at rest.

In the following tables, jurisdictional machine learning (ML) processing (identified as In use (jurisdictional)) refers to ML processing commitments for your data. As defined in the Service Specific Terms, Google performs machine learning processing of your data only in your selected region or multi-region.

The following sections provide details about data residency support for agents and conversations that use BigQuery and Looker data sources.

BigQuery data

For data agents that connect to BigQuery, regional and multi-regional endpoints support data residency for data at rest and jurisdictional ML processing for data in use. Regardless of the endpoint location that you specify, the agent can connect to BigQuery datasets in any location or combination of locations:

Location Location description Endpoint type Endpoint URL Dataset location Data residency support
global Global Global geminidataanalytics.googleapis.com Any region or multi-region Not supported
eu European Union Multi-regional geminidataanalytics.eu.rep.googleapis.com Any region or multi-region At rest, In use (jurisdictional)
us United States Multi-regional geminidataanalytics.us.rep.googleapis.com Any region or multi-region At rest, In use (jurisdictional)
us-east4 Northern Virginia Regional geminidataanalytics-us-east4.googleapis.com Any region or multi-region At rest, In use (jurisdictional)

Looker data

For data agents that connect to Looker, regional and multi-regional endpoints support data residency for data at rest. Regardless of the endpoint location that you specify, the agent can connect to data sources in any location or combination of locations:

Location Location description Endpoint type Endpoint URL Dataset location Data residency support
global Global Global geminidataanalytics.googleapis.com Any region or multi-region Not supported
eu European Union Multi-regional geminidataanalytics.eu.rep.googleapis.com Any region or multi-region At rest, In use (jurisdictional)
us United States Multi-regional geminidataanalytics.us.rep.googleapis.com Any region or multi-region At rest
us-east4 Northern Virginia Regional geminidataanalytics-us-east4.googleapis.com Any region or multi-region At rest

For the full list of available regional and multi-regional endpoints, see Conversational Analytics API locations.

Enforce data residency with regional endpoints

To enforce data residency for your DataAgent and Conversation resources, use a regional endpoint when you create and access them. The service endpoints for the Conversational Analytics API use the following formats, depending on the location type:

  • Global: geminidataanalytics.googleapis.com
  • Multi-regional: geminidataanalytics.LOCATION.rep.googleapis.com
  • Regional: geminidataanalytics-LOCATION.googleapis.com

Replace the LOCATION placeholder with a supported single region or multi-region, such as eu, us, or us-east4.

The following examples show how to configure a regional endpoint for HTTP and Python SDK requests:

HTTP

To use a regional endpoint with HTTP, construct the request URL with the regional base URL. First, configure the base_url to use your chosen regional endpoint, as shown in the following example from Configure initial settings and authentication:

project_id = "PROJECT_ID"
location = "LOCATION"

# Set the base URL based on location.
if not location or location == "global":
  base_url = "https://geminidataanalytics.googleapis.com"
elif "-" in location:
  # Regional endpoints
  base_url = f"https://geminidataanalytics-{location}.googleapis.com"
else:
  # Multi-regional endpoints
  base_url = f"https://geminidataanalytics.{location}.rep.googleapis.com"

Then, use the base_url variable when constructing URLs for API requests, such as in this example from Ask questions with stateful and stateless chat:

# Example API request URL construction using base_url:
chat_url = f"{base_url}/v1beta/projects/{project_id}/locations/{location}:chat"

Python SDK

To use a regional endpoint with the Python SDK, pass client_options with the regional api_endpoint parameter when initializing API clients, as shown in the following example from Configure settings and initialize clients.

from google.cloud import geminidataanalytics
from google.api_core import client_options

project_id = "PROJECT_ID"
location = "LOCATION"

# Set client options based on location.
if not location or location == "global":
  endpoint = "geminidataanalytics.googleapis.com"
elif "-" in location:
  # Regional endpoints
  endpoint = f"geminidataanalytics-{location}.googleapis.com"
else:
  # Multi-regional endpoints
  endpoint = f"geminidataanalytics.{location}.rep.googleapis.com"
opts = client_options.ClientOptions(api_endpoint=endpoint)

# Use client options when initializing API clients.
data_agent_client = geminidataanalytics.DataAgentServiceClient(client_options=opts)
data_chat_client = geminidataanalytics.DataChatServiceClient(client_options=opts)

# Use clients to make API requests. For example:
# response = data_chat_client.chat(request=request)

Replace the sample values as follows:

  • PROJECT_ID: Your Google Cloud project ID.
  • LOCATION: The region or multi-region where you want to create your resources. To use one of the regional endpoints, specify eu, us, or us-east4.

Limitations

When you use regional endpoints, consider the following points:

What's next