Skip to main content

Cross-Project Setup

💎Premium Feature

This feature is available exclusively for Premium users.

By default GA4Dataform reads the GA4 BigQuery export from the same GCP project it writes its output tables to. The GA4_DATASET_PROJECT variable lets you split those apart: read the GA4 export from one project (the source) while materializing all outputs in another (the destination, where Dataform runs).

When to use this​

  • A dev / test / staging project that reads the production GA4 export but writes its own outputs, so experiments never touch production tables.
  • The GA4 export lives in a central data project owned by another team, and you want your transformed tables in your own project.
  • You want to keep the raw GA4 export and the modeled output under different ownership, billing, or access boundaries.

To combine multiple GA4 properties (optionally across projects) into one model, use EXTRA_GA4_DATASETS_ARRAY - see Multi-Property Support.

Configuration​

GA4_DATASET_PROJECT is a workflow_settings.yaml variable (not a value in the GA4 module's config.js). Add it under vars:

# workflow_settings.yaml
defaultProject: my-output-project      # where Dataform runs and writes outputs (destination)
defaultDataset: superform_outputs
defaultLocation: EU
vars:
  GA4_DATASET_PROJECT: my-ga4-export-project   # where the GA4 export lives (source)
  • Source (GA4 export): GA4_DATASET_PROJECT.
  • Destination (outputs): defaultProject.

When GA4_DATASET_PROJECT is unset, the GA4 source is read from defaultProject - i.e. source and destination are the same project (the default behavior).

Region must match

The source GA4 dataset and your destination must be in the same BigQuery region (defaultLocation). BigQuery cannot join tables across regions.

Grant cross-project access​

The Dataform service account (in the destination project) must be able to read the GA4 export in the source project. Grant it BigQuery Data Viewer on the source:

gcloud projects add-iam-policy-binding my-ga4-export-project \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/bigquery.dataViewer"

Replace SERVICE_ACCOUNT_EMAIL with the Dataform service account used by your repository. Without this role, source reads fail with a permission error.

Verify before a full run

After setting the variable and granting access, trigger a small run (or a dry run) and confirm the GA4 source tables resolve to my-ga4-export-project. A permission or region mismatch surfaces immediately on the first source read.

Precedence​

When using EXTRA_GA4_DATASETS_ARRAY, a per-dataset project on an entry takes precedence over GA4_DATASET_PROJECT for that dataset. The resolution order for each GA4 source is:

  1. the dataset entry's own project (if set), then
  2. GA4_DATASET_PROJECT (if set), then
  3. defaultProject.