The superset utility is a modern, enterprise-ready business intelligence web application. It requires Meltano version 2.0.

Getting Started #

Prerequisites #

If you haven't already, follow the initial steps of the Getting Started guide:

  1. Install Meltano
  2. Create your Meltano project

Dependencies #

The Superset plugin requires Meltano version 2.0. If you’re on an older version, make sure you update Meltano first.

Once you have Meltano running, you likely already have everything you need for Superset as well. If you do run into trouble installing Superset following the instructions below, check out the OS Dependencies section in the Superset documentation. Note that the rest of that guide is not relevant if you’re using Meltano to manage your Superset installation, initialization, and configuration.

Installation and configuration #

  1. Add the superset utility to your project using meltano add :

    meltano add utility superset
  2. Configure the settings below using meltano config .

Next steps #

  1. If you’re running Superset for the first time in a new environment, generate a new SECRET_KEY to increase security:

    meltano config superset set SECRET_KEY $(openssl rand -base64 42)
    
  2. Create an admin user: (use admin as username to be able to load the examples)

    meltano invoke superset:create-admin
    

    This is equivalent to superset fab create-admin in the Superset documentation

  3. Optionally, load some example data to play with:

    meltano invoke superset:load-examples
    

    This is equivalent to superset load_examples in the Superset documentation

  4. Launch the Superset UI and log in using the username/password you created:

    meltano invoke superset:ui
    

    By default, the UI will be available at at http://localhost:8088. You can change this using the ui.bind_host and ui.port settings documented below.

Add additional database drivers #

Superset does not ship bundled with connectivity to databases, except for SQLite, which is part of the Python standard library. You’ll need to install the required packages for the database you want to use as your metadata database as well as the packages needed to connect to the databases you want to access through Superset.

You can find the list of supported databases and the appropriate PyPI (pip) packages in the Supported Databases and Dependencies section in the Superset documenation. These can then be added to your Meltano project by configuring a custom pip_url for the superset utility:

  1. Find the superset plugin definition in your meltano.yml project file
  2. Update the pip_url property to include the desired additional packages:

    utilities:
    - name: superset
      variant: apache
      pip_url: apache-superset==1.5.0 snowflake-sqlalchemy
    
  3. Re-install the plugin:

    meltano install utility superset
    

Now when you (re)start Superset, you will be able to connect to a new type of database, like Snowflake in the example.

If you run into any issues, learn how to get help.

Settings #

Meltano centralizes the configuration of all of the plugins in your project, including Superset’s. This means that if the Superset documentation tells you to put something in superset_config.py, you can use meltano config, meltano.yml, or environment variables instead, and get the benefits of Meltano features like environments.

Most settings (those with simple values like strings, integers, booleans, lists, or dictionaries) can be added directly to meltano.yml, manually or using meltano config. For example, ROW_LIMIT = 5000 becomes meltano config superset set ROW_LIMIT 5000 on the CLI, or ROW_LIMIT: 5000 in meltano.yml. Just like in superset_config.py, config keys should be ALL_CAPS.

Advanced configuration #

If you want to configure something more complex, like custom OAuth2 configuration, you can add a superset_config.py file somewhere in your project, put your Superset config there exactly as the documentation suggests, and tell Meltano to pass that to Superset along with the Meltano-managed configuration by adding the config_path property to the superset plugin definition in meltano.yml:

utilities:
- name: superset
  variant: apache
  pip_url: apache-superset==1.5.0
  config_path: analyze/superset/superset_config.py
  config:
    ROW_LIMIT: 5000

Properties defined in your own superset_config.py take precedence over those managed by Meltano, like ROW_LIMIT in the example.

Superset settings already known to Meltano #

The settings for utility superset that are known to Meltano are documented below. To quickly find the setting you're looking for, use the Table of Contents at the top of the page.

UI Bind Host (ui.bind_host) #

Host used by meltano invoke superset:ui. Used in the gunicorn --bind option along with ui.port.

How to use #

Manage this setting using meltano config or an environment variable:

meltano config superset set ui.bind_host <ui.bind_host>

