Manual installation

Introduction

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

Setup

This step consists of setting up the Snowflake cluster and database where we want to install the toolbox.

Creating the schema

The following script will create the user, schema, and role to be used for the installation in your database. Please note that this script must be executed by an account administrator.

For the sake of documenting the process, we'll will assume a database named CARTO, as well as a schema named CARTO in that database . We will also use a dedicated Snowflake user called CARTO.

All the database, schema and user can have a different name, but remember to adapt the code snippets accordingly.

-- Set admin permissions
USE ROLE ACCOUNTADMIN;

-- Create the carto database
CREATE DATABASE CARTO;

-- Create the carto schema
CREATE SCHEMA CARTO.CARTO;

-- Grant all to sysadmin role
GRANT ALL ON SCHEMA CARTO.CARTO TO ROLE SYSADMIN;

-- Grant usage to public role
GRANT USAGE ON DATABASE CARTO TO ROLE PUBLIC;
GRANT USAGE ON SCHEMA CARTO.CARTO TO ROLE PUBLIC;
GRANT SELECT ON FUTURE TABLES IN SCHEMA CARTO.CARTO TO ROLE PUBLIC;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA CARTO.CARTO TO ROLE PUBLIC;
GRANT USAGE ON FUTURE FUNCTIONS IN SCHEMA CARTO.CARTO TO ROLE PUBLIC;
GRANT USAGE ON FUTURE PROCEDURES IN SCHEMA CARTO.CARTO TO ROLE PUBLIC;

AT Gateway configuration

Some functionalities of the CARTO Analytics Toolbox for Snowflake require making external calls from Snowflake to CARTO services. In order to make requests to these services, Snowflake needs an API integration and a API Gateway

• Creation of isolines, geocoding and routing require making calls to CARTO LDS API. The functions and procedures in the lds module provide access to geocoding and isolines services from different providers directly in your database via SQL. The service provider for each LDS function/procedure will depend on your contractual arrangements with CARTO.

• Some other functionalities, like HTTP Request or Create Builder Map require making a request to the CARTO Platform backend. For this purpose, CARTO provides Lambda functions on different regions.

API integration

CARTO Analytics Toolbox uses external lambda functions (that we call AT Gateway) to perform the requests from Snowflake to the external LDS provider. CARTO provides a role to make use of the lambda functions: “arn:aws:iam::000955892807:role/CartoFunctionsRole”.

Snowflake external functions are required to call the lambda function via an API Gateway. These are the endpoints currently available for the CARTO AT Gateway:

GCP Region	AWS Region	API Gateway Name	API Gateway endpoint
asia-northeast1	ap-northeast-1	at-gateway-asia-northeast1	https://x4tgg7t3y9.execute-api.ap-northeast-1.amazonaws.com/production/at-gateway
australia-southeast1	ap-southeast-2	at-gateway-australia-southeast1	https://hnxqvkcdsj.execute-api.ap-southeast-2.amazonaws.com/production/at-gateway
europe-west1	eu-west-1	at-gateway-europe-west1	https://01wzfofw1l.execute-api.eu-west-1.amazonaws.com/production/at-gateway
europe-central2	eu-central-1	at-gateway-europe-central2	https://ipz0mjyc1i.execute-api.eu-central-1.amazonaws.com/production/at-gateway
us-east1	us-east-1	at-gateway-us-east1	https://dliqfcry6j.execute-api.us-east-1.amazonaws.com/production/at-gateway

Let’s pick, for example, region “us-east-1”, the API Gateway endpoint will be “https://dliqfcry6j.execute-api.us-east-1.amazonaws.com/production/at-gateway”.

To make the connection between Snowflake and the API Gateway, a component called API integration is required. Follow the steps to create an integration for CARTO AT Gateway:

-- Set admin permissions
USE ROLE accountadmin;

-- Create the API integration
CREATE OR REPLACE API INTEGRATION CARTO_AT_GATEWAY
  API_PROVIDER = aws_api_gateway
  API_AWS_ROLE_ARN = 'arn:aws:iam::000955892807:role/CartoFunctionsRole'
  ENABLED = TRUE
  API_ALLOWED_PREFIXES = ('https://dliqfcry6j.execute-api.us-east-1.amazonaws.com/production/at-gateway');

-- Grant usage on the API integration
GRANT USAGE ON INTEGRATION CARTO_AT_GATEWAY TO ROLE public;

Use the API Integration name and the API Gateway endpoint to be used in the installation section.

API Base URL and LDS Token

The Analytics Toolbox LDS functions and procedures make requests to the CARTO LDS API in your account. You need to store the API Base URL and LDS Token in Redshift.

To get the API Base URL, go to the “Developers” section in the CARTO Platform and copy the value. For more information, check the documentation.

To get the LDS Token, go to the “Developers” section and create a new API Access Token. For more information, check the documentation. Make sure your token has LDS API enabled:

Then, keep the API Base URL and LDS Token to be used in the installation section.

Installation

Once the setup is completed, we can proceed with the installation of the toolbox. This step will be performed the first time and every time we want to install an updated version.

Download the Analytics Toolbox package

This zip file contains the scripts to install the analytics toolbox, in this case with the LDS module. Unzip the content in your local storage. This package will contain:

• LICENSE file

• modules.sql file

The package is only available for CARTO customers. Please, please contact us at [e-mail] to get a download link for the installation package. If you're insterested in a trial version of the Analytics Toolbox, check the Snowflake Native App version.

Create the functions and procedures

Run the script to create the SQL functions and procedures in the CARTO schema.

Notice that to install the toolbox in a different database than CARTO, you need to request a custom installation package with the requested database name.

WARNING: This script will remove all the previous functions and procedures in the carto schema.

Setup AT Gateway variables

To configure the LDS functions, we need to run the SETUP procedure with the LDS variables:

CALL CARTO.CARTO.SETUP('{
  "api_integration": "{API_INTEGRATION}",
  "endpoint": "{ENDPOINT}",
  "api_base_url": "{API_BASE_URL}",
  "api_access_token": "{API_ACCESS_TOKEN}"
}');

Congratulations!

You have successfully installed the CARTO Analytics Toolbox in your Snowflake database. Now you can start using the functions in the SQL reference.