Connect BigQuery
Set up a Google BigQuery connection with a service-account key — the project and a least-privilege data-viewer role.
This page covers connecting Google BigQuery to Flax. Add the connection from the Data page at /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:
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.