How Conversion works with BigQuery
Conversion connects to BigQuery through a dedicated service account and runs the SQL queries you write on a schedule you choose. Each query's rows become contacts, custom objects related to contacts, or events that can trigger workflows and filter audiences. Access is limited to the datasets you share with the service account, and Conversion never writes to your project.
What you can do
Standard SQL on shared datasets
Query any dataset you share with the service account, join across datasets with fully qualified table names, and alias columns with AS to match Conversion field keys.
Objects with relationships
Sync products, subscriptions, or usage as custom objects tied to contacts, so audiences, workflows, and email personalization can reference a plan or product directly.
Events for workflows and audiences
Synced events appear on each contact's timeline, where they can start workflows and define who belongs in an audience.
Lean, incremental scans
BigQuery bills for the data a query scans. Filter on last_sync_time with TIMESTAMP_SECONDS() and select only the columns you need, so each run reads just the rows that changed.
What syncs
| Data | Direction | Details |
|---|---|---|
| Contacts | Into Conversion | Created or updated from query rows, matched on userId when present and on email otherwise. Creating a contact requires an email. |
| Custom objects | Into Conversion | Any custom object type you create in Conversion, with relationship fields to contacts built in the same query using JSON_OBJECT. |
| Events | Into Conversion | Rows with an event name and timestamp land on the contact timeline. An eventId keeps re-synced rows from duplicating. |
How to connect BigQuery
- 1 Create a dedicated Google Cloud service account with the BigQuery Job User and BigQuery User roles, and generate a JSON key for it.
- 2 Share each dataset you want to sync with the service account as BigQuery Data Viewer, or grant that role across the project.
- 3 If your project uses VPC Service Controls or IP restrictions, allow Conversion's IP addresses.
- 4 Under Settings > CRM & Syncing > Connections, add a BigQuery connection with your project ID and the full JSON key, then create a sync for each destination.
