> ## 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 serves a core principal of granting access to raw data, enabling the creation of customized reporting solutions and fostering informed business decision-making.

<Note>
  Stigg's native integration with BigQuery is included in the Scale plan, and is also available as an optional add-on to the Growth plan. See Stigg's pricing for more details.
</Note>

## Exported entities

When connecting BigQuery, you can choose which Stigg entity groups to include in the sync. All groups are selected by default.

See [Exported entities](./overview#exported-entities) for the full list of entity groups and the tables within each.

* Products
* Plans
* Add-ons
* Features

2. Customers

3. Subscriptions

4. Usage data

   * Usage events (`USAGE_EVENT_<ENVIRONMENT_ID>`)
   * Credits usage (`CREDITS_USAGE_<ENVIRONMENT_ID>`)

<Note>
  Usage events and credits usage export originates from ClickHouse and must be enabled by Stigg support. Once enabled, the tables will appear in your BigQuery dataset alongside the standard Stigg tables.
</Note>

<Card title="Stigg entity schema" icon="sitemap" href="./schema" horizontal />

## Setting up the integration

### Prerequisites

* [A Google Cloud project with BigQuery enabled](https://cloud.google.com/bigquery/docs/quickstarts/query-public-dataset-console).
* [A BigQuery dataset](https://cloud.google.com/bigquery/docs/quickstarts/query-public-dataset-console#create_a_dataset) to sync data to.
* A Google Cloud [Service Account](https://cloud.google.com/iam/docs/service-account-overview) with the [BigQuery User](https://cloud.google.com/bigquery/docs/access-control#bigquery), [BigQuery Data Editor](https://cloud.google.com/bigquery/docs/access-control#bigquery) and [Storage Object Admin](https://cloud.google.com/storage/docs/access-control/iam-roles#standard-roles) roles and the [Service Account Key in JSON format](https://cloud.google.com/iam/docs/creating-managing-service-account-keys).
* If `BigQuery User` is granted at the dataset level, `BigQuery Job User` must also be granted at the project level to allow users to run queries.

### Setup Google Cloud Storage bucket

<Steps>
  <Step title="Create a Cloud Storage bucket">
    [Create a Cloud Storage bucket](https://cloud.google.com/storage/docs/creating-buckets) with the Protection Tools set to none or Object versioning. Make sure the bucket does not have a [retention policy](https://cloud.google.com/storage/docs/samples/storage-set-retention-policy).
  </Step>

  <Step title="Create an HMAC key">
    [Create an HMAC key and access ID](https://cloud.google.com/storage/docs/authentication/managing-hmackeys#create).
  </Step>

  <Step title="Grant the Storage Object Admin role">
    Make sure the [Storage Object Admin role](https://cloud.google.com/storage/docs/access-control/iam-roles#standard-roles) is granted to the Google Cloud [Service Account](https://cloud.google.com/iam/docs/service-accounts). This must be the same service account as the one you configure for BigQuery access.
  </Step>
</Steps>

Your bucket must be encrypted using a Google-managed encryption key (this is the default setting when creating a new bucket).

Bucket encryption using customer-managed encryption keys (CMEK) is not currently supported.

You can view this setting under the **Configuration** tab of your GCS bucket, in the Encryption type row.

### Connect Stigg with BigQuery

<Steps>
  <Step title="Open the BigQuery integration">
    In the [Stigg app](https://app.stigg.io/), navigate to **Integrations → Apps → BigQuery**.
  </Step>

  <Step title="Enter configuration values">
    Provide the following details in the opened form:

    | Field                                                                                                        | Description                                                                       |
    | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
    | [HMAC Key Access ID](https://cloud.google.com/storage/docs/authentication/managing-hmackeys#create)          | The HMAC key access ID used to access the GCS bucket                              |
    | [HMAC Key Secret](https://cloud.google.com/storage/docs/authentication/managing-hmackeys#create)             | The HMAC key secret used to access the GCS bucket                                 |
    | GCS Bucket Name                                                                                              | The name of the GCS bucket that will be used in the integration                   |
    | GCS Bucket Path                                                                                              | The directory path in the GCS bucket where data will be written                   |
    | [Project ID](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) | The GCP project ID containing the target BigQuery dataset                         |
    | Dataset location                                                                                             | The location of your BigQuery dataset                                             |
    | [Dataset ID](https://cloud.google.com/bigquery/docs/datasets#create-dataset)                                 | The default BigQuery Dataset ID used when the source does not specify a namespace |
    | [Service Account Key JSON](https://cloud.google.com/iam/docs/creating-managing-service-account-keys)         | The Google Cloud Service Account Key in JSON format                               |
  </Step>

  <Step title="Select entities to export">
    After entering your connection details, 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.
  </Step>

  <Step title="Connect">
    Click **Connect to BigQuery** to complete the setup.
  </Step>
</Steps>

## Sync process and schedule

After setup, Stigg performs a full sync of all selected entities. Subsequent syncs are incremental, transferring only changes since the last run.

Stigg syncs data to BigQuery daily at 12:00 AM UTC by default. You can configure a custom sync frequency during setup or from the BigQuery integration settings afterward.

## Manual sync

To trigger an immediate sync, open the BigQuery integration in [Stigg](https://app.stigg.io/) and click **Sync now**.

## Sync history

The BigQuery integration page shows a log of all past and in-progress syncs, including status, start and end timestamps, and error details for failed runs. Use the status and date filters to find a specific sync.

## Removing the integration

<Steps>
  <Step title="Remove the integration">
    Click the dotted menu icon and select **Remove**.
  </Step>

  <Step title="Confirm removal">
    In the opened modal, confirm the action by clicking **Remove**.
  </Step>
</Steps>