mirror of
https://github.com/apache/superset.git
synced 2026-04-07 18:35:15 +00:00
[docs] many improvements to the documentation / cleanup (#4817)
* fixed RSTs so images will show up on github * fresh screenshots on main page * removing irrelevant portions * moved a set of sections under 'Misc' * rebuilt the Gallery with all screenshots
This commit is contained in:
Maxime Beauchemin
committed by
GitHub
GitHub
parent
daf9a3bfb5
commit
4c268ec678
@@ -1,31 +1,31 @@
|
||||
Tutorial for Superset Administrators
|
||||
====================================
|
||||
Tutorial - Creating your first dashboard
|
||||
========================================
|
||||
|
||||
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
|
||||
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
|
||||
----------------------------
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
.. image:: images/tutorial/tutorial_01_sources_database.png
|
||||
:scale: 70%
|
||||
|
||||
On the resulting page, click on the green plus sign, near the top right:
|
||||
|
||||
.. image:: _static/img/tutorial/tutorial_02_add_database.png
|
||||
.. image:: images/tutorial/tutorial_02_add_database.png
|
||||
:scale: 70%
|
||||
|
||||
You can configure a number of advanced options on this page, but for
|
||||
@@ -33,12 +33,12 @@ this walkthrough, you’ll only need to do **two things**:
|
||||
|
||||
1. Name your database connection:
|
||||
|
||||
.. image:: _static/img/tutorial/tutorial_03_database_name.png
|
||||
.. image:: images/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
|
||||
.. image:: images/tutorial/tutorial_04_sqlalchemy_connection_string.png
|
||||
:scale: 70%
|
||||
|
||||
This example shows the connection string for our test weather database.
|
||||
@@ -51,19 +51,19 @@ 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
|
||||
.. image:: images/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
|
||||
.. image:: images/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
|
||||
.. image:: images/tutorial/tutorial_07_save_button.png
|
||||
:scale: 70%
|
||||
|
||||
Adding a new table
|
||||
@@ -74,25 +74,25 @@ 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
|
||||
.. image:: images/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
|
||||
.. image:: images/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
|
||||
.. image:: images/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
|
||||
.. image:: images/tutorial/tutorial_11_choose_db.png
|
||||
:scale: 70%
|
||||
|
||||
* Optionally, the database schema. If the table exists in the “default” schema
|
||||
@@ -101,13 +101,13 @@ You only need a few pieces of information to add a new table to Superset:
|
||||
|
||||
Click on the **Save** button to save the configuration:
|
||||
|
||||
.. image:: _static/img/tutorial/tutorial_07_save_button.png
|
||||
.. image:: images/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
|
||||
.. image:: images/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
|
||||
@@ -116,7 +116,7 @@ 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
|
||||
.. image:: images/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
|
||||
@@ -136,7 +136,7 @@ Here’s how we’ve configured fields for the weather data. Even for measures l
|
||||
weather measurements (precipitation, snowfall, etc.), it’s ideal to group and filter
|
||||
by these values:
|
||||
|
||||
.. image:: _static/img/tutorial/tutorial_14_field_config.png
|
||||
.. image:: images/tutorial/tutorial_14_field_config.png
|
||||
|
||||
As with the configurations above, click the **Save** button to save these settings.
|
||||
|
||||
@@ -146,17 +146,17 @@ 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
|
||||
.. image:: images/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
|
||||
.. image:: images/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
|
||||
.. image:: images/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.
|
||||
@@ -164,25 +164,25 @@ 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
|
||||
.. image:: images/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
|
||||
.. image:: images/tutorial/tutorial_19_click_query.png
|
||||
|
||||
You’ll see your results in the table:
|
||||
|
||||
.. image:: _static/img/tutorial/tutorial_20_count_star_result.png
|
||||
.. image:: images/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
|
||||
.. image:: images/tutorial/tutorial_21_group_by.png
|
||||
|
||||
and run the query:
|
||||
|
||||
.. image:: _static/img/tutorial/tutorial_22_group_by_result.png
|
||||
.. image:: images/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.
|
||||
@@ -190,11 +190,11 @@ 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
|
||||
.. image:: images/tutorial/tutorial_23_group_by_more_dimensions.png
|
||||
|
||||
And replace *COUNT(\*)* with *max__measurement_flag*:
|
||||
|
||||
.. image:: _static/img/tutorial/tutorial_24_max_metric.png
|
||||
.. image:: images/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
|
||||
@@ -206,16 +206,16 @@ precipitation and temperature). Therefore, we must filter our query only on reco
|
||||
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
|
||||
.. image:: images/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
|
||||
.. image:: images/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
|
||||
.. image:: images/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
|
||||
@@ -240,20 +240,20 @@ a dashboard.
|
||||
|
||||
We change the Chart Type to "Distribution - Bar Chart":
|
||||
|
||||
.. image:: _static/img/tutorial/tutorial_28_bar_chart.png
|
||||
.. image:: images/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
|
||||
.. image:: images/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
|
||||
.. image:: images/tutorial/tutorial_30_bar_chart_results.png
|
||||
:scale: 70%
|
||||
|
||||
Creating a slice and dashboard
|
||||
@@ -265,39 +265,39 @@ 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
|
||||
.. image:: images/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
|
||||
.. image:: images/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
|
||||
.. image:: images/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
|
||||
.. image:: images/tutorial/tutorial_33_dashboard.png
|
||||
|
||||
and find the dashboard we just created:
|
||||
|
||||
.. image:: _static/img/tutorial/tutorial_34_weather_dashboard.png
|
||||
.. image:: images/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
|
||||
.. image:: images/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
|
||||
.. image:: images/tutorial/tutorial_36_adjust_dimensions.gif
|
||||
:scale: 120%
|
||||
|
||||
After adjusting the size, you’ll be asked to click on the icon near the
|
||||
|
||||
Reference in New Issue
Block a user