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

# BigQuery

> Connect your BigQuery data warehouse to Modus for automatic cataloging and AI-powered visibility into your data landscape.

Modus connects to your Google BigQuery data warehouse to automatically catalog your
datasets, tables, and views — giving your team instant, AI-powered visibility into
your data landscape.

## Prerequisites

Before you begin, make sure you have:

* A **Google Cloud Platform** account with access to BigQuery.
* A **GCP Project** containing the BigQuery datasets you want Modus to catalog.
* Sufficient IAM permissions to create service accounts and assign roles in that project.

## How It Works

### 1. Connect your BigQuery project

You connect Modus to BigQuery using one of two secure authentication methods:

* **Service Account Key** — Provide a GCP service account JSON key with access to your BigQuery project.
* **Workload Identity Federation** — A keyless, more secure option that federates authentication between AWS and GCP without exchanging long-lived credentials.

<Note>
  Your credentials are encrypted and stored in AWS Secrets Manager.
</Note>

### 2. Select your datasets

After connecting, Modus lists all available datasets in your BigQuery project.
You choose which datasets you want Modus to analyze — nothing is scanned without
your explicit selection.

## GCP Permissions

Before connecting, grant your service account the required roles.
The roles depend on your chosen authentication method.

<Tabs>
  <Tab title="Service Account Key">
    Choose a permission set based on the level of access you want Modus to have:

    <Tabs>
      <Tab title="Read / Write">
        For workflows that need to create or modify tables (e.g. materializing results):

        | Role                         | Purpose                                      |
        | ---------------------------- | -------------------------------------------- |
        | **BigQuery Data Editor**     | Read, create, update, and delete table data  |
        | **BigQuery Resource Viewer** | View metadata for datasets, tables, and jobs |
      </Tab>

      <Tab title="Read Only">
        For cataloging and analysis with no write access:

        | Role                         | Purpose                                      |
        | ---------------------------- | -------------------------------------------- |
        | **BigQuery Data Viewer**     | Read-only access to table and view data      |
        | **BigQuery Job User**        | Permission to execute queries                |
        | **BigQuery Resource Viewer** | View metadata for datasets, tables, and jobs |
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Workload Identity Federation">
    Assign the following read-only roles to your service account:

    | Role                         | Purpose                                      |
    | ---------------------------- | -------------------------------------------- |
    | **BigQuery Data Viewer**     | Read-only access to table and view data      |
    | **BigQuery Job User**        | Permission to execute queries                |
    | **BigQuery Resource Viewer** | View metadata for datasets, tables, and jobs |
  </Tab>
</Tabs>

## GCP Setup

Choose your authentication method and follow the corresponding guide.

