> ## Documentation Index
> Fetch the complete documentation index at: https://data-foundation.rockerbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to Google BigQuery

> Setup guide to share Rockerbox schemas with your BigQuery project.

## Pre-Requisites

* Google Cloud Platform (GCP) account
* GCP **project** with **BigQuery** resource enabled
* Chosen **region** for the dataset (cloud storage bucket) and BigQuery to reside
* A user with **admin** access to the project’s BigQuery resource

***

## Step 1: Create a BigQuery Dataset

Create a **BigQuery dataset** in your target GCP project. We recommend colocating within a single region, but support multi-region setups.

> ⚠️ **Note on regions:** Google recommends colocating your BigQuery dataset within a single region for better performance. See [Google documentation](https://cloud.google.com/bigquery/docs/external-tables) for details.

***

## Step 2: Connect Rockerbox to BigQuery

1. Open the [Warehousing setup page](https://app.rockerbox.com/v3/data/exports/data_warehouse) Rockerbox and choose **BigQuery** → **Connect to BigQuery**.
2. Enter your **dataset region**, **project ID**, and **dataset ID**, then click **SetupBigQuery**.

***

## Step 3: Copy the Rockerbox Service Account

After initialization, Rockerbox displays a **unique service account email**. Click the icon next to it to copy the address.

***

## Step 4: Grant Dataset Permissions in GCP

In GCP, grant that service account with the **DataEditor role** `roles/bigquery.dataEditor` to your BigQuery dataset  so Rockerbox can create tables.

***

## Step 5: Grant Team Access (Optional)

Back in the Rockerbox UI, add **users, groups, and/or service accounts** from your organization that should access the shared data in BigQuery.

***

## Step 6: Notify Rockerbox (One-Time Enablement)

Tell your Rockerbox support rep that you’ve completed the steps above. Due to a **BigQuery limitation**, Rockerbox must **sync underlying datasets** first before you can create tables in the Rockerbox UI. Rockerbox support will confirm when you can proceed to the next step.

***

## Step 7: Sync Rockerbox Data Sets

* Choose which datasets to share:
  * **Platform Data**: Select the ad platforms you actively use.
  * **Rockerbox Data**: Select **Conversion** and any **Log Level MTA** datasets for each conversion event that you need.
* Click **Sync this dataset** when ready.

📦 `aggregate_mta` and `taxonomy_lookup` tables are automatically created in the data share.

### ⚠️ Backfill Notes

* **Platform Performance Schemas**: No data is automatically backfilled. This can be backfilled on a limited basis upon request to `support@rockerbox.com`.
* **Rockerbox First Party Data Schemas**: For each conversion dataset, Rockerbox will backfill based on the conversion event “First Reporting Date” in Rockerbox\
  💡 If no date is set, Rockerbox backfills one day of data. This process can take up to **24 hours**.

***

## Step 8: Query your new data tables

### Sample queries: `aggregate_mta` table

Test setup

```sql theme={null}
SELECT * FROM `<project>.<dataset>.aggregate_mta` LIMIT 1;
```

Report even weight attributed conversions and spend by conversion event + tier\_1 (most broad reporting taxonomy dimension)

```sql theme={null}
SELECT 
  conversion_event_name,
  tier_1,
  SUM(even) AS conversions_even,
  SUM(included_spend) AS spend
FROM `<project>.<dataset>.aggregate_mta`
WHERE 
  date >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
  AND date < CURRENT_DATE();

```

***

## BigQuery Table Limitations

For **MTA** and **Conversions** schemas in BigQuery, nested columns—`url_parameters`, `utm_parameters`, and `additional_attributes`—won’t auto-expand when new parameters appear.

Contact Rockerbox if you need newly added parameters reflected in those fields.