Connect GA4 BigQuery export

Previous Next

Connect GA4 BigQuery export

Connect your GA4 BigQuery export to calibrate AI shoppers from your exported event data. Squoosh reads device, geography, traffic source, and session conversion counts directly from BigQuery.

Beta: technical setup required

This connector remains in beta at the snapshot stage. It needs a GA4 daily export and a Google Cloud service account. Its REST requests are covered by offline tests; those tests do not establish agreement with a live property's GA4 reports. For a simpler setup, use Connect Google Analytics.

What the connection does

Squoosh queries your GA4 daily export tables and aggregates distinct sessions into device, geography, and traffic-source distributions. If you provide a key event, it also counts sessions containing that event against the same query's total sessions.

You can run a test without connecting analytics. See AI shoppers for how calibration affects the shopper pool.

Before you connect

  1. Link GA4 to BigQuery. In your property's Admin → Product Links → BigQuery Links, configure the link and enable Daily export. Wait until daily tables appear in the export dataset. Google does not guarantee an exact daily export time. See Google's BigQuery Export guide.
  2. Create a service account. In Google Cloud's IAM & Admin → Service Accounts, create an account with BigQuery Data Viewer on the export dataset and BigQuery Job User on the project. The latter lets it create query jobs. Under the service account's Keys tab, select Add key → Create new key → JSON and download the key. See BigQuery access control.

Connect GA4 BigQuery export

  1. In the sidebar, click Integrations.
  2. In the GA4 BigQuery export row, click Connect.
  3. Enter:
  4. Service account JSON: paste the complete downloaded key file. Squoosh keeps this credential private.
  5. GCP project: the project ID that owns the export.
  6. Dataset: the export dataset name, for example analytics_123456.
  7. Key event name (optional): an event such as purchase. Leave it blank to omit the conversion signal.
  8. Dataset location (optional): a location such as US, EU, or europe-west1. Leave it blank to let BigQuery detect the location from the dataset. An explicit value must match the dataset's location. See BigQuery locations.
  9. Click Connect.

Squoosh verifies access with a dry-run query against your configured export tables before saving the connection. Dry runs do not incur query charges. See BigQuery cost controls.

What Squoosh reads

Dimension Source Counting basis
Device device.category Distinct session identifiers per device
Geography geo.country Distinct session identifiers per country
Traffic source session_traffic_source_last_click.cross_channel_campaign source/medium, falling back to manual_campaign Distinct session identifiers per source/medium pair, mapped into Squoosh channels
Conversion The configured event_name and the query's total sessions Sessions containing the event divided by total sessions

The query forms a session identifier from user_pseudo_id and the ga_session_id event parameter. These fields are documented in Google's GA4 export schema. Squoosh retrieves aggregate rows, not individual event records or session identifiers. It does not modify your export tables.

A dimension needs enough traffic before it can calibrate the shopper pool. Sparse data does not become a guessed distribution.

Limits and caveats

  • Fixed window: 30 UTC dates including today. The query reads matching daily events_YYYYMMDD tables and excludes events_intraday_*. Today's daily table may not exist yet, so this is not a promise of 30 complete days of data. The window does not follow the requested experiment window or the GA4 property's timezone.
  • Query cost ceiling. Each snapshot attempt includes maximumBytesBilled, defaulting to 5 GiB. BigQuery rejects a query above that ceiling without charging for it. Retries are separate attempts. Squoosh operators can configure the ceiling through GA_BIGQUERY_MAX_BYTES_BILLED.
  • Bounded results. Squoosh follows result pages and rejects a result exceeding its 50-page limit instead of returning a clipped snapshot.
  • No key event means no conversion signal. The event name must match your export.
  • Read permissions. BigQuery Data Viewer on the dataset and BigQuery Job User on the project are required; table write permissions are unnecessary.
  • Identifier validation. Project IDs accept letters, digits, underscores, and hyphens; dataset IDs accept letters, digits, and underscores. This connection does not support legacy domain-scoped project IDs.
  • Validation still outstanding. Live checks must resolve OAuth scope acceptance, the dry-run response envelope, wildcard scan pruning, and whether channel fields stay constant within a session. Until then, do not assume exact parity with GA4's reporting UI.

Troubleshooting

Problem What to do
Service account JSON cannot be parsed Paste the full downloaded JSON file without editing it.
Missing client_email or private_key Download a valid service-account JSON key.
Dataset not found or not accessible Check project/dataset spelling, dataset access, and any explicit location. Clear a wrong location to allow detection.
Access denied Confirm Data Viewer on the dataset and Job User on the project.
Rate limit or temporary backend failure Retry later. BigQuery can report transient job failures with HTTP 400 and rate limits with HTTP 403.
Resource, response-size, or execution limit Ask your BigQuery administrator to inspect the failed query. Retrying the same workload may exceed the same limit.
Per-query cost ceiling exceeded No query charge was incurred for this rejection. Ask your Squoosh operator about the configured ceiling.
No data appears Confirm daily export tables exist in the fixed query window. Daily export timing is not guaranteed.

Error classifications follow BigQuery's error table. Squoosh displays fixed error descriptions so provider responses cannot expose credentials.

Connect Segment Adobe Commerce (Magento)