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

# Google BigQuery

> Connect your Google BigQuery project to Interact using a service account for secure, read-only access.

## Overview

Google BigQuery is the primary data source supported by Interact. Once connected, your agents can query any BigQuery table in the datasets you choose to expose.

**What you'll need:**

* A Google Cloud project with BigQuery enabled
* A service account with the correct IAM roles (detailed below)
* The service account's JSON key file

## Step 1: Create a service account

<Steps>
  <Step title="Open Google Cloud IAM">
    Go to [console.cloud.google.com](https://console.cloud.google.com) and navigate to **IAM & Admin** → **Service Accounts**.
  </Step>

  <Step title="Create a new service account">
    Click **Create Service Account**, give it a name (e.g. `interact-reader`), and click **Create and Continue**.
  </Step>

  <Step title="Assign the required roles">
    Add the following two roles:

    | Role                   | Purpose                   |
    | ---------------------- | ------------------------- |
    | `BigQuery Data Viewer` | Allows reading table data |
    | `BigQuery Job User`    | Allows running query jobs |

    Click **Continue**, then **Done**.
  </Step>

  <Step title="Create and download a JSON key">
    Click on your new service account, go to the **Keys** tab, click **Add Key** → **Create new key**, and choose **JSON**. Save the downloaded file — you'll need it in the next step.

    <Warning>
      Treat this JSON file like a password. Don't share it or commit it to version control.
    </Warning>
  </Step>
</Steps>

## Step 2: Connect BigQuery in Interact

<Steps>
  <Step title="Open Connectors">
    In Interact, go to **Settings** → **Connectors** and click **Add connector**.
  </Step>

  <Step title="Select Google BigQuery">
    Choose **Google BigQuery** from the list of available connectors.
  </Step>

  <Step title="Enter your project ID">
    Type in your **Google Cloud Project ID** (visible in the Google Cloud Console header).
  </Step>

  <Step title="Paste your service account credentials">
    Open the JSON key file you downloaded, copy the full contents, and paste it into the **Service account credentials** field.
  </Step>

  <Step title="Select datasets to expose">
    Interact will connect to BigQuery and list all available datasets in your project. Select the datasets you want your agents to be able to query.

    <Tip>
      You can also expand a dataset and select specific tables. This is useful if a dataset contains sensitive tables you don't want agents to access.
    </Tip>
  </Step>

  <Step title="Set a query cost limit (optional but recommended)">
    Enter a maximum cost per query in **USD**. Interact will estimate each query's cost before running it and block any query that would exceed this limit, protecting you from unexpected BigQuery charges.
  </Step>

  <Step title="Save the connector">
    Click **Save connector**. Interact will verify the connection using your credentials.
  </Step>
</Steps>

## Step 3: Attach the connector to an agent

Once the connector is saved, you can use it in any agent:

1. Open an agent (or create a new one)
2. In the **Subagents** section, add or edit a **Database Query Agent**
3. Select your BigQuery connector from the dropdown

The agent can now query the datasets you've whitelisted.

## Permissions reference

| IAM Role                    | Why it's needed                         |
| --------------------------- | --------------------------------------- |
| `roles/bigquery.dataViewer` | Read access to table data               |
| `roles/bigquery.jobUser`    | Permission to create and run query jobs |

<Note>
  You do not need `bigquery.dataEditor`, `bigquery.admin`, or any write-level permission. Interact is read-only.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection verification fails" icon="triangle-exclamation">
    Double-check that:

    * The Project ID is correct (no typos, no spaces)
    * The service account has both `BigQuery Data Viewer` and `BigQuery Job User` roles
    * The JSON key file is complete and unmodified
  </Accordion>

  <Accordion title="Agent says it can't find a table" icon="table">
    The table's dataset may not be whitelisted. Go to **Settings** → **Connectors**, edit the connector, and check that the relevant dataset (or table) is selected.
  </Accordion>

  <Accordion title="Query was blocked due to cost limit" icon="gauge">
    The query the agent generated exceeded your configured cost limit. You can either:

    * Raise the cost limit in the connector settings
    * Ask the agent to query a smaller date range or fewer columns
  </Accordion>

  <Accordion title="Permission denied error" icon="lock">
    Ensure the service account has been granted roles **at the project level**, or alternatively at the specific dataset level for each dataset you want to expose.
  </Accordion>
</AccordionGroup>