BigQuery

BigQuery Source

BigQuery is Google Cloud’s fully managed, petabyte-scale, and cost-effective analytics data warehouse that lets you run analytics over vast amounts of data in near real time. With BigQuery, there’s no infrastructure to set up or manage, letting you focus on finding meaningful insights using GoogleSQL and taking advantage of flexible pricing models across on-demand and flat-rate options.

If you are new to BigQuery, you can try to load and query data with the bq tool.

BigQuery uses GoogleSQL for querying data. GoogleSQL is an ANSI-compliant structured query language (SQL) that is also implemented for other Google Cloud services. SQL queries are handled by cluster nodes in the same way as NoSQL data requests. Therefore, the same best practices apply when creating SQL queries to run against your BigQuery data, such as avoiding full table scans or complex filters.

Available Tools

• bigquery-analyze-contribution Performs contribution analysis, also called key driver analysis in BigQuery.

• bigquery-conversational-analytics Allows conversational interaction with a BigQuery source.

• bigquery-execute-sql
  Execute structured queries using parameters.

• bigquery-forecast Forecasts time series data in BigQuery.

• bigquery-get-dataset-info
  Retrieve metadata for a specific dataset.

• bigquery-get-table-info
  Retrieve metadata for a specific table.

• bigquery-list-dataset-ids
  List available dataset IDs.

• bigquery-list-table-ids
  List tables in a given dataset.

• bigquery-sql
  Run SQL queries directly against BigQuery datasets.

• bigquery-search-catalog List all entries in Dataplex Catalog (e.g. tables, views, models) that matches given user query.

Pre-built Configurations

• BigQuery using MCP Connect your IDE to BigQuery using Toolbox.

Requirements

IAM Permissions

BigQuery uses Identity and Access Management (IAM) to control user and group access to BigQuery resources like projects, datasets, and tables.

Authentication via Application Default Credentials (ADC)

By default, Toolbox will use your Application Default Credentials (ADC) to authorize and authenticate when interacting with BigQuery.

When using this method, you need to ensure the IAM identity associated with your ADC (such as a service account) has the correct permissions for the queries you intend to run. Common roles include roles/bigquery.user (which includes permissions to run jobs and read data) or roles/bigbigquery.dataViewer. Follow this guide to set up your ADC.

Authentication via User’s OAuth Access Token

If the useClientOAuth parameter is set to true, Toolbox will instead use the OAuth access token for authentication. This token is parsed from the Authorization header passed in with the tool invocation request. This method allows Toolbox to make queries to BigQuery on behalf of the client or the end-user.

When using this on-behalf-of authentication, you must ensure that the identity used has been granted the correct IAM permissions.

Example

Initialize a BigQuery source that uses ADC:

sources:
  my-bigquery-source:
    kind: "bigquery"
    project: "my-project-id"
    # location: "US" # Optional: Specifies the location for query jobs.
    # allowedDatasets: # Optional: Restricts tool access to a specific list of datasets.
    #   - "my_dataset_1"
    #   - "other_project.my_dataset_2"

Initialize a BigQuery source that uses the client’s access token:

sources:
  my-bigquery-client-auth-source:
    kind: "bigquery"
    project: "my-project-id"
    useClientOAuth: true
    # location: "US" # Optional: Specifies the location for query jobs.
    # allowedDatasets: # Optional: Restricts tool access to a specific list of datasets.
    #   - "my_dataset_1"
    #   - "other_project.my_dataset_2"

Reference