Google BigQuery

CARTO uses access credentials to connect to BigQuery in order to run queries on your behalf. You can use features of CARTO directly by using the BigQuery console through the CARTO Analytics Toolbox, or you can use the CARTO Workspace to launch different processes, like tileset generation.

There are two ways to set up a connection to Google BigQuery:

• Service Account: these are JSON credentials generated in Google Cloud Console, and are usually granted specific permissions to certain projects or datasets.

• Sign in with Google: connect your own Google account and use the Google BigQuery projects that you already have access to. This method is also called OAuth.

In both 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 pricing models, and more importantly, configure specific limits in BigQuery to avoid any unexpected charges.

When you select the BigQuery connector in the New connection dialog, you will see the following page:

Click the Connect using a service account button. You will see the form where you need to provide your connection parameters:

• Name for your connection: You can register different connections with the BigQuery connector. You can use the name to identify the different connections.

• Service account key file in JSON format. Please read the following instructions to create a service account and a service account key file. We will use this service account to list tilesets, visualize them privately, and grant publishing permissions. Be sure that the service account has BigQuery Data Editor (bigquery.dataEditor) and BigQuery User (bigquery.user).

• Billing project: having entered the previous parameters, a selector for choosing the billing project will be enabled, enabling CARTO to run queries using your service account.

To connect using “Sign in with Google” simply click the Sign in with Google button. This will open a Google login modal that will request the necessary scopes for CARTO to connect to your BigQuery. You can connect with your previous account or use a new one.

Once you have selected an account, a new dialog will appear allowing you to confirm that you trust CARTO and you give it necessary permissions. Click on Allow button to confirm and be authenticated directly using your google credentials or click Cancel if you don’t want to continue.

If you use “Sign in with Google” you might be asked to reconnect at any time, for example, after a few months or after changing your password. This is because this type of connection is linked to your Google account consent, which you can also revoke at any moment.

After allowing CARTO to access your Google Account, you will see the form where you need to provide your connection parameters:

• Name for your connection: You can register different connections with the BigQuery connector. You can use the name to identify the different connections.

• Billing project: having entered the previous parameters, a selector for choosing the billing project will be enabled, enabling CARTO to run queries using your service account.

Once you have entered the parameters, you can click the Connect button. CARTO will try to connect to your BigQuery server. If everything is OK, your new connection will be registered.

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

• Workflows temp. location: This setting controls the location (project.dataset) where Workflows will create temporal tables for each node. By default, it's a carto dataset that will be created in the connection's project during the execution of a workflow. Learn more about it here.

• Data Transfer Version Info: This setting is only necessary for Scheduling Workflows with 'Sign in with Google' connections. Learn about how to generate the code here.

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

IP Whitelisting

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 for your specific region.