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

# BigQuery

## Overview

Stigg's integration with BigQuery allows you to export your product catalog, customer, and subscription data directly to your BigQuery project for custom reporting and analysis.

<Note>
  Stigg's native data export integrations are included in the Scale plan, and are also available as an optional add-on to the Growth plan. See Stigg's pricing for more details.
</Note>

<Card title="View the full entity schema" icon="sitemap" href="./schema">
  See every table and column exported to your destination, organized by entity group.
</Card>

## Setting up the integration

<Note>
  This guide describes the current connect flow. If your BigQuery connect form instead asks for an **HMAC Key Access ID**, **HMAC Key Secret**, and a **Service Account Key JSON** rather than an auth method and service account email, your account hasn't moved to this flow yet — [contact Stigg support](mailto:support@stigg.io) rather than following the steps below.
</Note>

### Prerequisites

* A Google Cloud project with **billing enabled**.
* Permission to create service accounts and edit IAM policies in that project (**Owner**, or **Service Account Admin** + **Project IAM Admin**).
* Access to the Stigg dashboard with permission to configure integrations.

<Note>
  The connect form offers three authentication methods. This guide covers **IAM Role**, the recommended one — you create a service account in your own Google Cloud project and grant Stigg's data-syncing account permission to impersonate it via short-lived tokens, so no key file or long-lived secret ever leaves your project. For **Key Auth** and **Federated OAuth**, see [Other authentication methods](#other-authentication-methods) below.
</Note>

