bigquery-execute-sql

About

A bigquery-execute-sql tool executes a SQL statement against BigQuery.

bigquery-execute-sql accepts the following parameters:

• sql (required): The GoogleSQL statement to execute.
• dry_run (optional): If set to true, the query is validated but not run, returning information about the execution instead. Defaults to false.

The behavior of this tool is influenced by the combination of the readOnly and writeMode settings on its bigquery source:

Note: Conflicting configurations, such as readOnly: true combined with writeMode: allowed, are rejected during server startup.

The tool’s behavior is influenced by the allowedDatasets restriction on the bigquery source. Similar to writeMode, this setting provides an additional layer of security by controlling which datasets can be accessed:

• Without allowedDatasets restriction: The tool can execute any valid GoogleSQL query.

• With allowedDatasets restriction: Before execution, the tool performs a dry run to analyze the query. It will reject the query if it explicitly references any table outside allowedDatasets.

  Authorized views are supported. If the dry run reports that the query reads a table outside allowedDatasets, but that table is not named anywhere in the SQL text, the access is treated as an authorized view and permitted. This lets you expose a curated view in an allowed dataset that reads from restricted source data. Note that all table names in the query must be fully qualified (dataset.table or project.dataset.table) to be eligible for authorized view exemptions, as unqualified table names resolved via default datasets cannot be statically verified against allowedDatasets.

  To keep the analysis sound, the following operations remain disallowed:

  • Dataset-level operations (e.g., CREATE SCHEMA, ALTER SCHEMA).
  • Unanalyzable operations where the accessed tables cannot be determined statically (e.g., EXECUTE IMMEDIATE, CREATE PROCEDURE, CREATE FUNCTION, CREATE TABLE FUNCTION, CALL).
  • Session variable assignments (e.g., SET @@dataset_id = ...).
  • Federated queries via EXTERNAL_QUERY.
  • Region-level INFORMATION_SCHEMA views (only dataset-scoped views such as <dataset>.INFORMATION_SCHEMA.TABLES are allowed).

Note: This tool is intended for developer assistant workflows with human-in-the-loop and shouldn’t be used for production agents.

Compatible Sources

Example

kind: tool
name: execute_sql_tool
type: bigquery-execute-sql
source: my-bigquery-source
description: Use this tool to execute sql statement.

Reference