This section is focused on documentation for end-users who will be using Superset for the data analysis and exploration workflow (data analysts, business analysts, data scientists, etc). In addition to this site, Preset.io maintains an updated set of end-user documentation at docs.preset.io.

This tutorial targets someone who wants to create charts and dashboards in Superset. We’ll show you how to connect Superset to a new database and configure a table in that database for analysis. You’ll also explore the data you’ve exposed and add a visualization to a dashboard so that you get a feel for the end-to-end user experience.

Connecting to a new database​

Superset itself doesn’t have a storage layer to store your data but instead pairs with your existing SQL-speaking database or data store.

First things first, we need to add the connection credentials to your database to be able to query and visualize data from it. If you’re using Superset locally via Docker compose, you can skip this step because a Postgres database, named examples, is included and pre-configured in Superset for you.

Under the + menu in the top right, select Data, and then the Connect Database option:

Then select your database type in the resulting modal:

Once you’ve selected a database, you can configure a number of advanced options in this window, or for the purposes of this walkthrough, you can click the link below all these fields:

Once you’ve clicked that link you only need to specify two things (the database name and SQLAlchemy URI):

As noted in the text below the form, you should refer to the SQLAlchemy documentation on creating new connection URIs for your target database.

Click the Test Connection button to confirm things work end to end. If the connection looks good, save the configuration by clicking the Connect button in the bottom right corner of the modal window:

Congratulations, you’ve just added a new data source in Superset!

Registering a new table​

Now that you’ve configured a data source, you can select specific tables (called Datasets in Superset) that you want exposed in Superset for querying.

Navigate to Data ‣ Datasets and select the + Dataset button in the top right corner.

A modal window should pop up in front of you. Select your Database, Schema, and Table using the drop downs that appear. In the following example, we register the cleaned_sales_data table from the examples database.

To finish, click the Add button in the bottom right corner. You should now see your dataset in the list of datasets.

Customizing column properties​

Now that you’ve registered your dataset, you can configure column properties for how the column should be treated in the Explore workflow:

• Is the column temporal? (should it be used for slicing & dicing in time series charts?)
• Should the column be filterable?
• Is the column dimensional?
• If it’s a datetime column, how should Superset parse the datetime format? (using the ISO-8601 string pattern)

Superset semantic layer​

Superset has a thin semantic layer that adds many quality of life improvements for analysts. The Superset semantic layer can store 2 types of computed data:

1. Virtual metrics: you can write SQL queries that aggregate values from multiple column (e.g. SUM(recovered) / SUM(confirmed)) and make them available as columns for (e.g. recovery_rate) visualization in Explore. Aggregate functions are allowed and encouraged for metrics.

You can also certify metrics if you’d like for your team in this view.

1. Virtual calculated columns: you can write SQL queries that customize the appearance and behavior of a specific column (e.g. CAST(recovery_rate) as float). Aggregate functions aren’t allowed in calculated columns.

Creating charts in Explore view​

Superset has 2 main interfaces for exploring data:

• Explore: no-code viz builder. Select your dataset, select the chart, customize the appearance, and publish.
• SQL Lab: SQL IDE for cleaning, joining, and preparing data for Explore workflow

We’ll focus on the Explore view for creating charts right now. To start the Explore workflow from the Datasets tab, start by clicking the name of the dataset that will be powering your chart.

You’re now presented with a powerful workflow for exploring data and iterating on charts.

• The Dataset view on the left-hand side has a list of columns and metrics, scoped to the current dataset you selected.
• The Data preview below the chart area also gives you helpful data context.
• Using the Data tab and Customize tabs, you can change the visualization type, select the temporal column, select the metric to group by, and customize the aesthetics of the chart.

As you customize your chart using drop-down menus, make sure to click the Run button to get visual feedback.

In the following screenshot, we craft a grouped Time-series Bar Chart to visualize our quarterly sales data by product line just by clicking options in drop-down menus.

Creating a slice and dashboard​

To save your chart, first click the Save button. You can either:

• Save your chart and add it to an existing dashboard
• Save your chart and add it to a new dashboard

In the following screenshot, we save the chart to a new “Superset Duper Sales Dashboard”:

To publish, click Save and goto Dashboard.

Behind the scenes, Superset will create a slice and store all the information needed to create your chart in its thin data layer (the query, chart type, options selected, name, etc).

To resize the chart, start by clicking the Edit Dashboard button in the top right corner.

Then, click and drag the bottom right corner of the chart until the chart layout snaps into a position you like onto the underlying grid.

Click Save to persist the changes.

Congrats! You’ve successfully linked, analyzed, and visualized data in Superset. There are a wealth of other table configuration and visualization options, so please start exploring and creating slices and dashboards of your own

ֿ

Manage access to Dashboards​

Access to dashboards is managed via owners (users that have edit permissions to the dashboard)

Non-owner users access can be managed two different ways:

1. Dataset permissions - if you add to the relevant role permissions to datasets it automatically grants implicit access to all dashboards that uses those permitted datasets
2. Dashboard roles - if you enable DASHBOARD_RBAC feature flag then you be able to manage which roles can access the dashboard
   • Granting a role access to a dashboard will bypass dataset level checks. Having dashboard access implicitly grants read access to all the featured charts in the dashboard, and thereby also all the associated datasets.
   • If no roles are specified for a dashboard, regular Dataset permissions will apply.

Customizing dashboard​

The following URL parameters can be used to modify how the dashboard is rendered:

• standalone:
  • 0 (default): dashboard is displayed normally
  • 1: Top Navigation is hidden
  • 2: Top Navigation + title is hidden
  • 3: Top Navigation + title + top level tabs are hidden
• show_filters:
  • 0: render dashboard without Filter Bar
  • 1 (default): render dashboard with Filter Bar if native filters are enabled
• expand_filters:
  • (default): render dashboard with Filter Bar expanded if there are native filters
  • 0: render dashboard with Filter Bar collapsed
  • 1: render dashboard with Filter Bar expanded

For example, when running the local development build, the following will disable the Top Nav and remove the Filter Bar: http://localhost:8088/superset/dashboard/my-dashboard/?standalone=1&show_filters=0