<Steps>
  <Step title="Enable the required APIs">
    In **APIs & Services → Library**, enable:

    * **BigQuery API** (`bigquery.googleapis.com`)
    * **Cloud Storage API** (`storage.googleapis.com`)
    * **IAM Service Account Credentials API** (`iamcredentials.googleapis.com`)

    The third one is easy to miss and is required — it's what issues the short-lived tokens used for impersonation. Without it, the connection fails even when every role is correct.

    <CodeGroup>
      ```bash gcloud theme={null}
      gcloud services enable \
        bigquery.googleapis.com storage.googleapis.com iamcredentials.googleapis.com \
        --project=<PROJECT_ID>
      ```
    </CodeGroup>
  </Step>

  <Step title="Create the destination dataset">
    In **BigQuery → your project → Create dataset**, set a **Dataset ID** and pick a location — write it down, since the staging bucket in the next step must match it exactly.

    <CodeGroup>
      ```bash gcloud theme={null}
      bq --location=<LOCATION> mk --dataset <PROJECT_ID>:<DATASET>
      ```
    </CodeGroup>
  </Step>

  <Step title="Create the staging bucket">
    BigQuery has no built-in staging area, so data is first written to a Cloud Storage bucket and then bulk-loaded into BigQuery. Files are deleted after each transfer — nothing is retained.

    In **Cloud Storage → Buckets → Create**:

    * **Location type** must match the dataset location from the previous step. If the dataset is in the `US` multi-region, choose **Multi-region → us**.
    * **Enforce public access prevention** — leave enabled.
    * **Access control** — **Uniform**.

    <CodeGroup>
      ```bash gcloud theme={null}
      gcloud storage buckets create gs://<BUCKET> \
        --project=<PROJECT_ID> --location=<LOCATION> \
        --uniform-bucket-level-access --public-access-prevention
      ```
    </CodeGroup>

    <Warning>
      The bucket location can't be changed after creation. If it doesn't match the dataset, the connection may pass but transfers will fail on load, and the bucket has to be recreated.
    </Warning>

    <Note>
      The bucket must use a Google-managed encryption key (the default). Bucket encryption with customer-managed encryption keys (CMEK) isn't currently supported.
    </Note>
  </Step>

  <Step title="Create the destination service account and grant it access">
    This is the account that does the actual work inside your project. In **IAM & Admin → Service Accounts → Create service account**, name it something recognizable, e.g. `stigg-prequel`. Its email will be `stigg-prequel@<PROJECT_ID>.iam.gserviceaccount.com`.

    Don't create a key for it — keys aren't used by this method (the IAM Role method covered in this guide). Then grant it:

    | Role                    | Where it's granted | Why                                    |
    | ----------------------- | ------------------ | -------------------------------------- |
    | **BigQuery Job User**   | Project            | Run load jobs (`bigquery.jobs.create`) |
    | **BigQuery Data Owner** | Dataset            | Create and write the synced tables     |
    | **Storage Admin**       | Bucket             | Write and clean up staging files       |

    `BigQuery Job User` must be granted at the **project** level — the `bigquery.jobs.create` permission can't be granted on a dataset. Granting only dataset-level access is the most common cause of failure after impersonation itself.

    <CodeGroup>
      ```bash gcloud theme={null}
      gcloud iam service-accounts create stigg-prequel \
        --project=<PROJECT_ID> --display-name="Stigg data export"

      SA=stigg-prequel@<PROJECT_ID>.iam.gserviceaccount.com

      gcloud projects add-iam-policy-binding <PROJECT_ID> \
        --member="serviceAccount:$SA" --role="roles/bigquery.jobUser"

      gcloud storage buckets add-iam-policy-binding gs://<BUCKET> \
        --member="serviceAccount:$SA" --role="roles/storage.admin"
      ```
    </CodeGroup>

    For the dataset grant, use **BigQuery → your dataset → Sharing → Permissions → Add principal**, with the service account as principal and **BigQuery Data Owner** as the role.

    <Note>
      If you'd rather have Prequel create the dataset for you instead of pre-creating it, grant **BigQuery User** at the project level instead of **BigQuery Job User**.
    </Note>
  </Step>

  <Step title="Allow Stigg to impersonate the service account">
    This is the step the whole integration hinges on, and it's granted **on the service account**, not on the project.

    In **IAM & Admin → Service Accounts**, open the service account from the previous step, go to **Principals with access → Grant access**, and add Stigg's data-syncing account:

    ```
    datasync-bwvmhape@prql-prod.iam.gserviceaccount.com
    ```

    Grant it both:

    * **Service Account Token Creator**
    * **Service Account User**

    <CodeGroup>
      ```bash gcloud theme={null}
      SA=stigg-prequel@<PROJECT_ID>.iam.gserviceaccount.com
      DATASYNC=datasync-bwvmhape@prql-prod.iam.gserviceaccount.com

      gcloud iam service-accounts add-iam-policy-binding $SA --project=<PROJECT_ID> \
        --member="serviceAccount:$DATASYNC" --role="roles/iam.serviceAccountTokenCreator"

      gcloud iam service-accounts add-iam-policy-binding $SA --project=<PROJECT_ID> \
        --member="serviceAccount:$DATASYNC" --role="roles/iam.serviceAccountUser"
      ```
    </CodeGroup>

    <Warning>
      The most common mistake is granting these roles on the *project* instead of on the *service account itself* — these are two different screens in the Google Cloud Console, and a project-level grant silently does nothing for this integration. Verify with `gcloud iam service-accounts get-iam-policy $SA --project=<PROJECT_ID>` — the output must list both roles for the datasync account.
    </Warning>
  </Step>

  <Step title="Fill in the Stigg connect form">
    In [Stigg](https://app.stigg.io/), navigate to **Integrations → Apps → BigQuery** and provide:

    | Field                          | Description                                                                                                                                      |
    | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
    | Destination name               | Any name you like                                                                                                                                |
    | Auth method                    | **IAM Role**                                                                                                                                     |
    | Provider service account email | Read-only — Stigg's datasync account (`datasync-bwvmhape@prql-prod.iam.gserviceaccount.com`), the one you granted access to in the previous step |
    | Service account email          | The service account you created earlier, e.g. `stigg-prequel@<PROJECT_ID>.iam.gserviceaccount.com`                                               |
    | Project ID                     | Your GCP project ID                                                                                                                              |
    | Dataset                        | The dataset created earlier                                                                                                                      |
    | GCS bucket name                | The staging bucket name (no `gs://` prefix)                                                                                                      |
    | GCS bucket region              | The bucket's location in lowercase, e.g. `us`                                                                                                    |

    <Note>
      Don't confuse the two service-account fields: **Provider service account email** is Stigg's, while **Service account email** is the one you created for this integration. The staging bucket fields ask only for a name and a region — no access key or secret is required, since the bucket is accessed by the same impersonated service account.
    </Note>

    Click **Test & continue**. If the check passes, the integration is connected.
  </Step>

  <Step title="Choose entities to export">
    Expand the **Entities to export** section to choose which entity groups to include in the sync. All groups are selected by default.

    See [Exported entities](./overview#exported-entities) for a description of each group.

    Click **Connect** to complete the setup.
  </Step>
</Steps>

## Other authentication methods

The connect form's **Auth method** dropdown offers two further options besides **IAM Role**.

### Key Auth

Instead of impersonation, you hand over a service account key file. Use this only if your organization's policy rules out cross-project impersonation — it places a long-lived credential outside your project, which is why both Google and Prequel recommend against it.

The dataset, staging bucket, and service account setup above still apply, but you don't need to grant Stigg's account impersonation access. Instead, create a key for the service account:

1. In **IAM & Admin → Service Accounts**, open the service account and go to **Keys → Add key → Create new key**.
2. Choose key type **JSON** and create it. The file downloads once and can't be re-downloaded.

<CodeGroup>
  ```bash gcloud theme={null}
  gcloud iam service-accounts keys create key.json \
    --iam-account=<SERVICE_ACCOUNT_EMAIL> --project=<PROJECT_ID>
  ```
</CodeGroup>

Then fill in the connect form:

| Field                 | Description                                    |
| --------------------- | ---------------------------------------------- |
| Auth method           | **Key Auth**                                   |
| Service account email | The service account you created                |
| JSON Token            | The entire contents of the downloaded key file |

Project ID, dataset, bucket name and region are the same as for IAM Role.

Delete the local copy of the key file once it's submitted, and rotate the key periodically from **IAM & Admin → Service Accounts → Keys**.

### Federated OAuth

For customers who run Workload Identity Federation and want access to originate from their own identity provider rather than a Google-to-Google grant, BigQuery also supports connecting via **Federated OAuth**. Setup involves configuring a Workload Identity Federation pool in GCP and an OAuth client in your identity provider.

This method hasn't been run end-to-end by Stigg yet, so we're setting it up hands-on rather than publishing self-serve steps. [Contact Stigg support](mailto:support@stigg.io) to configure Federated OAuth for your BigQuery destination.


## Related topics

- [Exported entities](/documentation/importing-and-exporting-data/export/overview.md#exported-entities)
- [Sync process, schedule, manual sync, and sync history](/documentation/importing-and-exporting-data/export/overview.md#sync-process)