# SQL Warehouse

## Introduction

This guide contains the steps to perform a fully manual installation of the [CARTO Analytics Toolbox for Databricks](https://docs.carto.com/analytics-toolbox-databricks/overview/getting-started/).

{% hint style="success" %}
The CARTO Analytics Toolbox for Databricks is available for CARTO customers. [Contact us](mailto:support@carto.com) to get an installation package.
{% endhint %}

## Prerequisites

Before installing the Analytics Toolbox, ensure you have:

* [Unity Catalog](https://docs.databricks.com/en/data-governance/unity-catalog/index.html) enabled in your Databricks workspace
* A [SQL Warehouse](https://docs.databricks.com/en/compute/sql-warehouse/index.html) provisioned in your workspace
* Appropriate permissions to create catalogs, schemas and functions:

```sql
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:

```sql
-- 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

```sql
-- 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](https://github.com/CartoDB/gitbook-documentation/blob/master/carto-user-manual/developers/api-access-tokens.md) 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

{% hint style="warning" %}
Keep your API Access Token secure. Anyone with access to this token can use the LDS quota assigned to your account.
{% endhint %}

## Installation

### Download the installation package

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

{% hint style="info" %}
The installation package is only available to CARTO customers. Please contact us at [**support@carto.com**](mailto:support@carto.com) to request the installation package for Databricks SQL Warehouses.
{% endhint %}

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.

{% hint style="danger" %}
Running the installation script will replace any existing functions with the same names in the target schema.
{% endhint %}

### Setup AT Gateway variables

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

```sql
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:

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

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

```json
[
  {
    "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](/data-and-analysis/analytics-toolbox-for-databricks/reference.md).

## Next steps

* Check the [SQL Reference](/data-and-analysis/analytics-toolbox-for-databricks/reference.md) for the complete list of available functions
* Learn about [LDS functions](/data-and-analysis/analytics-toolbox-for-databricks/reference/lds.md) for geocoding, routing, and isoline generation


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carto.com/data-and-analysis/analytics-toolbox-for-databricks/getting-access/sql-warehouse.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.