Assisted installation through the CARTO UI

Environment setup

CARTO requires a specific setup in your Snowflake account to securely install the Analytics Toolbox and then access it from our different platform interfaces.

This process must be completed by a user with ACCOUNTADMIN permissions in the Snowflake account. In this process you will need to create the following resources:

CARTO database within your Snowflake account.
CARTO schema in the CARTO database.
CARTO_ROLE user role with full USAGE privileges in the CARTO database and ALL PRIVILEGES on the CARTO schema.
CARTO user granted with the CARTO_ROLE that CARTO will use to perform the installation and maintain future updates.

Create resources

In order to create the aforementioned resources please copy and paste the following queries in your Snowflake console.

-- Set admin permissions
USE ROLE ACCOUNTADMIN;

-- Create the carto database where the toolbox will be installed
CREATE DATABASE "CARTO";

-- Create the carto schema in the carto database
CREATE SCHEMA "CARTO"."CARTO";

-- Create a carto role for the carto user
CREATE ROLE CARTO_ROLE;

-- Ensure the sysadmin role inherits any privileges the carto role is granted.
-- Note that this does not grant sysadmin privileges to the carto role
GRANT ROLE CARTO_ROLE TO ROLE SYSADMIN;

-- Create the carto user
CREATE USER CARTO WITH DEFAULT_ROLE=CARTO_ROLE DEFAULT_WAREHOUSE=COMPUTE_WH PASSWORD='<strong, unique password>';

-- Grant the carto role to the carto user
GRANT ROLE CARTO_ROLE TO USER CARTO;

-- Let the carto user see this database
GRANT USAGE ON DATABASE "CARTO" TO ROLE CARTO_ROLE;

-- Give the carto user full access to the carto schema
GRANT ALL PRIVILEGES ON SCHEMA "CARTO"."CARTO" TO ROLE CARTO_ROLE;

-- Give the carto user permission to use the warehouse
GRANT OPERATE ON WAREHOUSE COMPUTE_WH TO ROLE CARTO_ROLE;
GRANT USAGE ON WAREHOUSE COMPUTE_WH TO ROLE CARTO_ROLE;

Grant usage

In order to make the Analytics Toolbox available to use via the resources you have just created, some permissions should be granted. Please copy & paste the queries below if you want to grant usage of the Analytics Toolbox to all the users in your Snowflake account or amend the query to fulfil your specific user access requirements:

-- Set admin permissions
USE ROLE ACCOUNTADMIN;

-- Grant usage to public role
-- Apply this for any other role that needs to use the toolbox
GRANT USAGE ON DATABASE "CARTO" TO ROLE PUBLIC;
GRANT USAGE ON SCHEMA "CARTO"."CARTO" TO ROLE PUBLIC;
GRANT SELECT ON ALL TABLES IN SCHEMA "CARTO"."CARTO" TO ROLE PUBLIC;
GRANT SELECT ON FUTURE TABLES IN SCHEMA "CARTO"."CARTO" TO ROLE PUBLIC;
GRANT SELECT ON ALL VIEWS IN SCHEMA "CARTO"."CARTO" TO ROLE PUBLIC;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA "CARTO"."CARTO" TO ROLE PUBLIC;
GRANT USAGE ON ALL FUNCTIONS IN SCHEMA "CARTO"."CARTO" TO ROLE PUBLIC;
GRANT USAGE ON FUTURE FUNCTIONS IN SCHEMA "CARTO"."CARTO" TO ROLE PUBLIC;
GRANT USAGE ON ALL PROCEDURES IN SCHEMA "CARTO"."CARTO" TO ROLE PUBLIC;
GRANT USAGE ON FUTURE PROCEDURES IN SCHEMA "CARTO"."CARTO" TO ROLE PUBLIC;

API integration

CARTO’s Analytics Toolbox for Snowflake uses external lambda functions in Amazon Web Services (AWS) in order to perform requests to our external Location Data Services (LDS) providers for the geocoding and isolines functions in the LDS module. CARTO provides a specific 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 CARTO LDS, select the best for your case, depending on the region of your Snowflake account:

AWS region	Region name	API Gateway endpoint
Asia Pacific (Tokyo)	ap-northeast-1	https://d0ril9q8b8.execute-api.ap-northeast-1.amazonaws.com/production/lds
Asia Pacific (Sydney)	ap-southeast-2	https://wccsrp480l.execute-api.ap-southeast-2.amazonaws.com/production/lds
Europe (Ireland)	eu-west-1	https://a3g86ayq28.execute-api.eu-west-1.amazonaws.com/production/lds
United States East (N. Virgina)	us-east-1	https://m0qahrqhei.execute-api.us-east-1.amazonaws.com/production/lds

AWS region

Region name

API Gateway endpoint

Asia Pacific (Tokyo)

ap-northeast-1

https://d0ril9q8b8.execute-api.ap-northeast-1.amazonaws.com/production/lds

Asia Pacific (Sydney)

ap-southeast-2

https://wccsrp480l.execute-api.ap-southeast-2.amazonaws.com/production/lds

Europe (Ireland)

eu-west-1

https://a3g86ayq28.execute-api.eu-west-1.amazonaws.com/production/lds

United States East (N. Virgina)

us-east-1

https://m0qahrqhei.execute-api.us-east-1.amazonaws.com/production/lds

Pay attention to this step and remember that you should choose the best API Gateway endpoint for your case based on the region of your Snowflake account. If you make the configuration using an endpoint and later you want to modify it, you must repeat the whole setup and installation process.

