> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleander.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# BigQuery

> Attach a Google Cloud project and query BigQuery tables alongside your Iceberg lake.

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](https://oleander.dev/app/settings/lake).

## Setup

1. Open [Settings → Lake](https://oleander.dev/app/settings/lake) and find **BigQuery connections**.
2. Give the connection a name - lowercase letters, numbers, and underscores, e.g. `my_bq`. This becomes the catalog prefix in SQL.
3. 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`:

```sql theme={null}
-- 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';
```

<Note>
  **A BigQuery table selects DuckDB.** DuckDB is the only engine that attaches external connections, so the [query router](/platform/query-routing) 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.
</Note>

## 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](/observability/overview), to see cost per table broken down by producing pipeline, query type, and full-scan detection.

## From an agent

An agent connected over [MCP](/mcp/introduction) reaches the same tables through `query_run`. It discovers them with `catalogs_list` and queries `connection.dataset.table` directly - no BigQuery-specific tool needed.