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

# BigQuery

> Connect Summation to a Google BigQuery project.

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](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects).
* A **service account** in that project. See [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create).
* A **JSON key** for the service account. See [Create and delete service account keys](https://cloud.google.com/iam/docs/keys-create-delete).
* Two 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.

  Both roles are documented under [BigQuery IAM roles and permissions](https://cloud.google.com/bigquery/docs/access-control).

<Tip>
  Grant `bigquery.dataViewer` on individual datasets rather than at the project level to limit Summation's read scope to exactly what you intend.
</Tip>

## 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](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects). |
| **Dataset ID**           | Optional | Config    | Default dataset to scope the connection to. Leave blank to expose multiple datasets. See [Datasets overview](https://cloud.google.com/bigquery/docs/datasets-intro).                           |
| **Location**             | Optional | Config    | BigQuery region, e.g. `US`, `EU`, `us-east4`. Required when datasets aren't in the multi-region default. See [Dataset locations](https://cloud.google.com/bigquery/docs/locations).            |
| **Service Account JSON** | Yes      | Secret    | The full contents of the JSON key file (including the surrounding `{` and `}`).                                                                                                                |

## Creating the service account

```bash theme={null}
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"

# 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 this 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"
```

<Warning>
  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](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys).
</Warning>

## 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.                                                                                                                       |
| `Not found: Dataset ...`                                                        | The **Location** doesn't match the dataset's region. BigQuery rejects cross-region reads. See [Dataset locations](https://cloud.google.com/bigquery/docs/locations). |
| `Invalid JSON`                                                                  | Paste the full file contents including the surrounding `{` and `}`. Don't escape or wrap the JSON.                                                                   |