For illustration purposes let’s pick, for example, region “us-east-1”; then, the API Gateway end-point would be: “https://m0qahrqhei.execute-api.us-east-1.amazonaws.com/production/lds”.

To make the connection between Snowflake and the API Gateway, a component called API integration is required. Follow the steps below to create the API integration to be able to use CARTO’s Location Data Services (replacing the API Gateway endpoint with the most suitable one for your Snowflake account):

-- Set admin permissions
USE ROLE ACCOUNTADMIN;

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

-- Grant usage on the api integration
GRANT USAGE ON INTEGRATION CARTO_LDS TO ROLE PUBLIC;

Installation

Note

Note that this feature is only available for the Admin users in your CARTO account. Please contact CARTO’s support team at support@carto.com in case of needing assistance.

Admin users can install the Analytics Toolbox in Snowflake accounts from the Settings section available in the CARTO Workspace. In Settings, Admins will find a sub-section called “Analytics Toolbox” in which they can see and manage all different installations of the Analytics Toolbox associated with the CARTO account.

In order to start the installation process of the Analytics Toolbox in your Snowflake account, click on “+ New installation” on the aforementioned area of the Settings section.

From the list of the supported cloud data warehouses, select “Snowflake” and click on “Continue”.

The first thing that the installation wizard will ask you is to confirm that you have followed all the necessary steps detailed on the “Setup” section of this documentation. Mainly, the creation of the CARTO database with the CARTO schema, plus a user and a role with the necessary privileges for CARTO to securely connect with your account and perform the installation and future updates of the Analytics Toolbox.

Once you have ensured that your Snowflake account has been configured appropriately, confirm by ticking the box next to the message “I have already completed the setup of my Snowflake account”.

In the next step, you should input your Snowflake account name and the password you have associated with the CARTO user. Then, click on “Validate setup” so CARTO can check that we have access to all necessary resources to securely proceed with the Analytics Toolbox installation in your Snowflake account.

During this process CARTO will check that we have access to the CARTO database and schema with the necessary privileges to perform the installation. We also check that we can see the API integration necessary for the Location Data Services procedures (e.g. geocoding, islones, etc.). If you encounter any issues in this step please do not hesitate to contact CARTO’s support team at support@carto.com to receive technical assistance.

Once we validate that the Snowflake account has been set up successfully, you can click on “Install” in order to start the actual installation of the Analytics Toolbox.

Once you click on Install, the process of installing all functions and procedures in the relevant database will start. Please bear in mind that this process may take several minutes to complete.

Once the process completes successfully, click on “Done” to go back to the Analytics Toolbox section in Settings.

Now, you should be able to see your new Analytics Toolbox installation listed with its relevant details and “Available” as its Status. You are now all set to start getting the most out of advanced spatial analytics natively in your Snowflake account!

You can check the version by running SELECT CARTO.CARTO.VERSION_ADVANCED().

Once you have installed the Analytics Toolbox in your Snowflake account, all connections to Snowflake databases within that account and which have access to the CARTO database and CARTO schema should be able to automatically detect the Analytics Toolbox and make use of it. In that case, you should see in the relevant connection cards in the “Connections” section of the Workspace that the Analytics Toolbox is available.

Updates

We are currently actively working on further expanding and improving the Analytics Toolbox, therefore we tend to release a new update of this component approximately every month. When updates become available you will be informed in the Settings section plus in each connection card that is associated with a specific Analytics Toolbox installation.

Admin users can manage the updates of the Analytics Toolbox from the Settings section, in the same area used to perform the installation. Once new updates become available, click on the “Update available” option in the Status column associated with the relevant installation.

Please confirm that you would like to proceed with the Analytics Toolbox update in the dialog box that will appear on your screen by clicking on the “Yes, update” button.

CARTO will use the same credentials provided for that Analytics Toolbox installation and perform the update process on the same resources used during the installation.

Once the update has completed successfully please click on “Done”. You should then see the Analytics Toolbox installation again with “Available” on the Status column.

Change credentials

If for any reason you need to change the password of the CARTO user that was used for installing the Analytics Toolbox in your account and that will be used also for updating the package, you can do so by selecting “Change credentials” in the relevant Analytics Toolbox installation from the list.

As all other parameters are fixed, you can only modify the password. Please introduce and confirm the new password associated with the CARTO user and click on “Validate credentials”.

Next, CARTO will validate that with the new credentials we can check the setup that will be necessary to update the Analytics Toolbox when new versions become available.

Once CARTO has validated that everything works well, click on “Save changes”.

Uninstallation

Admin users can uninstall the Analytics Toolbox from Snowflake accounts at any time. In order to do that, you should click on Uninstall from the relevant Analytics Toolbox installation detailed in the Settings section.

Next, as this process will be irreversible, we ask you to confirm that you would like to uninstall that specific Analytics Toolbox installation. Click on “Yes, uninstall” to proceed with uninstalling the Analytics Toolbox from your Snowflake account.

Once the process is complete, you will be taken back to the Analytics Toolbox section of Settings in which the specific installation that you have just removed should not appear anymore.

Note that any active Snowflake connection will have stopped having access to the Analytics Toolbox. Therefore, in their connection cards you will be informed that the Analytics Toolbox is not available and that the Admin user should install it.

PreviousGetting access NextManual installation

Last updated 1 month ago