# Google BigQuery

CARTO can connect to your BigQuery Data Warehouse, allowing you to use your data for building Maps, Workflows and custom applications. There are three ways to set up a connection to Google BigQuery.

**Recommended methods:**

* [**Sign in with Google**](#using-oauth-2.0): Connect your own Google account and use all the Google BigQuery permissions that you have access to, with the possibility of enforcing viewer credentials. This method is ideal if you want to use in CARTO exactly the same permissions that you have in your BigQuery console. This method is also called **OAuth 2.0.**
* [**Workload Identity Federation**](#using-workload-identity-federation): Leverage CARTO identities directly in Google Cloud Platform, with permissions being granted via IAM to a Workload Identity Pool, previously configured by your GCP administrators. This method is ideal if you want to use granular, restricted permissions exclusively for CARTO.

**Other methods**

* [**Service Account**](#using-a-service-account): These are a set of credentials (a key in JSON format) generated in Google Cloud, representing a set of permissions for a database or a project, not associated with an individual. This is likely a quicker and more flexible solution for testing, but the other methods represent a more secure strategy for production environments.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-10b347df1631c3708781ec2ccffdccf358753fea%2FScreenshot%202025-01-08%20at%2019.14.49.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}

* Please make sure that your credentials (regardless of the method used) have the necessary permissions for CARTO to run. For more information, see [Required BigQuery Permissions](#required-bigquery-permissions).
* In all methods you will need to indicate a **billing project**. All queries performed by CARTO will use the billing account associated with the selected billing project. We recommend you review the different BigQuery pricing models, and more importantly, configure specific limits in BigQuery to avoid any unexpected charges.
  {% endhint %}

{% hint style="info" %}
CARTO is a fully cloud-native platform that runs queries on your behalf to power maps, workflows, etc. We never create or maintain any copies of your data.

[What it means to be fully cloud native.](https://carto.com/blog/what-being-cloud-native-should-really-mean-spatial-data)
{% endhint %}

## Using OAuth 2.0

To connect CARTO and BigQuery using your Google account simply click the *Continue with Google* button. This will open a Google login flow that will request the necessary scopes for CARTO to connect to your BigQuery data.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-72f6dc11e6c0b9b7f7232cd43671665c40dc1104%2Fthe_connections_bq_oauth_second.png?alt=media&#x26;token=8f6b8695-c971-4965-b9c9-eaca6bfeb246" alt=""><figcaption></figcaption></figure>

After allowing CARTO to access your Google BigQuery data, you will see a form where you'll specify the remaining details for this connection:

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-b97c5ec27b5c205b02bc6fc25ef9b307febbfd13%2FScreenshot%202024-07-31%20at%2014.46.54.png?alt=media" alt=""><figcaption></figcaption></figure>

* **Name**: This will be the name used to identify this connection across CARTO. It needs to be unique and there are special format rules: 3-50 characters long, containing only lowercase letters and numbers. Dashes and underscores are allowed if they're not leading or trailing.
* **Billing project**: All queries performed by CARTO will run against this Google Cloud Platform project, and its associated billing account.

{% hint style="info" %}
When using OAuth-based connections (such as this "Continue with Google"), **you might be asked to reconnect at any time.** It could happen, for example, after a few months or after changing your password. The reason is that this type of connections are linked to your Google account consent to CARTO, which you can also revoke at any moment.
{% endhint %}

{% hint style="warning" %}
Please make sure your Google account has adequate permissions for CARTO, at least at the billing project level. Learn more at [**Required BigQuery Permissions**](#required-bigquery-permissions).
{% endhint %}

## Using Workload Identity Federation

CARTO can connect to BigQuery by leveraging [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation).

{% hint style="warning" %}
**Initial setup required**

To connect to BigQuery using this method, the organization admin must first set up a Workload Identity Federation integration in CARTO. Once this is done, it will be available to all users within the organization. [Read more about setting up a Workload Identity Federation for BigQuery integration](https://docs.carto.com/carto-user-manual/settings/advanced-settings/workload-identity-federation).
{% endhint %}

To use it in your connections (and after your administator has completed the integration) simply click on ***Connect with Workload Identity Federation*** in the connection method selection screen. A new connection form will appear, and you'll need to complete the setup for your connection.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-df81e10e87870aba2a5b740686b4c2aa2a30ae40%2FScreenshot%202025-01-08%20at%2019.16.02.png?alt=media" alt=""><figcaption></figcaption></figure>

* **Name**: This will be the name used to identify this connection across CARTO. It needs to be unique and there are special format rules: 3-50 characters long, containing only lowercase letters and numbers. Dashes and underscores are allowed if they're not leading or trailing.
* **IAM Principal:** this is the identity that this connection will use in Google Cloud. Use this IAM directly in Google Cloud to grant permissions to this connection.
  * **Service Account email for impersonation** (optional): if you want to impersonate a Service Account using this connection, enter the service account email here. This assumes the IAM Principal has permissions to impersonate the service account.
* **Billing project:** All queries performed by CARTO will run against this Google Cloud Platform project, and its associated billing account.

{% hint style="warning" %}
Please make sure that your Workload Identity Federation IAM Principal has adequate permissions in Google BigQuery for CARTO, at least at the billing project level. Learn more at [**Required BigQuery Permissions**](#required-bigquery-permissions). If you're not sure, check with the Google Cloud administrator in your organization that [integrated CARTO via Workload Identity Federation](https://docs.carto.com/carto-user-manual/settings/advanced-settings/workload-identity-federation).
{% endhint %}

## Using a Service Account

If you select **Connect using a Service Account,** you'll see a form where you'll specify the details for this connection:

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-415857235e39d43fd2a3c9dc22004fbb5db07686%2FScreenshot%202024-07-31%20at%2014.35.51.png?alt=media" alt=""><figcaption></figcaption></figure>

* **Name**: This will be the name used to identify this connection across CARTO. It needs to be unique and there are special format rules: 3-50 characters long, containing only lowercase letters and numbers. Dashes and underscores are allowed if they're not leading or trailing.
* **Service account key:** The credentials file in JSON format. Please read the following instructions to learn how to create a [service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts) and a service account [key file](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) in Google Cloud.
* **Billing project**: All queries performed by CARTO will run against this Google Cloud Platform project, and its associated billing account.

{% hint style="warning" %}
Please make sure the Service Account has adequate permissions for CARTO, at least at the billing project level. Learn more at [**Required BigQuery Permissions.**](#required-bigquery-permissions)
{% endhint %}

## Requiring Viewer Credentials

Connections to Google BigQuery using both OAuth and Workload Identity Federation can be set up to require viewer credentials. This means that when the connection is shared, other users trying to access it will have to provide their own credentials to use it, instead of using the credentials (token) of the user that created the connection.

For more information, see [Requiring viewing credentials for shared connections](https://docs.carto.com/carto-user-manual/sharing-a-connection#requiring-viewer-credentials-on-shared-connections).

{% hint style="success" %}
When you share Workload Identity Federation connections in "Requiring Viewer Credentials" mode, users will automatically use their own identity, and do not need to provide any additional information.
{% endhint %}

## Required BigQuery permissions

When creating the connection, CARTO will check that you have a minimum set of permissions that will allow the connection to operate with CARTO. These checks are performed at the [Billing-project level](#billing-project-level).

You can then **granularly specify a different set of permissions for each resource**. For example, the connection could have edit permissions in some tables but read-only in others. Please note that you can give limited and granular permissions to resources in completely different projects than the billing project. We call this [Resource level](#resource-level).

{% hint style="info" %}
For each area + resource combination, connection credentials must have at least the **“Minimum permissions”** to work. Some optional features may require additional permissions to work as expected.
{% endhint %}

{% hint style="success" %}
For the best experience in CARTO, we advise you to set up the “**Recommended role**”:

* `bigquery.dataEditor`
* `bigquery.user`
  {% endhint %}

### Billing-project level

CARTO requires the following permissions at the billing project to connect to BigQuery:

<table><thead><tr><th width="246">Where</th><th width="218">Recommended role</th><th>Minimum permissions required</th></tr></thead><tbody><tr><td><strong>Billing project</strong><br>(as specified in the connection)</td><td><p>bigquery.dataEditor</p><p>bigquery.user</p></td><td><p>bigquery.jobs.list</p><p>bigquery.jobs.create</p><p>resourcemanager.projects.get</p></td></tr></tbody></table>

### Resource level

CARTO requires the following permissions for each BigQuery resource in order to operate with those resources, such as projects, datasets, or tables.

<table><thead><tr><th width="248">Where</th><th width="220">Recommended role</th><th>Minimum permissions required</th></tr></thead><tbody><tr><td><strong>Listing projects, datasets and tables in CARTO</strong><br>(<a href="../data-explorer">Data Explorer</a>)</td><td><p>bigquery.dataEditor</p><p>bigquery.user</p></td><td><p>resourcemanager.projects.get</p><p>resourcemanager.projects.list<br>bigquery.tables.list</p></td></tr><tr><td><strong>Projects, datasets, and tables used for map visualization</strong><br>(<a href="../maps">Builder</a>)</td><td><p>bigquery.dataEditor</p><p>bigquery.user</p></td><td><p>bigquery.jobs.create</p><p>bigquery.tables.list</p></td></tr><tr><td><strong>Projects, datasets, and tables used for spatial analysis</strong><br>(<a href="../workflows">Workflows</a>)</td><td><p>bigquery.dataEditor</p><p>bigquery.user</p></td><td><p>bigquery.jobs.create</p><p>bigquery.jobs.list</p><p>bigquery.tables.list</p><p>bigquery.tables.create</p><p>bigquery.datasets.create</p><p>bigquery.datasets.get</p></td></tr><tr><td><strong>Projects, datasets, and tables used in custom applications</strong><br><strong>(</strong><a href="https://github.com/CartoDB/gitbook-documentation/blob/master/carto-user-manual/connections/broken-reference/README.md">CARTO for Developers</a><strong>)</strong></td><td><p>bigquery.dataEditor</p><p>bigquery.user</p></td><td>bigquery.jobs.create</td></tr></tbody></table>

{% hint style="info" %}
You can also check our (more generic) guide about [why CARTO requires each permission](https://docs.carto.com/carto-user-manual/connections/required-permissions), with examples on setting different connections for different teams.
{% endhint %}

## Advanced options

* **Analytics Toolbox location:** This setting controls the location of the Analytics Toolbox used in SQL queries generated by Workflows components, Builder SQL Analyses, 'Create Tileset', 'Geocode Table' and 'Enrich Data' functionalities.\
  By default, CARTO will automatically determine the corresponding AT Location based on the actual region of the data.
* **Data Observatory location:** This settings controls the location of the Data Observatory subscriptions. This setting will be observed by Data Explorer, Workflows and Enrichment to access your data subscriptions.\
  By default, a specific project for your account (created automatically and maintained by CARTO) will be used. For example `carto-data.ac_xxxxxxxx`
* **CARTO temp location**

  Location to store **temporary tables** used during workflow execution. These include intermediate tables with hashed names created by nodes in a workflow.\
  By default, CARTO uses a `carto_temp` dataset per connection. For connections shared requiring Viewer Credentials, a `carto_temp_<user>` dataset is created per user.\
  **Example:** `my_project.carto_temp`
* **CARTO Workspace location**

  Location to store **persistent objects** related to workflows, such as API stored procedures and imported files.\
  By default, CARTO uses a `carto_workspace` dataset per connection. For connections shared requiring Viewer Credentials, a `carto_workspace_<user>` dataset is created per user.\
  **Example:** `my_project.carto_workspace`
* **CARTO Extensions location**

  Location to store **Extension Package resources**, including shared stored procedures and metadata.\
  By default, this location matches the Workspace location unless explicitly overridden.\
  Important notes:

  * This location is shared across all users of the connection, even for connections shared requiring Viewer Credentials.
  * User-specific datasets like `carto_extensions_<user>` are **not** created, to ensure a single source of extensions per connection.

  **Example:** `my_project.carto_extensions`

{% hint style="info" %}
**About CARTO temp, Workspace and Extensions locations**

* CARTO uses `CREATE IF NOT EXISTS` to provision all datasets when needed.

* For accounts in the CARTO SaaS platform, these datasets will be created in the same GCP region as the region selected when creating the account.

* For accounts in CARTO Self-hosted deployments, these datasets are created in the `US` multiregion. If a different region is required, the datasets must be created from BigQuery before creating or updating the connection.

* For connections shared requiring Viewer Credentials:
  * User-specific datasets (`carto_temp_<user>`, `carto_workspace_<user>`) are created on demand. These are created in the same region as the dataset specified by the owner of the connection.
  * The Extensions location remains shared across all users of the connection.
    {% endhint %}

* **Data Transfer Version Info:** This setting is only necessary for [Scheduling Workflows](https://docs.carto.com/carto-user-manual/workflows/scheduling-workflows) with 'Sign in with Google' connections. Learn about how to generate the code [here](https://docs.carto.com/carto-user-manual/workflows/scheduling-workflows#data-transfer-version-info).

* **Max number of concurrent queries:** This setting controls the maximum number of simultaneous queries that CARTO will send to BigQuery using this connection.

* **Max query timeout:** This setting controls the maximum allowed duration of queries that CARTO runs in BigQuery using this connection.

* **Restrict this connection to only use Named Sources:** When this setting is enabled, this connection will only work within apps that use [Named Sources](https://docs.carto.com/carto-user-manual/developers/named-sources), and it will NOT work in Data Explorer, Builder and Workflows. This prevents the usage of arbitrary SQL in applications for this connection.

## IP Whitelisting <a href="#ip-whitelisting" id="ip-whitelisting"></a>

If you're using the cloud version of CARTO (SaaS), CARTO will connect to BigQuery using a set of static IPs for each region. [Check this guide to find the IPs you need to allow](https://docs.carto.com/carto-user-manual/connections/ip-whitelisting) for your specific region.