execute_sql
Run a SQL query in the project and return the result. Prefer the execute_sql_readonly
tool if possible.
This tool can execute any query that bigquery supports including:
SQL Queries (
SELECT,INSERT,UPDATE,DELETE,CREATE, etc.)AI/ML functions like
AI.FORECAST,ML.EVALUATE,ML.PREDICTAny other query that bigquery supports.
Example Queries:
-- Insert data into a table.
INSERT INTO `my_project.my_dataset`.my_table (name, age)
VALUES ('Alice', 30);
-- Create a table.
CREATE TABLE `my_project.my_dataset`.my_table (
name STRING,
age INT64);
-- DELETE data from a table.
DELETE FROM `my_project.my_dataset`.my_table WHERE name = 'Alice';
-- Create Dataset
CREATE SCHEMA `my_project.my_dataset` OPTIONS (location = 'US');
-- Drop table
DROP TABLE `my_project.my_dataset`.my_table;
-- Drop dataset
DROP SCHEMA `my_project.my_dataset`;
-- Create Model
CREATE OR REPLACE MODEL `my_project.my_dataset.my_model`
OPTIONS (
model_type = 'LINEAR_REG'
LS_INIT_LEARN_RATE=0.15,
L1_REG=1,
MAX_ITERATIONS=5,
DATA_SPLIT_METHOD='SEQ',
DATA_SPLIT_EVAL_FRACTION=0.3,
DATA_SPLIT_COL='timestamp') AS
SELECT col1, col2, timestamp, label FROM `my_project.my_dataset.my_table`;Queries executed using the execute_sql tool will always have the default job label
goog-mcp-server: true automatically set in addition to any custom labels provided in the
request. Queries are charged to the project specified in the project_id field.
Query Execution Behavior:
If the query completes within the synchronous timeout (default 20 seconds or custom
timeout_ms), the tool returnsjob_complete: trueand the initial result rows directly. For fast queries,job_idmay be omitted as no persistent background job is created; no further action or polling is needed.If the query takes longer than
timeout_ms, the tool returnsjob_complete: falseand ajob_id. In this case, use theget_query_resultstool withjob_idto poll untiljob_complete: true, or usecancel_jobto abort the running query.You can optionally specify
timeout_msto configure the maximum synchronous wait time in milliseconds (defaults to 20,000 ms), andjob_timeout_msto enforce a hard server-side timeout after which BigQuery automatically terminates the job.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Required. The query to execute in the form of a GoogleSQL query. | |
| dryRun | No | Optional. If set to true, BigQuery doesn't run the job. Instead, if the query is valid, BigQuery returns statistics about the job such as how many bytes would be processed. If the query is invalid, an error returns. The default value is false. | |
| labels | No | Optional. The labels associated with this query. Labels can be used to organize and group query jobs. Label keys and values can be no longer than 63 characters, can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed. Label keys must start with a letter and each label in the map must have a different key. | |
| projectId | Yes | Required. Project that will be used for query execution and billing. | |
| timeoutMs | No | Optional. Optional: Specifies the maximum amount of time, in milliseconds, that the client is willing to wait for the query to complete. By default, this limit is 20 seconds (20,000 milliseconds). | |
| jobTimeoutMs | No | Optional. Optional: Job timeout in milliseconds. If this time limit is exceeded, BigQuery will attempt to stop the query job. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rows | No | An object with as many results as can be contained within the maximum permitted reply size. To get any additional rows, you can call GetQueryResults and specify the jobReference returned above. | |
| jobId | No | Output only. The ID of the BigQuery job created for this query, if any. Present when a query job is created (e.g. for long-running operations, DML, scripts). Use this ID with `get_query_results`, `cancel_job`, or `get_job`. | |
| errors | No | Output only. The first errors or warnings encountered during the running of the job. The final message includes the number of errors that caused the process to stop. Errors here do not necessarily mean that the job has completed or was unsuccessful. For more information about error messages, see [Error messages](https://cloud.google.com/bigquery/docs/error-messages). | |
| schema | No | The schema of the results. Present only when the query completes successfully. | |
| queryId | No | Output only. The ID of the query. | |
| jobComplete | No | Whether the query has completed or not. If rows or totalRows are present, this will always be true. If this is false, totalRows will not be available. | |
| totalSlotMs | No | Output only. Number of slot ms the user is actually billed for. | |
| totalBytesBilled | No | Output only. The total number of bytes billed for the query. Only applies if the project is configured to use on-demand pricing. | |
| numDmlAffectedRows | No | Output only. The number of rows affected by a DML statement. | |
| totalBytesProcessed | No | Output only. The total number of bytes processed for this query. |