> ## 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 warehouse available in Interact today. Other warehouses are coming soon. Once connected, assign this connector on a Data Analyst agent and select the semantic models it may use.

**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

**1. Open Google Cloud IAM**

Go to [console.cloud.google.com](https://console.cloud.google.com) and navigate to **IAM & Admin** → **Service Accounts**.

**2. Create a new service account**

Click **Create Service Account**, give it a name (e.g. `interact-reader`), and click **Create and Continue**.

**3. 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**.

**4. 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.

## Step 2: Connect BigQuery in Interact

**1. Open Connectors**

In Interact, go to **Settings** → **Connectors** and click **Add connector**.

**2. Select Google BigQuery**

Choose **Google BigQuery** from the list of available connectors.

**3. Enter your project ID**

Type in your **Google Cloud Project ID** (visible in the Google Cloud Console header).

**4. 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.

**5. 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.

**6. Set a max billable MBs per query (optional but recommended)**

Enter the maximum billable data volume per query in **MB** (default **1000 MB** ≈ 1 GB). Interact passes this to BigQuery as `maximumBytesBilled`. Queries that would scan more than the limit are rejected, which protects you from unbounded warehouse scans. This is separate from Interact’s [LLM cost caps](https://docs.getinteract.com/security/overview.md#llm-cost-caps) at organisation, group, and user level.

**7. Save the connector**

Click **Save connector**. Interact will verify the connection using your credentials.

## Step 3: Attach the connector to an agent

Once the connector is saved, assign it on a Data Analyst agent:

1. Open an agent (or create a new one)
2. Go to the **Data Access** tab
3. Set **Warehouse connection** to this BigQuery connector
4. Select the **semantic models** the agent may use (queries are limited to those models’ source tables)

You can create additional connectors with different service accounts when agents need different IAM scopes. [Data Access →](https://docs.getinteract.com/agents/settings/data-access.md)

## 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.

## Troubleshooting

> [accordion] Connection verification fails
>
> 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] Agent says it can't find a 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] Query was blocked due to the max billable MBs limit
>
> The query the agent generated would scan more data than the connector’s max billable MBs setting. You can either:
>
> * Raise the max billable MBs in the connector settings
> * Ask the agent to query a smaller date range or fewer columns

> [accordion] Permission denied error
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.