# Connect BigQuery

> Set up a Google BigQuery connection with a service-account key — the project and a least-privilege data-viewer role.

*[View this page in the Flax docs](https://flax-analytics.com/docs/connections/bigquery)*

This page covers connecting Google BigQuery to Flax. Add the connection from the **Data** page at [/app/data](/app/data).

## Authentication

Flax authenticates as a **service account**. Create one in Google Cloud, download its JSON key, and give Flax that key — Flax signs a JWT with the private key and exchanges it for a short-lived BigQuery access token on each run.

## Required fields

| Field | Description |
| --- | --- |
| `project_id` | The Google Cloud project that runs (and is billed for) your queries. |
| `service_account_json` | The full service-account key JSON, stored as the connection secret and encrypted at rest. |

## Least-privilege credentials

Grant the service account only what read-only analytics needs — do not reuse a project owner or editor account:

```bash
gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:flax@my-project.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:flax@my-project.iam.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"
```

`bigquery.dataViewer` allows reading tables and `bigquery.jobUser` allows running query jobs. Scope `dataViewer` to specific datasets if you want to narrow access further.

> [!IMPORTANT]
> Treat the service-account JSON like a password. Flax encrypts it at rest, but you should still rotate the key periodically and delete unused keys in Google Cloud.

## Query execution

Explore queries are compiled to BigQuery Standard SQL and pushed down to your project (ADR-0004); query jobs run — and are billed — in the project you configured.

## Related

- [Connecting data](/docs/connections/overview)
- [Connection security](/docs/connections/security)
- [Caching & performance](/docs/connections/caching-and-performance)