BigQuery

BigQuery is the supported way to import product usage from Google Cloud. Sonora reads a single table or view per product, joining it to your existing customers via an external ID column.

Authentication uses a Sonora-owned Google Cloud service account. You grant that service account read access to the dataset; no credentials are exchanged.

What Sonora reads

A BigQuery connection imports product usage only. Customer records have to come from a CRM connection (Salesforce or HubSpot) — BigQuery usage rows then match to those customers via an external ID column.

Sonora treats three columns as fixed metadata: account ID, date, and (optionally) product. Every other numeric column is imported as a usage metric.

If you need a starting point for shaping a usage table, the Product Usage Upload Template shows the expected layout.

Prerequisites

• roles/bigquery.admin or roles/owner on the Google Cloud project containing your dataset
• A configured customer source in Sonora (Salesforce or HubSpot) to match account IDs against

Grant Sonora’s service account access

Sonora connects as turbine@sonora-production.iam.gserviceaccount.com with the BigQuery Data Viewer role. Pick whichever method fits your workflow.

Option A: Cloud Console

1. Open the BigQuery console and select your dataset.
2. Click Share → Manage permissions → Add principal.
3. Paste turbine@sonora-production.iam.gserviceaccount.com.
4. Assign BigQuery Data Viewer (roles/bigquery.dataViewer).
5. Save.

Option B: gcloud (project-level)

This grants access to every dataset in the project. Replace YOUR_PROJECT:

gcloud projects add-iam-policy-binding YOUR_PROJECT \
  --member="serviceAccount:turbine@sonora-production.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

Option C: Terraform (dataset-level)

resource "google_bigquery_dataset_iam_member" "sonora_viewer" {
  project    = "your-project"
  dataset_id = "your_dataset"
  role       = "roles/bigquery.dataViewer"
  member     = "serviceAccount:turbine@sonora-production.iam.gserviceaccount.com"
}

Configure customer matching in Sonora

In Settings → Integrations → BigQuery → Configure, set the Customer External ID Source to whichever CRM owns the IDs in your BigQuery table:

• salesforce or salesforce_oauth for Salesforce Account IDs
• hubspot for HubSpot Company IDs

If this isn’t set, product usage imports will fail.

Share connection details

Send your Sonora contact:

Field	Example
Project	acme-analytics-prod
Dataset	product_usage
Table	events

Find the project ID in the Cloud Console URL, or run gcloud config get-value project.

Troubleshooting

“Access denied” when Sonora queries — Verify the grant: bq show --format=prettyjson YOUR_PROJECT:YOUR_DATASET | grep turbine. The service account should appear in the access list with role READER. If it isn’t there, re-grant access.

“Not found” — Project, dataset, and table names are case-sensitive in BigQuery. Confirm each one matches exactly.

Empty results after sync — Check that the IDs in your usage table actually come from the source you configured. Sonora reports zero rows when the external ID source is mismatched, even when the BigQuery query itself returns data.