This guide explains all the steps to install the Python libraries and the SQL functions and procedures of the toolbox in your Redshift database.
The CARTO Analytics Toolbox contains two packages:
- core: this is the public and open-source package. It contains all the core GIS functions that complement the GIS native functions available in Redshift.
- advanced: this is a premium package only available for CARTO customers. It contains advanced GIS functions to power high-level GIS analytics in Redshift.
This guide explains how to install the core package. To access the advanced features, please contact [email protected].
We can divide the process into two steps: setup and installation. The first one must be done only the first time. The second one must be done every time you want to install a new version of the packages.
This step consists of setting up the Redshift cluster and database where we want to install the toolbox. An AWS account is required.
Here is the documentation to create a Redshift cluster. Once the cluster is created, save the hostname (e.g. redshift-cluster-1.asdf1234.us-east-2.redshift.amazonaws.com). This is required to perform the connection to the database.
Once the account and the cluster are created, connect the database to create the
cartoschema. The CARTO Analytics Toolbox will be installed in this schema. We also recommend having a dedicated user called
cartowith the permissions to manage the
To do this, connect to your Redshift database and run the following script:
-- Create the carto user
CREATE USER carto WITH PASSWORD '<strong, unique password>';
-- Create the carto schema
CREATE SCHEMA carto;
-- Give the carto user full access to the carto schema
GRANT ALL ON SCHEMA carto TO carto;
GRANT USAGE ON LANGUAGE plpgsql TO carto;
GRANT USAGE ON LANGUAGE plpythonu TO carto;
This information (database, user and password) will be needed in the installation step.
You can check out the Redshift getting started documentation for further information.
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.
This step is required to run the next SQL scripts. Connect to the database that has the CARTO schema using the CARTO user and password.
If you have a previously installed version of the Analytics Toolbox, you can check the installed version by running
libraries.sqlto create the Python libraries used by the toolbox in the cluster.
If the following error arises
Must be superuser or the owner of library X, means that the library is already created by a superuser, so your user can not replace it. If the superuser drops the library (
DROP LIBRARY X), then your user will be able to create it.
modules.sqlto create the SQL functions and procedures in the
This script will remove all the previous functions and procedures in the
Congratulations! you have successfully installed the CARTO Analytics Toolbox in your Redshift database. Now you can start testing the functions in the SQL reference.