> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auxia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Google BigQuery setup guide

> Connect BigQuery tables to Auxia step by step

Follow these steps to connect BigQuery tables to Auxia. Setup takes about **15 minutes**, most of it waiting for permissions to propagate.

## Prerequisites

* Access to the [Auxia Console](https://console.auxia.io) with permission to create connections

* A GCP project containing the BigQuery datasets you want to connect

* Permission to grant IAM roles on that project or dataset:

  | Grant access at | Permission you need | Typical role |
  | - | - | - |
  | **Project level** | `resourcemanager.projects.setIamPolicy` | Project IAM Admin |
  | **Dataset level** | `bigquery.datasets.setIamPolicy` | BigQuery Data Owner or BigQuery Admin |

  If you don't have these, the wizard generates the exact commands to hand to your GCP administrator.

* Tables that meet the [table requirements](/data-ingestion/data-connections/google-bigquery#table-requirements)

## Setup instructions

<Steps>
  <Step title="Start a new connection">
    In the Auxia Console, go to **Configuration → Connections**, click **Add New Connection**, and choose **BigQuery**.

    The wizard shows a **service account email** unique to your Auxia project. You'll grant this account read access in the next step.
  </Step>

  <Step title="Enter your project and grant access">
    Enter:

    | Field | Notes |
    | - | - |
    | **GCP Project ID** | Your project, e.g. `my-analytics-project`. Lowercase letters, digits, and hyphens; 6–30 characters. |
    | **Datasets** | Comma-separated dataset names. At least one is required. |
    | **Tables** | Optional. Comma-separated, to narrow the scan. |

    Then grant the service account the **BigQuery Data Viewer** role (`roles/bigquery.dataViewer`) using any one of these methods:

    <Tabs>
      <Tab title="Command line">
        The wizard generates these commands with your project and service account filled in — copy them from there.

        **Project-level access** (all current and future datasets in the project):

        ```bash theme={null}
        gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
          --role="roles/bigquery.dataViewer" \
          --condition=None
        ```

        **Dataset-level access** (run once per dataset):

        ```bash theme={null}
        bq query --use_legacy_sql=false '
        GRANT `roles/bigquery.dataViewer`
        ON SCHEMA `YOUR_PROJECT_ID.YOUR_DATASET_NAME`
        TO "serviceAccount:SERVICE_ACCOUNT_EMAIL";
        '
        ```
      </Tab>

      <Tab title="Google Cloud console">
        **Project-level access:**

        1. In the [Google Cloud console](https://console.cloud.google.com), go to **IAM & Admin → IAM**.
        2. Click **Grant access**.
        3. In **New principals**, paste the service account email from the Auxia wizard.
        4. In **Select a role**, choose **BigQuery Data Viewer**.
        5. Click **Save**.

        **Dataset-level access:**

        1. Go to **BigQuery** and select the dataset in the Explorer panel.

        2. Click **Sharing → Permissions**.

                   <Frame caption="Open the dataset's sharing permissions">
                     <img src="https://mintcdn.com/auxia/XsfpA_ObWj7oESRX/img/data-ingestion/bigquery-3.png?fit=max&auto=format&n=XsfpA_ObWj7oESRX&q=85&s=583f4f67e6f31b2ac2f79ad968b9de6f" alt="BigQuery dataset Sharing menu with Permissions highlighted" width="602" height="374" data-path="img/data-ingestion/bigquery-3.png" />
                   </Frame>

        3. Click **Add principal**.

                   <Frame caption="Add the Auxia service account as a principal">
                     <img src="https://mintcdn.com/auxia/XsfpA_ObWj7oESRX/img/data-ingestion/bigquery-4.png?fit=max&auto=format&n=XsfpA_ObWj7oESRX&q=85&s=5e5c4bc43be7c2f5a2cf056c109804b5" alt="Dataset permissions panel with the Add Principal button" width="572" height="137" data-path="img/data-ingestion/bigquery-4.png" />
                   </Frame>

        4. Paste the service account email, choose the **BigQuery Data Viewer** role, and click **Save**.

        5. Repeat for each dataset.
      </Tab>

      <Tab title="Cloud Shell">
        No local `gcloud` install? Use [Google Cloud Shell](https://shell.cloud.google.com) in your browser — the `bq` tool is included.

        1. Open Cloud Shell.
        2. Select your project: `gcloud config set project YOUR_PROJECT_ID`
        3. Run the commands from the **Command line** tab.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Validate the connection">
    Back in the wizard, click **Validate / Test Connection**. Auxia runs four checks and shows each as it completes:

    1. Verify BigQuery access permissions
    2. Explore datasets and tables
    3. Validate table format and structure
    4. Analyze schemas for field mapping

    <Note>
      **IAM changes take 2–5 minutes to propagate.** If validation fails right after you grant access, wait and retry — don't re-grant.
    </Note>

    If some datasets fail (for example, *Access denied* or *Dataset not found*), the wizard reports *"Connection failed for N datasets"* and lists each with the reason and a ready-to-run grant command. Run it, wait 2–3 minutes, and retry — or continue with the datasets that connected.
  </Step>

  <Step title="Choose what to sync">
    Every table Auxia discovered is listed with its checks: partition column, append support, size, table type, and **Sample Rows** to preview.

    | Status | Meaning |
    | - | - |
    | **Ready** | Passes all checks |
    | **Warning** | Can be synced, with a caveat shown on the row |
    | **Blocked** / **Not supported** | Must be fixed in BigQuery first — the row explains how |

    Select the tables to carry forward.
  </Step>

  <Step title="Map Primary User ID">
    Pick the column that is most consistently present and unique across your data — the same `userId` you pass to the [Get Treatments](/api-reference/get-treatments) API. Auxia's agent scans your selected tables, proposes a candidate, and shows its coverage.

    Tables are sorted into groups:

    | Group | What to do |
    | - | - |
    | **Confirmed Mappings** | Nothing — uses the chosen column |
    | **Confirm These Mappings** | Same values under a different column name. Approve or skip |
    | **Excluded tables** | No matching column, or skipped. Approve another column, or add a join |
    | **Mapped via join** | Review the join and its **Mapping Preview** |
    | **Join Tables** | Supply a value used to resolve another table's user ID. They don't need a user ID of their own |

    **Resolving an ID with a join.** If a table has no usable user ID — device or session events, for example — join it to a table that has one, such as a user-mapping table. Choose the key columns on each side, then under **Resolves Auxia user\_id from**, the column whose values become the user ID. Joins can chain through up to five tables (**Hop 1**, **Hop 2**, …). Use an **INNER** join for ID resolution; key columns must have the same data type.

    A mapping table's timestamp usually records when the mapping was made, not when an event happened — don't map it as an event timestamp.

    See [Understanding the primary user ID](/data-ingestion/concepts/map-your-data#understanding-the-primary-user-id) for how to choose well.
  </Step>

  <Step title="Match Fields to Auxia Schema">
    For each table, review the role Auxia's agent assigned to every column — user ID, event name, event timestamp, event property, user attribute, and so on — and correct anything that's wrong. Unchecked columns are skipped. When you correct one column, the agent offers to apply the same change to similar fields in other tables.

    The wizard enforces the minimum mapping for each table type (for example, event tables need an event name and an event timestamp). If every row in a table is the same event, type an event name and Auxia applies it to all rows.

    Use the two previews to check your work:

    * **Source preview** — raw sample rows with your column names
    * **Unified preview** — a sample of the output in Auxia's schema, with mapping and joins applied

    **Pipeline choice.** By default each table is copied in *and* mapped (**Transfer + transform**). Choose **Transfer only** to land a table without mapping it — useful when the mapping needs custom logic that will be added later — or **Transform from source** to map a table that's already in Auxia into a second output. Tables mapped through a join don't offer this choice, because the join lives in the mapping.

    Full reference: [Map your data](/data-ingestion/concepts/map-your-data).
  </Step>

  <Step title="Add filters (optional)">
    Leave out rows you don't want ingested. Build conditions on any column — text, number, date, and boolean operators — and group them with **AND** / **OR**. The summary always reads *"Leaves out rows where …"* so the direction is never ambiguous.

    Filters apply to new syncs and backfills. Adding a filter never removes rows already in Auxia.
  </Step>

  <Step title="View the sync schedule">
    The schedule step shows each table's **Ingestion Schedule** (hourly, daily, or weekly) and region. Auxia sets the schedule from each table's shape — there's nothing to set here.
  </Step>

  <Step title="Review & Submit">
    Check the GCP project, datasets, primary user ID, and **Tables to Ingest** — each table's dataset, type, schedule, and **Pipeline**. Then choose:

    * **Enable Ingestion** — creates one configuration per table and switches ingestion on. The first sync starts within 1–2 minutes, and you're taken to **Import Configurations**.
    * **Enable Later** — creates the configurations switched off (**Dormant**). Enable them later from **Configuration → Connections → Import Configurations**.

    Data appears in Auxia once the initial sync completes. [Monitoring with Data Health →](/data-ingestion/concepts/monitoring)
  </Step>
</Steps>

## Related articles

* [Google BigQuery overview](/data-ingestion/data-connections/google-bigquery)
* [Troubleshooting BigQuery](/data-ingestion/data-connections/google-bigquery/troubleshooting)
* [What data is needed](/data-ingestion/what-data-is-needed)
* [Map your data](/data-ingestion/concepts/map-your-data)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.