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

# BigQuery Connection Guide

> Connect Delphina to BigQuery with a service account and the right IAM roles

Delphina connects to BigQuery using a **Google Cloud service account**. The service account needs IAM roles that let Delphina run jobs, read table data and metadata, and — optionally — read query history and masked columns.

## Connecting BigQuery

### Step 1: Create a service account

1. In the Google Cloud console, open **IAM & Admin > Service Accounts** for the project that owns your BigQuery data.
2. Click **Create Service Account** and give it a descriptive name (e.g., `delphina-warehouse`).
3. Skip the optional "Grant access to project" step — you'll grant roles in Step 2.
4. After creating the account, open it, go to **Keys**, and click **Add Key > Create new key > JSON**. Save the JSON file; you'll upload it to Delphina in Step 3.

### Step 2: Grant the service account IAM roles

The required roles depend on which features you want Delphina to use. The standard set below covers all of them and is the recommended starting point.

<Tabs>
  <Tab title="Standard set (recommended)">
    Grant the service account this combined set of roles. It covers data access, query history, and masked columns.

    | Role                                                                                                                                                  | Purpose                                         |
    | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
    | [`roles/bigquery.jobUser`](https://cloud.google.com/bigquery/docs/access-control#bigquery.jobUser)                                                    | Create query jobs                               |
    | [`roles/bigquery.dataViewer`](https://cloud.google.com/bigquery/docs/access-control#bigquery.dataViewer)                                              | Read table data                                 |
    | [`roles/bigquery.metadataViewer`](https://cloud.google.com/bigquery/docs/access-control#bigquery.metadataViewer)                                      | Read dataset/table metadata                     |
    | [`roles/bigquery.readSessionUser`](https://cloud.google.com/bigquery/docs/access-control#bigquery.readSessionUser)                                    | Read large result sets via the Storage Read API |
    | [`roles/bigquery.resourceViewer`](https://cloud.google.com/bigquery/docs/access-control#bigquery.resourceViewer)                                      | View reservations and slot assignments          |
    | [`roles/batch.jobsViewer`](https://docs.cloud.google.com/iam/docs/roles-permissions/batch#batch.jobsViewer)                                           | Read job execution metadata                     |
    | [`bigquerydatapolicy.maskedReader`](https://docs.cloud.google.com/bigquery/docs/column-data-masking-intro#roles_for_attaching_policy_tags_to_columns) | Read masked PII columns                         |

    Grant `dataViewer` and `metadataViewer` at the **dataset** level (or project level if you want Delphina to see everything). The remaining roles can be granted at the project level.
  </Tab>

  <Tab title="Minimal set (data access only)">
    If you don't need query history or masked-column access, you can use a narrower set.

    * A role containing `bigquery.jobs.create` at the project level so Delphina can create jobs. [`roles/bigquery.jobUser`](https://cloud.google.com/bigquery/docs/access-control#bigquery.jobUser) is the least-privileged predefined role with this permission, though it includes a few unused permissions.
    * [`roles/bigquery.metadataViewer`](https://cloud.google.com/bigquery/docs/access-control#bigquery.metadataViewer) on the datasets you want the agent to see.
    * [`roles/bigquery.dataViewer`](https://cloud.google.com/bigquery/docs/access-control#bigquery.dataViewer) on the tables Delphina should be able to query.

    Adding query history requires `roles/bigquery.readSessionUser`, `roles/bigquery.resourceViewer`, and `roles/batch.jobsViewer`. Reading masked PII columns requires `bigquerydatapolicy.maskedReader`.
  </Tab>
</Tabs>

### Step 3: Create the connection in Delphina

1. Navigate to [analytics.delphina.ai](https://analytics.delphina.ai/).

2. Click your name in the bottom-left, then **Org Admin > Warehouse Connections**.

3. Click **Add Connection** on the target workspace.

4. Set the **Warehouse Type** to **BigQuery**.

5. Paste the service account JSON. It should include the following fields:

   * `type`
   * `project_id`
   * `private_key_id`
   * `private_key`
   * `client_email`
   * `client_id`
   * `auth_uri`
   * `token_uri`
   * `auth_provider_x509_cert_url`
   * `client_x509_cert_url`
   * `universe_domain`

6. Click **Create Connection**, then **Test Connection** to verify Delphina can authenticate, list datasets, and read query history.

## Troubleshooting

| Problem                                 | Fix                                                                                                                     |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Test Connection fails**               | Verify the JSON key is valid and the service account exists. Re-download the key from Google Cloud if in doubt.         |
| **"Browse Tables" empty**               | Grant `bigquery.metadataViewer` on the datasets you want to expose to Delphina.                                         |
| **Queries fail with permission denied** | Add `bigquery.dataViewer` on the specific tables — `metadataViewer` lists tables but does not read them.                |
| **"Show Top Users" empty**              | Confirm `bigquery.readSessionUser`, `bigquery.resourceViewer`, and `batch.jobsViewer` are granted at the project level. |
| **Masked columns return `NULL`**        | Grant `bigquerydatapolicy.maskedReader` to the service account so it can read masked values.                            |