Getting access

This guide explains all the steps to install the Python libraries and the SQL functions and procedures of the toolbox in your PostgreSQL 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 PostgreSQL.
advanced: this is a premium package only available for CARTO customers. It contains advanced GIS functions to power high-level GIS analytics in PostgreSQL.
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.
Setup
This step consists of setting up the PostgreSQL database where we want to install the toolbox. A Postgres database is required (RDS, Aurora, Cloud SQL, Azure, etc.)
Here is the documentation to create a PostgreSQL cluster. Once the cluster is created, save the hostname. This is required to perform the connection to the database.
Creating the schema
Once the account and the cluster are created, connect the database to create the carto schema. The CARTO Analytics Toolbox will be installed in this schema. We also recommend having a dedicated user called carto with the permissions to manage the carto schema.
To do this, connect to your PostgreSQL database and run the following script:
-- Create the carto schema
CREATE SCHEMA carto;
​
-- Grant usage to public role
GRANT USAGE ON SCHEMA carto TO public;
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA carto TO public;
GRANT EXECUTE ON ALL PROCEDURES IN SCHEMA carto TO public;
This information (database, user and password) will be needed in the installation step.
You can check out the PostgreSQL getting started documentation for further information.
Installing extensions
The CARTO Analytics Toolbox makes use of the PostGIS extension. Make sure you have this extension installed in your database. Run the following query to enable the extension.
CREATE EXTENSION postgis;
Some modules require additional extensions. In case you want to make use of them, make sure you have the corresponding extension installed in your database. Run the following query to enable the extensions.
CREATE EXTENSION plv8; -- Required only by H3
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.
In this section, we will use a Python script to perform the installation process.
If you have a previously installed version of the Analytics Toolbox, you can check the installed version by running SELECT carto.VERSION_CORE().
1. Install the CARTO Analytics Toolbox installer
This will work in any operating system: Windows, macOS, and Linux.
1.Install Python >= 3.7: https://www.python.org/downloads/
2.Create a virtual environment (optional for Linux, macOS):
python -m venv env
source env/bin/activate
3.Next, install the tool:
pip install -U pip
pip install git+https://github.com/cartodb/[email protected]#subdirectory=tools/installer
2. Create the configuration file
Create a config.yml file. We recommend creating it in an empty directory. This file must contain information on the Postgres connection. For example:
connection:
  cloud: postgres
  host: HOST
  database: DATABASE
  user: USER
  password: PASSWORD
Fill the configuration file with the connection information (Postgres database to install the Analytics Toolbox).
3. Download the Analytics Toolbox package
This zip file contains the scripts to install the analytics toolbox. Put the zip file in the same directory as the config.yml file. Latest installation package: package file​
4. Run the installation script
From the directory containing the config.yaml file, and the zip installation package, open a console and run the Python installer as shown below.
cat-installer carto-analytics-toolbox-postgres-latest.zip
The installer will read both the Configuration file and Analytics Toolbox package and perform the installation of the modules in the specified Postgres database.
The output should look like this:
Reading config file: config.yml
Reading package file: carto-analytics-toolbox-postgres-latest.zip
Installing modules...
100%|█████████████████████████████████████| 62/62 [00:09<00:00,  6.45it/s]
This script will remove all the previous functions and procedures in the carto schema.
Congratulations! you have successfully installed the CARTO Analytics Toolbox in your PostgreSQL database. Now you can start testing the functions in the SQL reference.
Last modified 23d ago