SQL Warehouse

Introduction

This guide contains the steps to perform a fully manual installation of the CARTO Analytics Toolbox for Databricks.

The CARTO Analytics Toolbox for Databricks is available for CARTO customers. Contact us to get an installation package.

Prerequisites

Before installing the Analytics Toolbox, ensure you have:

• Unity Catalog enabled in your Databricks workspace

• A SQL Warehouse provisioned in your workspace

• Appropriate permissions to create catalogs, schemas and functions:

GRANT CREATE CATALOG ON METASTORE TO `<principal>`;
GRANT CREATE MANAGED STORAGE ON EXTERNAL LOCATION `<location>` TO `<principal>`;
GRANT CREATE CONNECTION ON METASTORE TO `<principal>`;

Setup

This step consists of setting up the Databricks catalog and schema where the Analytics Toolbox will be installed.

Creating the catalog and schema

The Analytics Toolbox functions will be installed in a dedicated catalog and schema within your Unity Catalog. Run the following SQL in your SQL Warehouse:

-- Create the carto catalog
CREATE CATALOG IF NOT EXISTS carto MANAGED LOCATION '<location>';

-- Create the carto schema
CREATE SCHEMA IF NOT EXISTS carto.carto;

-- Grant all privileges on the schema to a sysadmin role
GRANT ALL PRIVILEGES ON SCHEMA carto.carto TO `<principal-sysadmin>`;

-- Grant usage on the catalog and schema to a specific role/group
GRANT USAGE ON CATALOG carto TO `<principal-public>`;
GRANT USAGE ON SCHEMA carto.carto TO `<principal-public>`;
GRANT EXECUTE ON SCHEMA carto.carto TO `<principal-public>`;

AT Gateway configuration

Some functionalities of the CARTO Analytics Toolbox for Databricks require making external calls from Databricks to CARTO services. In order to make requests to these services, Databricks needs a Connection to the AT Gateway.

Connection

-- Create the connection
CREATE CONNECTION carto_at_gateway
  TYPE HTTP
  OPTIONS (
    host '<provided-at-gateway-url>',
    bearer_token ''
  );

GRANT USE CONNECTION ON CONNECTION carto_at_gateway TO `<principal-public>`;

API Base URL and API Access Token

The Analytics Toolbox LDS functions (geocoding, isolines, routing) require credentials to connect to CARTO's Location Data Services API:

• API Base URL: The address for accessing your CARTO account services, typically https://gcp-us-east1.api.carto.com

• API Access Token: An API Access Token with LDS API permissions

To obtain these credentials:

1. Go to the Developers section in your CARTO workspace

2. Copy the API Base URL displayed there

3. Create a new API Access Token with LDS API enabled

Keep your API Access Token secure. Anyone with access to this token can use the LDS quota assigned to your account.

Installation

Download the installation package

The Analytics Toolbox installation package contains SQL scripts to create the functions in your Unity Catalog schema.

The installation package is only available to CARTO customers. Please contact us at [email protected] to request the installation package for Databricks SQL Warehouses.

This package will contain:

• LICENSE file

• modules.sql file

Create the functions and procedures

1. Extract the installation package

2. Open the modules.sql file in your Databricks SQL editor

3. Update the catalog and schema names if different from the defaults

4. Execute the script against your SQL Warehouse

The script will create all Analytics Toolbox functions in the specified schema.

Running the installation script will replace any existing functions with the same names in the target schema.

Setup AT Gateway variables

After running the installation script, configure the AT Gateway credentials by calling the SETUP procedure:

CALL carto.carto.SETUP('{
  "connection": "<connection-name>",
  "api_base_url": "<your-api-base-url>",
  "api_access_token": "<your-api-access-token>"
}');

This step stores your credentials so that LDS functions can use them. You can pass NULL for the credentials in subsequent LDS function calls to use these stored defaults.

Verification

After installation and configuration, verify that everything is working correctly by checking your LDS quota:

SELECT carto.carto.GET_LDS_QUOTA_INFO(NULL, NULL);

You should receive a JSON response showing your available quota and configured providers:

[
  {
    "used_quota": 0,
    "annual_quota": 100000,
    "providers": {
      "geocoding": "tomtom",
      "isolines": "here",
      "routing": "tomtom"
    }
  }
]

This confirms that:

• The Analytics Toolbox is installed correctly

• Your credentials are valid

• The LDS service is working

Congratulations!

You have successfully installed the CARTO Analytics Toolbox for Databricks. Now you can start using the SQL functions available in the SQL Reference.

Next steps

• Check the SQL Reference for the complete list of available functions

• Learn about LDS functions for geocoding, routing, and isoline generation