docs/tutorial.rst

Tutorial for Superset Administrators
====================================

This tutorial targets a Superset administrator: someone configuring Superset 
for an organization on behalf of users. 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
----------------------------

We assume you already have a database configured and can connect to it from the 
instance on which you’re running Superset. If you’re just testing Superset and 
want to explore sample data, you can load some 
`sample PostgreSQL datasets <https://wiki.postgresql.org/wiki/Sample_Databases>`_
into a fresh DB, or configure the 
`example weather data <https://github.com/dylburger/noaa-ghcn-weather-data>`_
we use here.

Under the **Sources** menu, select the *Databases* option:

.. image:: _static/img/tutorial/tutorial_01_sources_database.png
   :scale: 70%

On the resulting page, click on the green plus sign, near the top left:

.. image:: _static/img/tutorial/tutorial_02_add_database.png
   :scale: 70%

You can configure a number of advanced options on this page, but for 
this walkthrough, you’ll only need to do **two things**:

1. Name your database connection:

.. image:: _static/img/tutorial/tutorial_03_database_name.png
   :scale: 70%

2. Provide the SQLAlchemy Connection URI and test the connection:

.. image:: _static/img/tutorial/tutorial_04_sqlalchemy_connection_string.png
   :scale: 70%

This example shows the connection string for our test weather database. 
As noted in the text below the URI, you should refer to the SQLAlchemy 
documentation on 
`creating new connection URIs <http://docs.sqlalchemy.org/en/rel_1_0/core/engines.html#database-urls>`_
for your target database.

Click the **Test Connection** button to confirm things work end to end. 
Once Superset can successfully connect and authenticate, you should see 
a popup like this:

.. image:: _static/img/tutorial/tutorial_05_connection_popup.png
   :scale: 50%

Moreover, you should also see the list of tables Superset can read from 
the schema you’re connected to, at the bottom of the page:

.. image:: _static/img/tutorial/tutorial_06_list_of_tables.png
   :scale: 70%

If the connection looks good, save the configuration by clicking the **Save** 
button at the bottom of the page:

.. image:: _static/img/tutorial/tutorial_07_save_button.png
   :scale: 70%

Adding a new table
------------------

Now that you’ve configured a database, you’ll need to add specific tables 
to Superset that you’d like to query.

Under the **Sources** menu, select the *Tables* option:

.. image:: _static/img/tutorial/tutorial_08_sources_tables.png
   :scale: 70%

On the resulting page, click on the green plus sign, near the top left:

.. image:: _static/img/tutorial/tutorial_09_add_new_table.png
   :scale: 70%

You only need a few pieces of information to add a new table to Superset:

* The name of the table

.. image:: _static/img/tutorial/tutorial_10_table_name.png
   :scale: 70%

* The target database from the **Database** drop-down menu (i.e. the one 
  you just added above)

.. image:: _static/img/tutorial/tutorial_11_choose_db.png
   :scale: 70%

* Optionally, the database schema. If the table exists in the “default” schema 
  (e.g. the *public* schema in PostgreSQL or Redshift), you can leave the schema 
  field blank.

Click on the **Save** button to save the configuration:

.. image:: _static/img/tutorial/tutorial_07_save_button.png
   :scale: 70%

When redirected back to the list of tables, you should see a message indicating 
that your table was created:

.. image:: _static/img/tutorial/tutorial_12_table_creation_success_msg.png
   :scale: 70%

This message also directs you to edit the table configuration. We’ll edit a limited 
portion of the configuration now - just to get you started - and leave the rest for 
a more advanced tutorial.

Click on the edit button next to the table you’ve created:

.. image:: _static/img/tutorial/tutorial_13_edit_table_config.png
   :scale: 70%

On the resulting page, click on the **List Table Column** tab. Here, you’ll define the 
way you can use specific columns of your table when exploring your data. We’ll run 
through these options to describe their purpose:

* If you want users to group metrics by a specific field, mark it as **Groupable**.
* If you need to filter on a specific field, mark it as **Filterable**.
* Is this field something you’d like to get the distinct count of? Check the **Count 
  Distinct** box.
* Is this a metric you want to sum, or get basic summary statistics for? The **Sum**, 
  **Min**, and **Max** columns will help.
* The **is temporal** field should be checked for any date or time fields. We’ll cover 
  how this manifests itself in analyses in a moment.

Here’s how we’ve configured fields for the weather data. Even for measures like the 
weather measurements (precipitation, snowfall, etc.), it’s ideal to group and filter 
by these values:

.. image:: _static/img/tutorial/tutorial_14_field_config.png

As with the configurations above, click the **Save** button to save these settings.

Exploring your data
-------------------

To start exploring your data, simply click on the table name you just created in 
the list of available tables:

.. image:: _static/img/tutorial/tutorial_15_click_table_name.png

By default, you’ll be presented with a Table View:

.. image:: _static/img/tutorial/tutorial_16_datasource_chart_type.png

Let’s walk through a basic query to get the count of all records in our table. 
First, we’ll need to change the **Since** filter to capture the range of our data. 
You can use simple phrases to apply these filters, like "3 years ago":

.. image:: _static/img/tutorial/tutorial_17_choose_time_range.png

The upper limit for time, the **Until** filter, defaults to "now", which may or may 
not be what you want.

