BigQuery

Connect a Google Cloud project and every BigQuery table in it becomes queryable from the lake, joinable against your Iceberg tables in a single SQL statement. Connections are managed in Settings → Lake.

Setup

Open Settings → Lake and find BigQuery connections.
Give the connection a name - lowercase letters, numbers, and underscores, e.g. my_bq. This becomes the catalog prefix in SQL.
Paste your service account JSON. The GCP project ID is filled in from the key.

The service account needs roles/bigquery.dataViewer, or narrower table-level permissions. The key is stored encrypted and is never returned to the browser after saving.

Querying

Tables are reachable as connection_name.dataset.table:

-- Query a BigQuery table
SELECT *
FROM my_bq.analytics.events
WHERE _PARTITIONDATE = '2024-06-01'
LIMIT 100;

-- Join BigQuery with your Iceberg lake
SELECT e.user_id, u.plan
FROM my_bq.analytics.events e
JOIN oleander.default.users u ON e.user_id = u.id
WHERE e.event_type = 'signup';

A BigQuery table selects DuckDB. DuckDB is the only engine that attaches external connections, so the query router routes any query naming a connection table here before it considers input size - leave engine on auto. Asking for Bloom, Polars, or Spark on one of these queries returns an engine capability error rather than rerouting silently.

Cost attribution

BigQuery spend is pulled into the context graph alongside your own runs. Use bigquery_cost_get from an agent, or the cost views in observability, to see cost per table broken down by producing pipeline, query type, and full-scan detection.

From an agent

An agent connected over MCP reaches the same tables through query_run. It discovers them with catalogs_list and queries connection.dataset.table directly - no BigQuery-specific tool needed.

Getting Started

Platform

Connections

Coding with agents

CLI

External Compute

Setup

Querying

Cost attribution

From an agent

​Setup

​Querying

​Cost attribution

​From an agent

Setup

Querying

Cost attribution

From an agent