export SUPERSET_UI_BIND_HOST=<ui.bind_host>

UI Port (ui.port) #

Port used by meltano invoke superset:ui. Used in the gunicorn --bind option along with ui.bind_host.

How to use #

Manage this setting using meltano config or an environment variable:

meltano config superset set ui.port <ui.port>

export SUPERSET_UI_PORT=<ui.port>

UI Timeout (ui.timeout) #

Timeout in sections, used by meltano invoke superset:ui. Corresponds to the gunicorn --timeout option

How to use #

Manage this setting using meltano config or an environment variable:

meltano config superset set ui.timeout <ui.timeout>

export SUPERSET_UI_TIMEOUT=<ui.timeout>

UI Workers (ui.workers) #

Workers used by meltano invoke superset:ui. Corresponds to the gunicorn --workers option

How to use #

Manage this setting using meltano config or an environment variable:

meltano config superset set ui.workers <ui.workers>

export SUPERSET_UI_WORKERS=<ui.workers>

SQLAlchemy Database URI (SQLALCHEMY_DATABASE_URI) #

  • Environment variable: SUPERSET_SQLALCHEMY_DATABASE_URI
  • Default: sqlite:///$MELTANO_PROJECT_ROOT/.meltano/utilities/superset/superset.db

Superset metadata database connection string. Equivalent to the SQLALCHEMY_DATABASE_URI setting in superset_config.py.

SQLite is used by default, but in production PostgreSQL or MySQL is more appropriate. See the Superset documentation for more information. To add a database driver like psycopg2 or mysqlclient, refer to the Add additional database drivers section above.

How to use #

Manage this setting using meltano config or an environment variable:

meltano config superset set SQLALCHEMY_DATABASE_URI <SQLALCHEMY_DATABASE_URI>

export SUPERSET_SQLALCHEMY_DATABASE_URI=<SQLALCHEMY_DATABASE_URI>

Secret Key (SECRET_KEY) #

App secret key used for securely signing the session cookie and encrypting sensitive information on the database. Equivalent to the SECRET_KEY setting in superset_config.py.

How to use #

Manage this setting using meltano config or an environment variable:

meltano config superset set SECRET_KEY <SECRET_KEY>

export SUPERSET_SECRET_KEY=<SECRET_KEY>

Commands #

The superset utility supports the following commands that can be used with meltano invoke :

ui #

  • Equivalent to: gunicorn --bind $SUPERSET_UI_BIND_HOST:$SUPERSET_UI_PORT --timeout $SUPERSET_UI_TIMEOUT --workers $SUPERSET_UI_WORKERS superset.app:create_app()

Start the Superset UI. Will be available on the configured ui.bind_host and ui.port, which default to http://localhost:8088

How to use #

Run this command using meltano invoke:

meltano invoke superset:ui [additional arguments...]

create-admin #

  • Equivalent to: superset fab create-admin

Create an admin user.

How to use #

Run this command using meltano invoke:

meltano invoke superset:create-admin [additional arguments...]

load-examples #

  • Equivalent to: superset load_examples

Load examples.

How to use #

Run this command using meltano invoke:

meltano invoke superset:load-examples [additional arguments...]

Troubleshooting #

Invalid decryption key #

If you see a ValueError: Invalid decryption key warning or a message that Superset default roles and permissions could not be created: 'superset init' failed then it’s likely that your encryption key is incorrect.

If you change your SECRET_KEY, the metadata database containing your users and reports will become unreadable. If there was nothing valuable in there, you can delete it at .meltano/utilities/superset/superset.db inside your project. If you changed the secret key because the old one was leaked, you can rotate the key:

meltano config superset set SECRET_KEY <new_key>
meltano config superset set PREVIOUS_SECRET_KEY <original_key>
meltano invoke superset re-encrypt-secrets

Looking for help? #

If you're having trouble getting the superset utility to work, look for an existing issue in its repository, file a new issue, or join the Meltano Slack community and ask for help in the #plugins-general channel.

Found an issue on this page? #

This page is generated from a YAML file that you can contribute changes to. Edit it on GitHub!