Connect BigQuery

BigQuery is a serverless data warehouse. climpt connects to it with a service account key and reads through the BigQuery Storage Read API — it never writes, and it keeps no copy of your tables.

Credentials

Service account JSON

The complete key file downloaded from the Google Cloud console. The project_id is read from the file, so there is nothing else to enter.

Permissions

Because climpt reads table data through the Storage Read API, it needs three read-only roles — two at project level and one on each dataset you expose. All three are required; queries fail if any is missing.

roles/bigquery.jobUser

Project level. Lets climpt create a query job. Without it no query can start at all.

roles/bigquery.readSessionUser

Project level. Lets climpt read results through the Storage Read API. Skip this one and discovery still works, which makes it look fine — then every query fails with a bigquery.readsessions.create permission error.

roles/bigquery.dataViewer

Dataset level, once per dataset. Grants read-only access to the tables in that dataset.

Scope access to the datasets you want analysed

Grant Data Viewer on specific datasets, never at project level. climpt discovers and scans every dataset the service account can read, so the account’s access is the scope — and BigQuery enforces it. A dataset you don’t grant cannot be read, whatever climpt asks for.

Creating the service account

1. In the Google Cloud console, go to IAM & Admin → Service Accounts and click Create service account.
2. Name it something recognisable, for example climpt-analytics-readonly.
3. Grant the project-level role BigQuery Job User.
4. Add the second project-level role, BigQuery Read Session User.
5. Click Continue, then Done.
6. Open BigQuery, find a dataset you want climpt to read, and use ⋮ → Share.
7. Add the service account email and grant it BigQuery Data Viewer. Repeat for each dataset you want exposed.
8. Back in Service Accounts, open the account, go to the Keys tab and choose Add key → Create new key → JSON.
9. Paste the downloaded file into the Service Account JSON field in climpt.

The same setup from the command line

Replace PROJECT_ID and DATASET with your own. Run the gcloud commands in Cloud Shell or any terminal with the gcloud CLI; run the GRANT in the BigQuery Studio SQL editor.

1 · Service account, project roles and key

# Create the read-only service account, in the project where queries run
gcloud iam service-accounts create climpt-analytics-readonly \
  --project=PROJECT_ID \
  --display-name="climpt Analytics (read-only)"

# Project level: allow running queries
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:climpt-analytics-readonly@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

# Project level: allow reading table data via the Storage Read API (required)
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:climpt-analytics-readonly@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.readSessionUser"

# Create the JSON key to paste into climpt
gcloud iam service-accounts keys create climpt-key.json \
  --iam-account=climpt-analytics-readonly@PROJECT_ID.iam.gserviceaccount.com

2 · Dataset access — run once per dataset

GRANT `roles/bigquery.dataViewer`
ON SCHEMA `PROJECT_ID`.DATASET
TO "serviceAccount:climpt-analytics-readonly@PROJECT_ID.iam.gserviceaccount.com";

What the key file looks like

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "abc123...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...",
  "client_email": "service-account@project.iam.gserviceaccount.com",
  "client_id": "123456789...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  ...
}

Exposing views

Views work, but BigQuery checks permissions on both sides of one:

• The service account needs Data Viewer on the dataset containing the view. Sharing only the underlying tables is not enough.
• It also needs Data Viewer on every dataset the view’s definition reads, including nested views — unless you use authorized views.
• Prefer authorized views to expose curated data without sharing raw tables: share the view’s dataset only, then authorize the view against its sources under Dataset → Sharing → Authorized views.

After a scan, the Datasets climpt can access dialog flags any view whose underlying data the service account cannot read, and names the dataset to grant.

Worth knowing

• BigQuery bills on data scanned. Filter with WHERE and LIMIT, and consider slot reservations or quotas to cap spend.
• Rotate the service account key roughly every 90 days.
• All connections are encrypted with TLS.
• Enable Cloud Audit Logs if you want an independent record of every query climpt runs.
• You can use separate service accounts per environment or team.
• BigQuery uses standard SQL.