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

# Connecting to BigQuery

> How to set up a connection to Google BigQuery to import data into Permutive

## Overview

This guide walks you through connecting your Google BigQuery data warehouse to Permutive so you can import data for audience building and activation. BigQuery is one of the simplest sources to connect — you just need to grant Permutive access to your dataset and provide your project and dataset details.

<Info>
  **Prerequisites:**

  * A Google Cloud Platform (GCP) account with BigQuery enabled
  * Access to manage IAM permissions on your BigQuery dataset
  * Knowledge of your GCP Project ID and Dataset name
</Info>

## Step 1: Grant Permutive Access to Your Dataset

Before creating the connection in Permutive, you need to grant read access to your BigQuery dataset.

<Steps>
  <Step title="Open Your BigQuery Dataset">
    In the Google Cloud Console, navigate to **BigQuery** and select the dataset you want to connect to Permutive.
  </Step>

  <Step title="Open Sharing Settings">
    Click on the dataset name, then click **Sharing** > **Permissions**.
  </Step>

  <Step title="Add Permutive Service Account">
    Click **Add Principal** and enter the following service account email:

    ```
    connection@permutive.com
    ```
  </Step>

  <Step title="Assign the Required Role">
    Assign the following role to the service account:

    * **BigQuery Data Viewer** (`roles/bigquery.dataViewer`)

    This grants Permutive read-only access to the tables within your dataset.
  </Step>

  <Step title="Save">
    Click **Save** to apply the permissions.
  </Step>
</Steps>

<Note>
  For more details on configuring BigQuery IAM roles, see [Google's documentation on BigQuery access control](https://cloud.google.com/bigquery/docs/access-control).
</Note>

## Step 2: Find Your Project ID and Dataset Name

You'll need two pieces of information from your GCP account:

### GCP Project ID

1. In the Google Cloud Console, click on the project dropdown at the top of the page
2. Your **Project ID** is displayed next to each project name
3. Alternatively, go to **IAM & Admin** > **Settings** to see the Project ID

### Dataset Name

1. In BigQuery, expand your project in the Explorer panel
2. The **Dataset Name** is shown directly under your project

<Warning>
  The Project ID and Dataset Name are case-sensitive. Ensure you enter them exactly as they appear in your GCP account.
</Warning>

## Step 3: Create the Connection in Permutive

<Steps>
  <Step title="Select BigQuery from the Catalog">
    In the Permutive dashboard, go to **Connectivity > Catalog** and select **Google BigQuery**. Click **Connect**.
  </Step>

  <Step title="Enter Connection Details">
    Fill in the following fields:

    | Field                | Description                                                                                                 |
    | :------------------- | :---------------------------------------------------------------------------------------------------------- |
    | **Name**             | A descriptive name for your connection in Permutive. This is for your reference only.                       |
    | **GCP Project ID**   | The Project ID from your GCP account (must match exactly)                                                   |
    | **GCP Dataset Name** | The Dataset name from your BigQuery account (must match exactly)                                            |
    | **Confirmation**     | Confirm that you've granted `connection@permutive.com` the `roles/bigquery.dataViewer` role on your dataset |
  </Step>

  <Step title="Save the Connection">
    Click **Save** to create the connection. It will appear on your **Connections** page with a "Processing" status while Permutive validates access to your dataset. Once validated, the status changes to "Active".
  </Step>
</Steps>

## Step 4: Create an Import

Once your connection is active, you can create imports to bring data into Permutive.

<Steps>
  <Step title="Navigate to Imports">
    Go to **Connectivity > Imports** and click **Create Import**.
  </Step>

  <Step title="Configure the Import">
    1. Select **Google BigQuery** as the source type
    2. Select your BigQuery connection
    3. Choose the table you want to import
    4. Continue with the standard import configuration
  </Step>
</Steps>

For more details on configuring imports, see [Imports](/products/connectivity/imports).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection fails to validate">
    If your connection remains in "Processing" status or fails:

    * Verify that `connection@permutive.com` has been granted the `roles/bigquery.dataViewer` role
    * Check that the Project ID and Dataset Name are entered exactly as they appear in GCP (case-sensitive)
    * Ensure the dataset exists and contains tables

    **Solution:** Double-check IAM permissions in the Google Cloud Console and verify your Project ID and Dataset Name.
  </Accordion>

  <Accordion title="Permission denied errors">
    If you receive permission errors after creating the connection:

    * The service account may not have been granted access correctly
    * The role may have been applied at the wrong level (project vs dataset)

    **Solution:** Ensure the `roles/bigquery.dataViewer` role is granted specifically on the dataset you're connecting to, not just at the project level.
  </Accordion>

  <Accordion title="Tables not appearing">
    If you don't see expected tables after creating the connection:

    * Verify the dataset contains tables (not just views, if views aren't supported)
    * Check that permissions are applied to the correct dataset

    **Solution:** Review your dataset in BigQuery to confirm tables exist and permissions are correctly configured. After updating permissions, run a schema resync in Permutive to refresh the available tables. To access the resync option, go to **Create Import**, enter an import name, select the source, and select the connection—the **Resync with source** button will then appear.
  </Accordion>

  <Accordion title="Wrong Project ID or Dataset Name">
    If you entered incorrect values:

    * You'll need to create a new connection with the correct values
    * The existing connection cannot be edited

    **Solution:** Create a new connection with the correct Project ID and Dataset Name.
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What permissions does Permutive need?">
    Permutive only requires read access to your data. The `roles/bigquery.dataViewer` role grants:

    * Read access to the dataset's metadata
    * Read access to all tables within the dataset

    Permutive cannot modify, delete, or write data to your BigQuery dataset.
  </Accordion>

  <Accordion title="Can I connect multiple datasets?">
    Yes, you can create separate connections for each dataset you want to import from. Each connection requires its own IAM configuration.
  </Accordion>

  <Accordion title="Can I connect to datasets in different projects?">
    Yes, you can create connections to datasets across multiple GCP projects. Ensure `connection@permutive.com` has the required permissions on each dataset.
  </Accordion>

  <Accordion title="What table types are supported?">
    Permutive supports standard BigQuery tables. Partitioned tables are also supported.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create an Import" icon="download" href="/products/connectivity/imports">
    Learn how to import data from your BigQuery connection
  </Card>

  <Card title="Back to Sources" icon="arrow-left" href="/products/connectivity/sources">
    Return to Sources overview
  </Card>
</CardGroup>