BigQuery

Convertmax can send data to BigQuery in two ways. Use the sections below to see which option matches your account, then follow the authentication and validation steps that apply.

Two ways data reaches BigQuery

(A) Managed reporting replication

Use this option when you want classified reporting data copied into tables in your GCP project on a managed schedule.

Typical tables (depending on your reporting setup):

• daily_searches
• acquisition_events
• conversion_events
• custom_events

Convertmax or your onboarding team configures this path for your workspace. It is separate from the real-time warehouse sync option below.

(B) Data warehouse sync (event stream)

Use this option when Data Warehouse Sync is enabled for your organization and you want event data delivered into a BigQuery table you control.

Events are written with stable columns (for example event_type, occurred_at, and event payload fields). Delivery can work in one of two ways:

Your Convertmax contact can confirm which delivery style is active for your workspace.

Authentication

Convertmax supports two authentication options for BigQuery. Choose the one that matches your security and GCP policies.

Service account impersonation (recommended)

This is the recommended option for most customer-managed GCP projects.

1. Create or designate a writer service account in your GCP project with access to the target BigQuery dataset.
2. Grant Convertmax permission to impersonate that writer service account (roles/iam.serviceAccountTokenCreator on the writer account).
3. Provide the writer service account email when prompted in Convertmax or to your onboarding contact.

This approach avoids sharing long-lived JSON keys while still allowing Convertmax to write into your project.

Service account JSON key

Use this option when you prefer to provide a dedicated BigQuery service account key file to Convertmax.

This fits teams that:

• want to supply a dedicated key for the integration
• are not using cross-project impersonation

Upload or share the key only through the channels your security team approves.

Set up in the Convertmax app

When Data Warehouse Sync is enabled for your organization:

1. Open Integrations and the Data Warehouse (BigQuery) flow for your workspace.
2. Enter your GCP project ID and BigQuery dataset ID.
3. Choose Impersonation or Service account JSON and complete the prompts.

Some accounts also support browser-based GCP setup (OAuth, dataset selection, and permission checks). If you do not see those steps, your workspace may use a guided setup instead—contact Convertmax support.

Prepare the target BigQuery dataset

For both options, create or confirm:

1. a GCP project that will own the export
2. a BigQuery dataset for Convertmax data
3. tables that match the option you use (reporting tables for (A), or your event table for (B))

At minimum you need:

• GCP project ID
• BigQuery dataset ID

Table names and schemas depend on your setup. Follow guidance from onboarding or Convertmax support.

Validate the export

After setup:

1. Confirm the dataset exists in the correct GCP project.
2. Confirm Convertmax has permission to write to that dataset.
3. Confirm new rows appear in the expected tables (reporting tables for (A), or your event table for (B)).

Allow time for the first batch load if your account uses batch delivery.

Troubleshooting

Permission denied on impersonation

Confirm:

• the Convertmax service account can impersonate your writer service account (roles/iam.serviceAccountTokenCreator on the writer)
• the writer service account has BigQuery access to the target dataset

Saved in the app but no data in BigQuery

Confirm the GCP project ID and dataset ID are correct, then contact Convertmax support with your workspace name and the approximate time you completed setup. If your account uses batch delivery, ask when the next load is expected.

Missing reporting tables

Reporting table names and schemas vary by account. Ask Convertmax support which tables apply to your workspace before creating tables manually.