Look for the Metrics section under the **GROUP BY** header, and start typing "Count" 
- you’ll see a list of metrics matching what you type:

.. image:: _static/img/tutorial/tutorial_18_choose_metric.png

Select the *COUNT(\*)* metric, then click the green **Query** button near the top 
of the explore:

.. image:: _static/img/tutorial/tutorial_19_click_query.png

You’ll see your results in the table:

.. image:: _static/img/tutorial/tutorial_20_count_star_result.png

Let’s group this by the *weather_description* field to get the count of records by 
the type of weather recorded by adding it to the *Group by* section:

.. image:: _static/img/tutorial/tutorial_21_group_by.png

and run the query:

.. image:: _static/img/tutorial/tutorial_22_group_by_result.png

Let’s find a more useful data point: the top 10 times and places that recorded the 
highest temperature in 2015.

We replace *weather_description* with *latitude*, *longitude* and *measurement_date* in the 
*Group by* section:

.. image:: _static/img/tutorial/tutorial_23_group_by_more_dimensions.png

And replace *COUNT(\*)* with *max__measurement_flag*:

.. image:: _static/img/tutorial/tutorial_24_max_metric.png

The *max__measurement_flag* metric was created when we checked the box under **Max** and 
next to the *measurement_flag* field, indicating that this field was numeric and that 
we wanted to find its maximum value when grouped by specific fields.

In our case, *measurement_flag* is the value of the measurement taken, which clearly 
depends on the type of measurement (the researchers recorded different values for 
precipitation and temperature). Therefore, we must filter our query only on records 
where the *weather_description* is equal to "Maximum temperature", which we do in 
the **Filters** section at the bottom of the explore:

.. image:: _static/img/tutorial/tutorial_25_max_temp_filter.png

Finally, since we only care about the top 10 measurements, we limit our results to 
10 records using the *Row limit* option under the **Options** header:

.. image:: _static/img/tutorial/tutorial_26_row_limit.png

We click **Query** and get the following results:

.. image:: _static/img/tutorial/tutorial_27_top_10_max_temps.png

In this dataset, the maximum temperature is recorded in tenths of a degree Celsius. 
The top value of 1370, measured in the middle of Nevada, is equal to 137 C, or roughly 
278 degrees F. It’s unlikely this value was correctly recorded. We’ve already been able 
to investigate some outliers with Superset, but this just scratches the surface of what 
we can do.

You may want to do a couple more things with this measure:

* The default formatting shows values like 1.37k, which may be difficult for some 
  users to read. It’s likely you may want to see the full, comma-separated value. 
  You can change the formatting of any measure by editing its config (*Edit Table 
  Config > List Sql Metric > Edit Metric > D3Format*)
* Moreover, you may want to see the temperature measurements in plain degrees C, 
  not tenths of a degree. Or you may want to convert the temperature to degrees 
  Fahrenheit. You can change the SQL that gets executed agains the database, baking 
  the logic into the measure itself (*Edit Table Config > List Sql Metric > Edit 
  Metric > SQL Expression*)

For now, though, let’s create a better visualization of these data and add it to 
a dashboard.

We change the Chart Type to "Distribution - Bar Chart":

.. image:: _static/img/tutorial/tutorial_28_bar_chart.png

Our filter on Maximum temperature measurements was retained, but the query and 
formatting options are dependent on the chart type, so you’ll have to set the 
values again:

.. image:: _static/img/tutorial/tutorial_29_bar_chart_series_metrics.png

You should note the extensive formatting options for this chart: the ability to 
set axis labels, margins, ticks, etc. To make the data presentable to a broad 
audience, you’ll want to apply many of these to slices that end up in dashboards. 
For now, though, we run our query and get the following chart:

.. image:: _static/img/tutorial/tutorial_30_bar_chart_results.png
   :scale: 70%

Creating a slice and dashboard
------------------------------

This view might be interesting to researchers, so let’s save it. In Superset, 
a saved query is called a **Slice**. 

To create a slice, click the **Save as** button near the top-left of the 
explore:

.. image:: _static/img/tutorial/tutorial_19_click_query.png

A popup should appear, asking you to name the slice, and optionally add it to a 
dashboard. Since we haven’t yet created any dashboards, we can create one and 
immediately add our slice to it. Let’s do it:

.. image:: _static/img/tutorial/tutorial_31_save_slice_to_dashboard.png
   :scale: 70%

Click Save, which will direct you back to your original query. We see that 
our slice and dashboard were successfully created:

.. image:: _static/img/tutorial/tutorial_32_save_slice_confirmation.png
   :scale: 70%

Let’s check out our new dashboard. We click on the **Dashboards** menu:

.. image:: _static/img/tutorial/tutorial_33_dashboard.png

and find the dashboard we just created:

.. image:: _static/img/tutorial/tutorial_34_weather_dashboard.png

Things seemed to have worked - our slice is here!

.. image:: _static/img/tutorial/tutorial_35_slice_on_dashboard.png
   :scale: 70%

But it’s a bit smaller than we might like. Luckily, you can adjust the size 
of slices in a dashboard by clicking, holding and dragging the bottom-right 
corner to your desired dimensions:

.. image:: _static/img/tutorial/tutorial_36_adjust_dimensions.gif
   :scale: 120%

After adjusting the size, you’ll be asked to click on the icon near the 
top-right of the dashboard to save the new configuration.

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.