Connect BigQuery
Create a service account, scope it to a dataset, and connect BigQuery to Arcus.
Arcus reads from BigQuery using a service account with two roles: BigQuery Data Viewer and BigQuery Job User. Setup takes about 10 minutes if you're already a project owner.
What Arcus needs
- A GCP project with BigQuery enabled.
- A service account scoped to read the dataset(s) you want exposed.
- The JSON key for that service account.
We don't write to your warehouse, ever. The role grants we ask for are the minimum needed to discover the schema and run SELECT queries.
GCP-side setup
Run these in the GCP Console or the gcloud CLI. Replace my-project with your project ID and my-dataset with the dataset you want exposed.
1. Create a service account
gcloud iam service-accounts create arcus-reader \
--display-name="Arcus Reader" \
--project=my-project
2. Grant minimum roles at the project level
gcloud projects add-iam-policy-binding my-project \
--member=serviceAccount:arcus-reader@my-project.iam.gserviceaccount.com \
--role=roles/bigquery.jobUser
bigquery.jobUser lets the service account run queries. It does not grant data access — that's scoped per-dataset below.
3. Grant data viewer on the specific dataset
In the BigQuery console, open your dataset, click Sharing → Permissions, and add arcus-reader@my-project.iam.gserviceaccount.com with BigQuery Data Viewer.
Or via CLI:
bq update --source=- my-project:my_dataset <<EOF
{
"access": [
{
"role": "READER",
"userByEmail": "arcus-reader@my-project.iam.gserviceaccount.com"
}
]
}
EOF
If you have multiple datasets to expose, repeat for each. Or grant BigQuery Data Viewer at the project level instead — but that's broader than most teams want.
4. Generate a JSON key
gcloud iam service-accounts keys create arcus-reader-key.json \
--iam-account=arcus-reader@my-project.iam.gserviceaccount.com
This downloads a JSON file. Keep it secret — anyone with this key can read everything the service account can read.
Arcus-side setup
In Arcus, open Settings → Connections → Add a connection and pick BigQuery. Fill in:
- Connection name — readable label, like "Production BigQuery".
- Project ID —
my-project. - Default dataset — optional. If set, Arcus uses it as the default for ambiguous queries.
- Service account JSON — paste the entire contents of
arcus-reader-key.json.
Click Save. Arcus runs SELECT 1 to verify and shows a green Connected badge.
After connecting, delete the local JSON file. Arcus stores it encrypted at rest with envelope encryption (per-tenant data key wrapped by a root KEK) — but the source-of-truth copy on your machine is now redundant and shouldn't sit around.
Cost-control tip
By default, BigQuery bills you per byte scanned. Arcus queries small — typical scans are under 1 GB — but it's still wise to set a tenant-level scan cap so a malformed query can't accidentally chew through 100 GB.
In Arcus: Settings → Connections → [your connection] → Cost cap. Default is 10 GB per query. We refuse to run queries above the cap and tell the agent to narrow the question.
Common errors
User does not have permission to perform this action — the service account is missing bigquery.jobUser at the project level. Re-run the add-iam-policy-binding command.
Permission denied: Not allowed to access dataset — the service account is missing BigQuery Data Viewer on the dataset. Add it via console or bq update.
Invalid JSON key — the JSON file got corrupted (often by line-wrapping in chat or email). Re-generate the key and paste it exactly as the file contents.
Test the connection
Click Discover schema on the connection. Arcus lists every dataset and table the service account can see. If a dataset you expected is missing, it's a permission issue — add Data Viewer for that dataset.
Region note
Arcus's compute runs in US regions. If your BigQuery dataset is in EU or APAC, queries still work — BigQuery handles cross-region — but expect 100-300ms of extra latency. For latency-sensitive tenants, contact us about deploying compute closer to your dataset.