> For the complete documentation index, see [llms.txt](https://docs.telm.ai/telmai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telm.ai/telmai/connect-to-data/data-connections/google-bigquery.md).

# Google BigQuery

Connect Telmai to Google BigQuery.

Telmai reads tables and views from BigQuery datasets with a Google Cloud service account.

## Before you connect

Choose the service account Telmai uses:

* **Tenant service account**: Telmai's own service account, on GCP deployments only. To see it, start a Google BigQuery connection and select **Use tenant service account**. The form shows it next to **Using service account:**.
* **Your own service account**: create a [service account key](https://cloud.google.com/iam/docs/keys-create-delete) in JSON format.

On hybrid deployments, the account that reads your data is the service account in your hybrid agent, so grant the roles to that account.

Grant the service account these roles:

1. On each dataset Telmai reads: `BigQuery Data Viewer` (`roles/bigquery.dataViewer`) and `BigQuery Metadata Viewer` (`roles/bigquery.metadataViewer`). In the Google Cloud console, open the dataset and click **Sharing** > **Permissions** > **Add principal**. See [Grant access to a dataset](https://cloud.google.com/bigquery/docs/control-access-to-resources-iam#grant_access_to_a_dataset).
2. On the project where the queries run: `BigQuery Job User` (`roles/bigquery.jobUser`).

## Connection fields

On the **Connections** page, click **Add connection** and choose **Google BigQuery**. See [Add a connection](https://docs.telm.ai/telmai/connect-to-data.md#add-a-connection) for the full flow.

| Field                                                                                | Description                                                                                                             |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **Google project**                                                                   | The Google Cloud project that holds the datasets, for example `your-project`.                                           |
| **Use dataset project for job**                                                      | Optional, GCP deployments only. Runs BigQuery jobs in the dataset's project.                                            |
| **Use service account credentials** or **Use tenant service account**                | GCP deployments only. Choose whether Telmai signs in with your own service account or the tenant service account.       |
| **Client email**, **Client ID**, **Project ID**, **Private key ID**, **Private key** | Your own service account's details, from its JSON key. Click **Import credentials** to fill them in from the JSON file. |

On deployments outside GCP, there is no choice under **Credentials**: fill in your own service account's details.

## Asset fields

Click **Add assets** on the connection. See [Add assets](https://docs.telm.ai/telmai/connect-to-data.md#list-of-connectors-enabled-by-default).

| Field       | Description                                                      |
| ----------- | ---------------------------------------------------------------- |
| **Dataset** | The BigQuery dataset that holds the tables, for example `sales`. |

## Limitations

### Additional permissions for GCP VPC deployments

On a [GCP VPC deployment](https://docs.telm.ai/telmai/deployment-models/virtual-private-cloud-vpc-deployment.md), Telmai's scan job runs as the service account on the connection. With the tenant service account, there is nothing more to grant. With your own service account, the job also writes its results, so grant that account:

| What it needs to do           | Where to grant it                                | Role                                                 |
| ----------------------------- | ------------------------------------------------ | ---------------------------------------------------- |
| Write scan output and metrics | The Telmai tenant GCS bucket for your deployment | `Storage Object Admin` (`roles/storage.objectAdmin`) |
| Run scan jobs                 | The GCP project where Telmai runs the scan       | `BigQuery Job User` (`roles/bigquery.jobUser`)       |

Ask your Telmai deployment owner for the tenant GCS bucket name and the project the scan runs in.

{% hint style="warning" %}
Without these, **Test connection** passes but scans fail. The test only checks that Telmai can read your data; the write happens later, during the scan.
{% endhint %}
