-
-

Tutorial

-

This basic linear tutorial will take you through connecting to a database, -adding a table, creating a slice and a dashboard. First you’ll need to tell -Superset where to find the database you want to -query. First go to the database menu

-_images/db_menu.png -

Now click on the + button to add a new entry

-_images/db_plus.png -

Fill in an arbitrary reference name for the database, and you SQLAlchemy -URI. To figure out how to construct your URI, check out the -SQLAlchemy documentation. -Then you can test your connection. If it works, you’ll see a positive popup -and list of the tables that SQLAlchemy has found for that URI.

-_images/db_added.png -

Once your database has been added, it’s time to add your table. Navigate -using the navigation bar at the top to Sources -> Tables and click the -plus (+) sign there (similar to the one ).

-

Now enter the name of the table in the Table Name textbox, and select -the database you just created in the Database dropdown, hit save. At this -moment, Superset fetched the column names, their data types and tries to guess -which fields are metrics in dimensions. From the list view, edit the table -that you just created by clicking the tiny pen icon.

-_images/pen.png -

Now you’re in the table editor, click on the “List Table Column” tab, -showing you the list of columns in your table as well as their data types.

-_images/matrix.png -

Click the checkboxes here that inform Superset how your columns should be -shown in the explore view, and which metrics should be created. Make sure -to inform Superset about your date columns. You could also create -“SQL expression” columns here, or metrics in that tab as aggregate expressions, -but let’s not do that just yet. Hit save.

-

You should now be back in the Table List view. Click on the name of the -table you just created. You enter the “Explore” view for your table.

-_images/explore.png -

The next step is to create a Slice. First, make sure to use a time filter -that is relevant.

-
-

Note

-

You can use some “natural language time expressions” -either as relative (as in now, 4 weeks ago, or 1 year ago) as well -as hard date or time expressions (as in 3015, 3016-01-01 or -May).

+
+

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 +into a fresh DB, or configure the +example weather data +we use here.

+

Under the Sources menu, select the Databases option:

+_images/tutorial_01_sources_database.png +

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

+_images/tutorial_02_add_database.png +

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:
    2. +
+_images/tutorial_03_database_name.png +
    +
  1. Provide the SQLAlchemy Connection URI and test the connection:
    2. +
+_images/tutorial_04_sqlalchemy_connection_string.png +

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 +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:

+_images/tutorial_05_connection_popup.png +

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:

+_images/tutorial_06_list_of_tables.png +

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

+_images/tutorial_07_save_button.png +
+
+

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:

+_images/tutorial_08_sources_tables.png +

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

+_images/tutorial_09_add_new_table.png +

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

+
    +
  • The name of the table
    • +
+_images/tutorial_10_table_name.png +
    +
  • The target database from the Database drop-down menu (i.e. the one +you just added above)
    • +
+_images/tutorial_11_choose_db.png +
    +
  • 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:

+_images/tutorial_07_save_button.png +

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

+_images/tutorial_12_table_creation_success_msg.png +

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:

+_images/tutorial_13_edit_table_config.png +

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:

+_images/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:

+_images/tutorial_15_click_table_name.png +

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

+_images/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”:

+_images/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:

+_images/tutorial_18_choose_metric.png +

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

+_images/tutorial_19_click_query.png +

You’ll see your results in the table:

+_images/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:

+_images/tutorial_21_group_by.png +

and run the query:

+_images/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:

+_images/tutorial_23_group_by_more_dimensions.png +

And replace COUNT(*) with max__measurement_flag:

+_images/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:

+_images/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:

+_images/tutorial_26_row_limit.png +

We click Query and get the following results:

+_images/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”:

+_images/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:

+_images/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:

+_images/tutorial_30_bar_chart_results.png +
+
+

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:

+_images/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:

+_images/tutorial_31_save_slice_to_dashboard.png +

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

+_images/tutorial_32_save_slice_confirmation.png +

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

+_images/tutorial_33_dashboard.png +

and find the dashboard we just created:

+_images/tutorial_34_weather_dashboard.png +

Things seemed to have worked - our slice is here!

+_images/tutorial_35_slice_on_dashboard.png +

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:

+_images/tutorial_36_adjust_dimensions.gif +

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.

-

Alter the form’s option and click Query until you get to an interesting -cut of data, and click SAVE AS, enter a name, and you just created your first -slice.

-_images/created.png -

This slice is now accessible in the slice list from the -Menu -> Slices at any time. Note that this view is easily filterable and -searchable.

-_images/search.png -

Now let’s create a dashboard. A dashboard is simply a collection of slices -with metadata around their sizes, positions, CSS style and a few other things. -Navigate to the dashboard list view Menu -> Dashboard and click the plus -(+) sign. In the form, enter a name and pick the slice you just created.

-_images/new_dash.png -

Hit Save, you should be back in Menu -> Dashboard. Now enter your -new dashboard.

-_images/in_new_dash.png -

Here you are. You can now resize and move the different slice(s), style them -in the CSS modal window, and save right from here. For now, renaming the -dashboard or adding on a new slice is done through the dashboard edit view, -which is the same form as you used when you originally created the dashboard, -and is accessible by clicking the edit pen icon from the dashboard list -view (Menu -> Dashboards)

diff --git a/videos.html b/videos.html index bc4628ada1b..7c43f211bd8 100644 --- a/videos.html +++ b/videos.html @@ -60,6 +60,9 @@ + + +
@@ -78,52 +81,10 @@