Connections

About connections

When developing with CARTO, all queries and requests from your application are pushed down to your own Data Warehouse (or the default one provided by CARTO), achieving three main benefits:

• Unparalleled scalability and performance with large geospatial datasets

• No need to create and manage ETLs; Data stays in your database.

• Respect the governance and policies in your Data Warehouse

In order to run those queries we need a secure set of credentials, which is what we call Connections.

Inside a Connection

A connection is an object stored and managed by CARTO that contains all the necessary information to run queries in your Data Warehouse. Each connection is typically composed of these attributes:

• name: The name that will identify the connection in code and in the UI.

• provider: The Data Warehouse provider — e.g., "Snowflake" or "BigQuery"

• config: A set of items that define the connection, including but not limited to:

  • type: The authentication method used for this connection — e.g., "service_account"

  • credentials: The actual credentials (including the secrets) being used to authenticate the request to the Data Warehouse. This varies for each provider and type. For example, in Snowflake you will be required to indicate an account, a username, a database and a warehouse, and other optional fields such as the role.

• privacy: Connections can be private or shared with the organization or specific user groups. The connections that a given user can use are defined by this attribute. Read more about sharing connections.

There are more attributes but these above are the most important ones.

This is an example of a Snowflake connection, in JSON syntax.

{
    "name": "example_snowflake_connection",
    "provider_id": "snowflake",
    "config": {
        "type": "snowflake_account",
        "credentials": {
            "username": "YOUR_SNOWFLAKE_USERNAME",
            "password": "XXX",
            "account": "your-snowflake-account.us-east-1",
            "database": "YOUR_SNOWFLAKE_DATABASE",
            "warehouse": "YOUR_SNOWFLAKE_WAREHOUSE"
        }
    },
    "privacy": "private"
}

Creating and managing Connections

Connections are created and managed in the CARTO Workspace, under its own section. Follow this documentation to learn how to create Connections.

Connections can be managed programmatically using the Connections API, although we consider it an advanced strategy and don't recommend it for most cases.

Using connections in your apps

When developing with CARTO, all queries that reach the Data Warehouse must always use a specific Connection. When using data sources, the connection name will be a parameter of the data source.

import {vectorTableSource} from '@deck.gl/carto';
const data = vectorTableSource({
  accessToken: 'XXX',
  connectionName: 'carto_dw', // the name of your connection
  tableName: 'carto-demo-data.demo_tables.chicago_crime_sample'
});

When using APIs like the SQL API directly, this is defined using the path of the request:

https://api_base_url/v3/sql/:connection/query?q=select * from carto-demo-data.demo_tables.airports

Since Connections are tied to specific credentials, they are a good way to restrict access to the data. You could create specific credentials in your Data Warehouse and leverage them as a first security control for your app.

Remember that connections can be private, shared with specific groups, or shared with all users in the organization. If your app leverages the CARTO login, consider using the connection privacy as a building block for granular security.