<Tabs>
  <Tab title="Service Account Key">
    <Steps>
      <Step title="Create a service account">
        1. Open the [Google Cloud Console](https://console.cloud.google.com) and select your project.
        2. Go to **IAM & Admin > Service Accounts**.
        3. Click **+ Create Service Account**.
        4. Enter a descriptive name (e.g. `modus-integration`) and click **Create and Continue**.
      </Step>

      <Step title="Assign BigQuery roles">
        In the **Grant this service account access to project** step:

        1. Click the **Select a role** dropdown and add each role from the [permissions table above](#gcp-permissions).
        2. Click **+ Add Another Role** to add additional roles as needed.
        3. Click **Continue**, then **Done**.
      </Step>

      <Step title="Generate and download a JSON key">
        1. In the **Service Accounts** list, find the account you just created.
        2. Click the service account name to open its detail page.
        3. Go to the **Keys** tab.
        4. Click **Add Key > Create new key**.
        5. Select **JSON** as the key type and click **Create**.
        6. A `.json` file will download automatically — store it securely. You will paste its contents into Modus in a later step.

        <Warning>
          Treat this key file like a password. Do not commit it to version control
          or share it in plaintext.
        </Warning>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Workload Identity Federation">
    Workload Identity Federation (WIF) lets Modus access your BigQuery project
    without long-lived service account keys. Instead, Modus authenticates from
    AWS and GCP verifies the identity through a trust relationship — no secrets
    are exchanged.

    <Steps>
      <Step title="Create a service account and assign roles">
        1. Open the [Google Cloud Console](https://console.cloud.google.com) and select your project.
        2. Go to **IAM & Admin > Service Accounts**.
        3. Click **+ Create Service Account**.
        4. Enter a name (e.g. `modus-tenant-sa`) and an optional description.
        5. Click **Create and Continue**.
        6. In the **Grant this service account access to project** step, add the following roles:

        | Role                         | Purpose                                      |
        | ---------------------------- | -------------------------------------------- |
        | **BigQuery Data Viewer**     | Read-only access to table and view data      |
        | **BigQuery Job User**        | Permission to execute queries                |
        | **BigQuery Resource Viewer** | View metadata for datasets, tables, and jobs |

        7. Click **Continue**, then **Done**.

        <Frame>
          <img src="https://mintcdn.com/modus-c77f86cb/qfWKAqW6IUqBcTju/images/bigquery-integration/wif-service-account-roles.png?fit=max&auto=format&n=qfWKAqW6IUqBcTju&q=85&s=3affa19bcba5fc001876172ba92e4ada" alt="Service account roles — BigQuery Data Viewer, BigQuery Job User, BigQuery Resource Viewer" width="1024" height="939" data-path="images/bigquery-integration/wif-service-account-roles.png" />
        </Frame>
      </Step>

      <Step title="Grant Modus permission to impersonate the service account">
        This step authorizes Modus to act as your service account via WIF.

        1. In **IAM & Admin > Service Accounts**, click the service account you just created.
        2. Go to the **Permissions** tab.
        3. Click **Grant Access**.
        4. In the **New principals** field, paste one of the following principals:

        **Recommended — scoped to Modus's AWS account:**

        ```
        principalSet://iam.googleapis.com/projects/858295161418/locations/global/workloadIdentityPools/modus-aws-pool/attribute.aws_account/887678038232
        ```

        **Alternative — all identities in the Modus WIF pool:**

        ```
        principalSet://iam.googleapis.com/projects/858295161418/locations/global/workloadIdentityPools/modus-aws-pool/*
        ```

        Use the scoped principal when your security policy requires limiting impersonation
        to Modus's AWS account rather than the entire pool. Contact Modus if you need
        the AWS account ID for your environment.

        5. In the **Select a role** dropdown, search for and select **Workload Identity User** (`roles/iam.workloadIdentityUser`).
        6. Click **Save**.

        <Frame>
          <img src="https://mintcdn.com/modus-c77f86cb/qfWKAqW6IUqBcTju/images/bigquery-integration/wif-principal-access.png?fit=max&auto=format&n=qfWKAqW6IUqBcTju&q=85&s=99320d327ef7307b07e4a163266f3f22" alt="Grant Modus principal access to impersonate the service account" width="703" height="1024" data-path="images/bigquery-integration/wif-principal-access.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Connect in Modus

<Steps>
  <Step title="Open the Integrations page">
    1. Log into [Modus](https://app.getmodus.com).
    2. Click **Integrations** in the left sidebar, then select **BigQuery**.
    3. Click **+ New Connection**.
  </Step>

  <Step title="Fill in connection details">
    Enter a **Connection Name** and your **Project ID** (your Google Cloud project identifier).
    Then choose an **Authentication Method**.

    <Tabs>
      <Tab title="Service Account Key">
        Select **Service Account Key** from the Authentication Method dropdown.

        Open the JSON key file you downloaded from GCP in a text editor, copy
        its entire contents, and paste it into the **Service Account Key** field.

        <Frame>
          <img src="https://mintcdn.com/modus-c77f86cb/qfWKAqW6IUqBcTju/images/bigquery-integration/service-account-key.png?fit=max&auto=format&n=qfWKAqW6IUqBcTju&q=85&s=ae00bdcb65c3cbb03770bf8be14b5707" alt="BigQuery connection form — Service Account Key" width="1688" height="939" data-path="images/bigquery-integration/service-account-key.png" />
        </Frame>

        <Warning>
          Treat the JSON key file like a password. Do not commit it to version
          control or share it in plaintext.
        </Warning>
      </Tab>

      <Tab title="Workload Identity Federation">
        Select **Workload Identity Federation** from the Authentication Method dropdown.

        Enter the **Service Account Email** of the GCP service account you
        configured for Modus access, and select the **Location** that matches
        your BigQuery datasets.

        <Frame>
          <img src="https://mintcdn.com/modus-c77f86cb/qfWKAqW6IUqBcTju/images/bigquery-integration/wif-modus-connection.png?fit=max&auto=format&n=qfWKAqW6IUqBcTju&q=85&s=85a03483c87c21cda3c5ada05ee2a2e1" alt="BigQuery connection form — Workload Identity Federation" width="1024" height="941" data-path="images/bigquery-integration/wif-modus-connection.png" />
        </Frame>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Test and save">
    1. Click **Test Connection** to verify Modus can reach your BigQuery project.
    2. Click **Save Connection**.
  </Step>

  <Step title="Select datasets">
    After saving, Modus will list all available datasets in your project.
    Select the datasets you want Modus to catalog and analyze, then confirm your selection.
  </Step>
</Steps>

## Connection form field reference

### Basic information

| Field               | Description                         | Example               |
| ------------------- | ----------------------------------- | --------------------- |
| **Connection Name** | A friendly name for this connection | `Production BigQuery` |

### Connection details

| Field          | Description                          | Example          |
| -------------- | ------------------------------------ | ---------------- |
| **Project ID** | Your Google Cloud project identifier | `my-gcp-project` |

### Authentication

Select your preferred **Authentication Method** from the dropdown.

<Tabs>
  <Tab title="Service Account Key">
    | Field                   | Description                                      | Example               |
    | ----------------------- | ------------------------------------------------ | --------------------- |
    | **Service Account Key** | Full contents of the downloaded `.json` key file | *(paste entire JSON)* |
  </Tab>

  <Tab title="Workload Identity Federation">
    | Field                     | Description                                        | Example                                           |
    | ------------------------- | -------------------------------------------------- | ------------------------------------------------- |
    | **Service Account Email** | The GCP service account email configured for Modus | `modus-tenant-sa@project.iam.gserviceaccount.com` |
    | **Location**              | BigQuery location for your datasets (default: US)  | `US (Multi-region)`                               |
  </Tab>
</Tabs>

## Verification

Your BigQuery project is now connected. Modus will begin cataloging the selected
datasets, tables, and views so that Modus can provide context-aware answers
about your data.

<Note>
  All credentials are encrypted and stored in AWS Secrets Manager. Modus only
  requests the minimum permissions needed to catalog and query your data.
  Workload Identity Federation is available as a keyless alternative that avoids
  long-lived credentials entirely.
</Note>