BigQuery

Sonora connects to BigQuery using a Google Cloud service account. You grant Sonora’s service account read-only access to the dataset containing your product usage data—no credentials are exchanged or stored.

BigQuery imports are product usage only. Customer records are matched using external IDs from an existing customer source (for example Salesforce or HubSpot).

In product usage tables, Sonora treats the configured account, date, and product columns as mapped metadata. All other numeric columns are imported as usage metrics.

If you need a starting point for structuring your data, use the Product Usage Upload Template to see the expected format.

Customer matching setup

In BigQuery Product Usage settings, choose the Customer External ID Source that owns the account IDs in your BigQuery table.

• If your table uses Salesforce Account IDs, select salesforce or salesforce_oauth.
• If your table uses HubSpot Company IDs, select hubspot.

If this source is not set, product usage imports will fail until it is configured.

Prerequisites

You need roles/bigquery.admin or roles/owner on the Google Cloud project containing your dataset.

Grant access to Sonora

Add Sonora’s service account as a member on your BigQuery dataset with read-only access.

Option A: Google Cloud console

1. Open the BigQuery console and select your dataset.

2. Click Share → Manage permissions → Add principal.

3. Enter the service account:

   turbine@sonora-production.iam.gserviceaccount.com

4. Assign the role BigQuery Data Viewer (roles/bigquery.dataViewer).

5. Click Save.

Option B: gcloud CLI

This grants access at the project level (all datasets). Replace YOUR_PROJECT with your own value:

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

To scope access to a single dataset instead, use the Console or Terraform options.

Option C: Terraform

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"
}

Share connection details

Send your Sonora contact the following so we can complete the setup:

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

Your project ID appears in your Google Cloud console URL or can be found with gcloud config get-value project.

Troubleshooting

“Access denied” when Sonora tries to query — Verify the grant with bq show --format=prettyjson YOUR_PROJECT:YOUR_DATASET | grep turbine. The service account should appear in the access list with role READER. If it does not, re-grant using the steps above.

“Not found” error — Confirm the project ID, dataset name, and table name are correct. BigQuery identifiers are case-sensitive.

Data not appearing after sync — Check that the table contains the expected columns and that the customer external ID source is configured in Sonora’s BigQuery settings.