BigQuery

Summation reads from BigQuery as a Google Cloud service account. You configure the project to bill jobs to and paste the service account’s JSON key.

What you’ll need

A GCP project ID containing (or with access to) the data you want to expose. See Identifying projects.
A service account in that project. See Create service accounts.
A JSON key for the service account. See Create and delete service account keys.
Three IAM roles for the service account:
- roles/bigquery.jobUser on the project: lets Summation run queries.
- roles/bigquery.dataViewer on each dataset (or the project): lets Summation read data.
- roles/bigquery.readSessionUser on the project: required. Summation reads via Arrow / the BigQuery Storage API, which creates read sessions.
All three roles are documented under BigQuery IAM roles and permissions.

Grant bigquery.dataViewer on individual datasets rather than at the project level to limit Summation’s read scope to exactly what you intend.

Form fields

Field	Required	Stored as	Notes
Project ID	Yes	Config	The GCP project Summation runs jobs in, e.g. `my-gcp-project-123`. See Identifying projects.
Dataset ID	Optional	Config	Default dataset for attached tables whose source reference does not name one. It does not restrict browsing; you can browse and attach tables from any dataset the service account can read, whatever this is set to. See Datasets overview.
Location	Optional	Config	BigQuery region, e.g. `US`, `EU`, `us-east4`. Collected by the form but not currently applied when browsing or reading, so setting it does not change which datasets are reachable. See Dataset locations.
Service Account JSON	Yes	Secret	The full contents of the JSON key file (including the surrounding `{` and `}`).

Creating the service account

In the GCP Console

Open IAM & Admin → Service Accounts for the project.
Click Create Service Account.
Enter a name (for example summation) and click Create and Continue.

On Grant this service account access, add these three roles, then click Continue and Done:

Role	Purpose
BigQuery Job User (`roles/bigquery.jobUser`)	Run queries in the project
BigQuery Data Viewer (`roles/bigquery.dataViewer`)	Read tables and datasets
BigQuery Read Session User (`roles/bigquery.readSessionUser`)	Required for Arrow / Storage API reads

If you prefer to scope Data Viewer to individual datasets, skip it here and grant it per dataset after the account exists.

Open the new service account → Keys → Add Key → Create new key → JSON. The downloaded .json file is the credential for the form.

With gcloud

PROJECT_ID=my-gcp-project-123

gcloud iam service-accounts create summation \
  --project="$PROJECT_ID" \
  --display-name="Summation"

# Lets Summation run queries in the project
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:summation@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

# Required: Summation reads via Arrow / Storage API read sessions
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:summation@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.readSessionUser"

# Repeat per dataset you want to expose
bq add-iam-policy-binding \
  --member="serviceAccount:summation@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer" \
  "$PROJECT_ID:analytics"

# Generate a JSON key, paste it into the form, then delete the local copy
gcloud iam service-accounts keys create summation-key.json \
  --iam-account="summation@$PROJECT_ID.iam.gserviceaccount.com"

The downloaded summation-key.json is a credential. Paste it into Summation, then delete the local copy. See Best practices for managing service account keys.

Adding datasets

After saving the connection, browse the project’s BigQuery datasets and select tables or views. Source references use the form:

adbc:dataset_id.table_name

Common problems

Error or symptom	Likely cause
`Access Denied: Project ... User does not have bigquery.jobs.create permission`	Grant `roles/bigquery.jobUser` on the project.
`Access Denied` on `bigquery.readsessions.create`, Arrow, or Storage API	Grant `roles/bigquery.readSessionUser` on the project. Job User and Data Viewer are not sufficient.
`Not found: Dataset ...`	The service account can’t see the dataset (grant `roles/bigquery.dataViewer` on it), or the dataset name is wrong. Setting Location does not resolve this; it isn’t applied when browsing or reading.
`Invalid JSON`	Paste the full file contents including the surrounding `{` and `}`. Don’t escape or wrap the JSON.

Get started

Key concepts

Connectors

Agent integrations

What you’ll need

Form fields

Creating the service account

In the GCP Console

With gcloud

Adding datasets

Common problems

​What you’ll need

​Form fields

​Creating the service account

​In the GCP Console

​With gcloud

​Adding datasets

​Common problems

What you’ll need

Form fields

Creating the service account

In the GCP Console

With gcloud

Adding datasets

Common problems