Skip to main content

BigQuery

Tool types for querying Google BigQuery: browse datasets and tables, inspect schemas, and run SQL with built-in cost controls.

Every type on this page requires a BigQuery connector (the same Google connector used for Google Analytics); connectorId is the ID of that connector. Each tool also names an explicit GCP projectId, since one connected account can span many projects. The three browse tools exist so an agent can discover schema before writing SQL — a RUN_QUERY-only agent tends to guess table names.

List datasets TOOLBIGQUERY_LIST_DATASETS​

Lists the datasets in a GCP project, up to maxResults (default 100). This is the top of the discovery chain: dataset → tables → schema → query.

Example​

Tool config
{
  "toolType": "BIGQUERY_LIST_DATASETS",
  "connectorId": "V1StGXR8Z5",
  "projectId": "acme-analytics-prod",
  "maxResults": 100
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the Google Analytics/BigQuery connection References a connector by ID.
  • Name
    projectId
    Type
    string
    Description
    The GCP project ID containing the datasets
  • Name
    maxResults
    Type
    integer
    Description
    Maximum number of datasets to return (default 100, max 1000)

List tables TOOLBIGQUERY_LIST_TABLES​

Lists the tables (and views) inside a dataset, up to maxResults (default 100). GA4 BigQuery exports show up here as date-sharded events_YYYYMMDD tables — useful context when an agent is deciding what to query.

Example​

Tool config
{
  "toolType": "BIGQUERY_LIST_TABLES",
  "connectorId": "V1StGXR8Z5",
  "projectId": "acme-analytics-prod",
  "datasetId": "analytics_123456789",
  "maxResults": 100
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the Google Analytics/BigQuery connection References a connector by ID.
  • Name
    projectId
    Type
    string
    Description
    The GCP project ID
  • Name
    datasetId
    Type
    string
    Description
    The dataset ID to list tables from
  • Name
    maxResults
    Type
    integer
    Description
    Maximum number of tables to return (default 100, max 1000)

Get table schema TOOLBIGQUERY_GET_TABLE_SCHEMA​

Returns a table's schema — column names, types, modes, and nested record structure. Have the agent call this before writing SQL against an unfamiliar table; it is the difference between correct queries and column-name guesswork.

Example​

Tool config
{
  "toolType": "BIGQUERY_GET_TABLE_SCHEMA",
  "connectorId": "V1StGXR8Z5",
  "projectId": "acme-analytics-prod",
  "datasetId": "analytics_123456789",
  "tableId": "@@{tableId}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the Google Analytics/BigQuery connection References a connector by ID.
  • Name
    projectId
    Type
    string
    Description
    The GCP project ID
  • Name
    datasetId
    Type
    string
    Description
    The dataset ID containing the table
  • Name
    tableId
    Type
    string
    Description
    The table ID to get schema for

Run query TOOLBIGQUERY_RUN_QUERY​

Executes SQL (Standard SQL unless useLegacySql is true) and returns up to maxRows rows (default 1000, max 10000). Two guardrails matter for cost: maxBytesProcessed makes the query fail fast if it would scan more data than you allow, and dryRun: true returns the estimated bytes scanned without executing at all — a cheap way to validate a query before paying for it. timeoutMs caps execution at up to 5 minutes.

Example​

Tool config
{
  "toolType": "BIGQUERY_RUN_QUERY",
  "connectorId": "V1StGXR8Z5",
  "projectId": "acme-analytics-prod",
  "query": "@@{sqlQuery}",
  "maxRows": 1000,
  "timeoutMs": 30000,
  "maxBytesProcessed": 1000000000,
  "dryRun": false,
  "useLegacySql": false
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the Google Analytics/BigQuery connection References a connector by ID.
  • Name
    projectId
    Type
    string
    Description
    The GCP project ID to run the query in
  • Name
    query
    Type
    string
    Description
    The SQL query to execute (Standard SQL by default)
  • Name
    maxRows
    Type
    integer
    Description
    Maximum number of rows to return (default 1000, max 10000)
  • Name
    timeoutMs
    Type
    integer
    Description
    Query timeout in milliseconds (default 30000, max 300000 = 5 min)
  • Name
    maxBytesProcessed
    Type
    integer
    Description
    Maximum bytes the query can process (fails if exceeded, good for cost control)
  • Name
    dryRun
    Type
    boolean
    Description
    If true, only estimates cost without executing (returns bytesProcessed estimate)
  • Name
    useLegacySql
    Type
    boolean
    Description
    If true, uses legacy SQL. Default false = Standard SQL