BigQuery

image-20250812-061101.png

Zeta supports integration with Google BigQuery for seamless data access and segmentation within the Zeta Marketing Platform (ZMP). This guide will help you set up a secure connection using either Google Cloud service account credentials (JSON key file) or Workload Identity Federation (WIF) authentication.

Prerequisites:

Before you begin, ensure that External databases are enabled for your ZMP account.

  • This requires submitting a support ticket to Zeta to enable the ext_db_segmentation_enabled flag on your account.

Setting Up the BigQuery Connection

Once external databases are enabled:

1. Navigate to Settings > Integrations > Connections. Click on Create Connection.

image-20260910-093421 (1).png

2. On the Select Connection Type page, click on the Google BigQuery tile. Click on Next.

image-20260917-082120.png

  • Zeta connects to BigQuery using the existing Google BigQuery connection type.

  • On the connection credentials screen, choose one authentication method:

    • JSON File — upload a Google Cloud service account JSON key

    • Manual — enter service account key fields manually

    • WIF Authentication — configure Workload Identity Federation (no long-lived keyfile)

  • You will also need a Temp Dataset (tmp_dataset) — a dataset in your project that ZMP can use for temporary tables — when using service account keyfile authentication.

image-20261027-075913.png

3. Prepare credentials in Google Cloud (and AWS, if using WIF).

Option A — Service account JSON key

Create a service account in Google Cloud Console and generate a key.

  • Once the key is created, download the JSON key file; you will need it for ZMP configuration.

image-20261027-075754.png

Option B — Workload Identity Federation (WIF)

WIF lets ZMP access BigQuery with short-lived federated credentials instead of a downloaded service account key. Use this when your security or compliance requirements prefer federated identity over long-lived keyfiles.

In Google Cloud, configure a Workload Identity Pool and provider so ZMP can exchange identity for a short-lived token and (optionally) impersonate a target service account that has BigQuery access. If your federation trust includes AWS, configure the corresponding AWS IAM role as well.

image-20261027-075527.png

You will need the following values ready before completing the ZMP form:

Field in ZMP

What it is

Where to find it

GCP Project ID

Project ID for the BigQuery / WIF setup

Google Cloud Console → project picker, or IAM & Admin → Settings

Project Number

Numeric project number

Same Settings page (distinct from Project ID)

Workload Identity Pool ID

ID of the pool you created

IAM & Admin → Workload Identity Federation → select pool

Provider ID

ID of the identity provider under that pool

Same pool page → Providers

Service Account Email to Impersonate

Target service account ZMP impersonates for BigQuery access

IAM & Admin → Service Accounts

AWS Role ARN

AWS IAM role used in the federation trust

AWS IAM → Roles → role ARN

Token Duration (optional)

Lifetime of the temporary token

Choose a value between 10 minutes and 12 hours (default 1 hour). The same maximum must also be allowed in your GCP WIF / IAM configuration.

Location

BigQuery location/region for the connection

Match the location of your datasets

Use Storage API

Optional toggle for higher-throughput BigQuery Storage API access

Enable if you want Storage API reads (ensure the impersonated service account has the required permissions)

Notes for WIF setup:

  • WIF is an additional authentication method on the Google BigQuery connection — not a separate connection type.

  • Grant the impersonated service account least-privilege BigQuery access to the datasets/tables ZMP will use, plus access to any temporary dataset required for your workflows.

  • Do not send pool IDs, ARNs, or service account emails through unsecured channels if your security policy restricts that; enter values directly in the ZMP Connections UI.

4. Zeta provides a BigQuery test instance for onboarding and sandbox testing: Zeta Demos Project on Google Cloud Console. [Invite required; reach out to David Harry or your Zeta representative]

Service Account Key Configuration (Sample)

When adding the connection in ZMP with JSON File or Manual authentication, you'll be asked to provide details from your service account JSON. The required format looks like this (example only):

{
  "type": "service_account",
  "project_id": "zeta-demos",
  "private_key_id": "xxxxxxx",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...",
  "client_email": "bq-services@zeta-demos.iam.gserviceaccount.com",
  "client_id": "xxxxxxx",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  ...
}

There is a parameter called tmp_dataset. If unsure what to enter, use: zeta-demos (for the Zeta demos/sandbox project when that dataset is available to your service account).If unsure what to enter, use: zeta-demos

Using BigQuery After the Connection Is Live

Once your BigQuery connection is saved and active, you can typically:

  • Use Zero Copy Database Explorer to segment and personalize against BigQuery tables without copying data into ZMP first. See Zero Copy Database Explorer.

  • Use BigQuery as a source in Data Flows when you want selected data ingested into ZMP. See Data Flows.

If you plan to use Zero Copy, open the connection’s action menu (⋯) → Configure Tables & Groups, assign a User ID, and configure targeting/personalization columns as needed.

WIF and Data Flows query preview

If your BigQuery connection uses WIF Authentication, query preview in Data Flows may be unavailable. You can still save and run the Data Flow; execution uses the WIF connection. Use a service account keyfile connection if you need interactive query preview while authoring the flow.