google__adk-docs/docs/integrations/bigquery.md

catalog_title, catalog_description, catalog_icon, catalog_tags

catalog_title	catalog_description	catalog_icon	catalog_tags
BigQuery Tools	Connect with BigQuery to retrieve data and perform analysis	/integrations/assets/bigquery.png	data google

BigQuery tool for ADK

Supported in ADKPython v1.1.0

These are a set of tools aimed to provide integration with BigQuery, namely:

• list_dataset_ids: Fetches BigQuery dataset ids present in a GCP project.
• get_dataset_info: Fetches metadata about a BigQuery dataset.
• list_table_ids: Fetches table ids present in a BigQuery dataset.
• get_table_info: Fetches metadata about a BigQuery table.
• get_job_info: Fetches metadata information about a BigQuery job (slot usage, configuration, statistics, status, etc.).
• execute_sql: Runs a SQL query in BigQuery and fetch the result.
• forecast: Runs a BigQuery AI time series forecast using the AI.FORECAST function.
• analyze_contribution: Performs BigQuery ML contribution analysis to understand what drives changes in a metric.
• detect_anomalies: Trains an ARIMA_PLUS model and detects anomalies in time series data.
• ask_data_insights: Answers questions about data in BigQuery tables using natural language.
• search_catalog: Finds BigQuery datasets and tables using natural language semantic search via Dataplex.

They are packaged in the toolset BigQueryToolset.

Authentication

The BigQueryToolset supports several authentication mechanisms through BigQueryCredentialsConfig.

Application Default Credentials

You should use this approach for local development and running on Google Cloud services, such as Cloud Run and GKE.

import google.auth
from google.adk.tools.bigquery import BigQueryToolset, BigQueryCredentialsConfig

# Load Application Default Credentials
credentials, project_id = google.auth.default()

# Configure the toolset
credentials_config = BigQueryCredentialsConfig(credentials=credentials)
bigquery_toolset = BigQueryToolset(credentials_config=credentials_config)

Service Account

You can explicitly provide a service account file or info.

from google.oauth2 import service_account
from google.adk.tools.bigquery import BigQueryToolset, BigQueryCredentialsConfig

# Load Service Account credentials
credentials = service_account.Credentials.from_service_account_file('path/to/key.json')

# Configure the toolset
credentials_config = BigQueryCredentialsConfig(credentials=credentials)
bigquery_toolset = BigQueryToolset(credentials_config=credentials_config)

External Access Token

For applications that need to act on behalf of an end-user, you can pass user credentials directly instantiated from an access token, such as from an OAuth2 flow or an external IDP.

from google.oauth2.credentials import Credentials
from google.adk.tools.bigquery import BigQueryToolset, BigQueryCredentialsConfig

# Assume 'user_token' is obtained via an external OAuth flow
credentials = Credentials(token=user_token)

# Configure the toolset
credentials_config = BigQueryCredentialsConfig(credentials=credentials)
bigquery_toolset = BigQueryToolset(credentials_config=credentials_config)

External Auth Providers

If you are integrating with an external authentication provider where the token is managed by the platform, such as Gemini Enterprise, use external_access_token_key.

from google.adk.tools.bigquery import BigQueryToolset, BigQueryCredentialsConfig

# The key used to look up the access token in the session state
credentials_config = BigQueryCredentialsConfig(
    external_access_token_key="YOUR_AUTH_ID"
)
bigquery_toolset = BigQueryToolset(credentials_config=credentials_config)

Interactive Auth (ADK Web)

When using the adk web interface for interactive sessions, you can provide OAuth 2.0 client credentials to trigger a login flow. This mechanism works for both local development and when your ADK agent is deployed to environments like Cloud Run.

from google.adk.tools.bigquery import BigQueryToolset, BigQueryCredentialsConfig

# Provide OAuth 2.0 Client ID and Secret
credentials_config = BigQueryCredentialsConfig(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)
bigquery_toolset = BigQueryToolset(credentials_config=credentials_config)

Sample Code

The following sample code demonstrates how to use the BigQueryToolset in an ADK agent using Application Default Credentials (ADC).

--8<-- "examples/python/snippets/tools/built-in-tools/bigquery.py"

Sample Agent

For a complete, ready-to-run sample of a BigQuery-powered agent with detailed authentication examples, see the BigQuery Sample Agent on GitHub.

Note: If you want to access a BigQuery data agent as a tool, see Data Agents tools for ADK.