QT/superset2
1
0
Fork 0
mirror of https://github.com/apache/superset.git synced 2026-05-07 17:04:58 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
7f66807a57a0ae45a6c8d8f51464e6adf1d534f2
superset2/tutorial.html
Maxime Beauchemin edc8d64f60 new docs
2017-01-26 08:55:58 -08:00

415 lines
23 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Tutorial for Superset Administrators &mdash; Superset&#39;s documentation documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="index" title="Index"
href="genindex.html"/>
<link rel="search" title="Search" href="search.html"/>
<link rel="top" title="Superset&#39;s documentation documentation" href="index.html"/>
<link rel="next" title="Security" href="security.html"/>
<link rel="prev" title="Installation &amp; Configuration" href="installation.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> Superset's documentation
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation &amp; Configuration</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Tutorial for Superset Administrators</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#connecting-to-a-new-database">Connecting to a new database</a></li>
<li class="toctree-l2"><a class="reference internal" href="#adding-a-new-table">Adding a new table</a></li>
<li class="toctree-l2"><a class="reference internal" href="#exploring-your-data">Exploring your data</a></li>
<li class="toctree-l2"><a class="reference internal" href="#creating-a-slice-and-dashboard">Creating a slice and dashboard</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="security.html">Security</a></li>
<li class="toctree-l1"><a class="reference internal" href="sqllab.html">SQL Lab</a></li>
<li class="toctree-l1"><a class="reference internal" href="videos.html">Videos</a></li>
<li class="toctree-l1"><a class="reference internal" href="gallery.html">Gallery</a></li>
<li class="toctree-l1"><a class="reference internal" href="druid.html">Druid</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Superset's documentation</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li>Tutorial for Superset Administrators</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="tutorial-for-superset-administrators">
<h1>Tutorial for Superset Administrators<a class="headerlink" href="#tutorial-for-superset-administrators" title="Permalink to this headline"></a></h1>
<p>This tutorial targets a Superset administrator: someone configuring Superset
for an organization on behalf of users. We&#8217;ll show you how to connect Superset
to a new database and configure a table in that database for analysis. You&#8217;ll
also explore the data you&#8217;ve exposed and add a visualization to a dashboard
so that you get a feel for the end-to-end user experience.</p>
<div class="section" id="connecting-to-a-new-database">
<h2>Connecting to a new database<a class="headerlink" href="#connecting-to-a-new-database" title="Permalink to this headline"></a></h2>
<p>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
<a class="reference external" href="https://wiki.postgresql.org/wiki/Sample_Databases">sample PostgreSQL datasets</a>
into a fresh DB, or configure the
<a class="reference external" href="https://github.com/dylburger/noaa-ghcn-weather-data">example weather data</a>
we use here.</p>
<p>Under the <strong>Sources</strong> menu, select the <em>Databases</em> option:</p>
<a class="reference internal image-reference" href="_images/tutorial_01_sources_database.png"><img alt="_images/tutorial_01_sources_database.png" src="_images/tutorial_01_sources_database.png" style="width: 316.4px; height: 187.6px;" /></a>
<p>On the resulting page, click on the green plus sign, near the top left:</p>
<a class="reference internal image-reference" href="_images/tutorial_02_add_database.png"><img alt="_images/tutorial_02_add_database.png" src="_images/tutorial_02_add_database.png" style="width: 369.6px; height: 232.4px;" /></a>
<p>You can configure a number of advanced options on this page, but for
this walkthrough, you’ll only need to do <strong>two things</strong>:</p>
<ol class="arabic simple">
<li>Name your database connection:</li>
</ol>
<a class="reference internal image-reference" href="_images/tutorial_03_database_name.png"><img alt="_images/tutorial_03_database_name.png" src="_images/tutorial_03_database_name.png" style="width: 554.4px; height: 98.0px;" /></a>
<ol class="arabic simple" start="2">
<li>Provide the SQLAlchemy Connection URI and test the connection:</li>
</ol>
<a class="reference internal image-reference" href="_images/tutorial_04_sqlalchemy_connection_string.png"><img alt="_images/tutorial_04_sqlalchemy_connection_string.png" src="_images/tutorial_04_sqlalchemy_connection_string.png" style="width: 1071.0px; height: 196.0px;" /></a>
<p>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
<a class="reference external" href="http://docs.sqlalchemy.org/en/rel_1_0/core/engines.html#database-urls">creating new connection URIs</a>
for your target database.</p>
<p>Click the <strong>Test Connection</strong> button to confirm things work end to end.
Once Superset can successfully connect and authenticate, you should see
a popup like this:</p>
<a class="reference internal image-reference" href="_images/tutorial_05_connection_popup.png"><img alt="_images/tutorial_05_connection_popup.png" src="_images/tutorial_05_connection_popup.png" style="width: 562.0px; height: 277.0px;" /></a>
<p>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:</p>
<a class="reference internal image-reference" href="_images/tutorial_06_list_of_tables.png"><img alt="_images/tutorial_06_list_of_tables.png" src="_images/tutorial_06_list_of_tables.png" style="width: 963.2px; height: 127.4px;" /></a>
<p>If the connection looks good, save the configuration by clicking the <strong>Save</strong>
button at the bottom of the page:</p>
<a class="reference internal image-reference" href="_images/tutorial_07_save_button.png"><img alt="_images/tutorial_07_save_button.png" src="_images/tutorial_07_save_button.png" style="width: 187.6px; height: 85.4px;" /></a>
</div>
<div class="section" id="adding-a-new-table">
<h2>Adding a new table<a class="headerlink" href="#adding-a-new-table" title="Permalink to this headline"></a></h2>
<p>Now that you’ve configured a database, you’ll need to add specific tables
to Superset that you’d like to query.</p>
<p>Under the <strong>Sources</strong> menu, select the <em>Tables</em> option:</p>
<a class="reference internal image-reference" href="_images/tutorial_08_sources_tables.png"><img alt="_images/tutorial_08_sources_tables.png" src="_images/tutorial_08_sources_tables.png" style="width: 315.0px; height: 187.6px;" /></a>
<p>On the resulting page, click on the green plus sign, near the top left:</p>
<a class="reference internal image-reference" href="_images/tutorial_09_add_new_table.png"><img alt="_images/tutorial_09_add_new_table.png" src="_images/tutorial_09_add_new_table.png" style="width: 322.0px; height: 232.4px;" /></a>
<p>You only need a few pieces of information to add a new table to Superset:</p>
<ul class="simple">
<li>The name of the table</li>
</ul>
<a class="reference internal image-reference" href="_images/tutorial_10_table_name.png"><img alt="_images/tutorial_10_table_name.png" src="_images/tutorial_10_table_name.png" style="width: 772.8px; height: 130.2px;" /></a>
<ul class="simple">
<li>The target database from the <strong>Database</strong> drop-down menu (i.e. the one
you just added above)</li>
</ul>
<a class="reference internal image-reference" href="_images/tutorial_11_choose_db.png"><img alt="_images/tutorial_11_choose_db.png" src="_images/tutorial_11_choose_db.png" style="width: 387.8px; height: 229.6px;" /></a>
<ul class="simple">
<li>Optionally, the database schema. If the table exists in the “default” schema
(e.g. the <em>public</em> schema in PostgreSQL or Redshift), you can leave the schema
field blank.</li>
</ul>
<p>Click on the <strong>Save</strong> button to save the configuration:</p>
<a class="reference internal image-reference" href="_images/tutorial_07_save_button.png"><img alt="_images/tutorial_07_save_button.png" src="_images/tutorial_07_save_button.png" style="width: 187.6px; height: 85.4px;" /></a>
<p>When redirected back to the list of tables, you should see a message indicating
that your table was created:</p>
<a class="reference internal image-reference" href="_images/tutorial_12_table_creation_success_msg.png"><img alt="_images/tutorial_12_table_creation_success_msg.png" src="_images/tutorial_12_table_creation_success_msg.png" style="width: 1260.0px; height: 89.6px;" /></a>
<p>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.</p>
<p>Click on the edit button next to the table you’ve created:</p>
<a class="reference internal image-reference" href="_images/tutorial_13_edit_table_config.png"><img alt="_images/tutorial_13_edit_table_config.png" src="_images/tutorial_13_edit_table_config.png" style="width: 509.6px; height: 180.6px;" /></a>
<p>On the resulting page, click on the <strong>List Table Column</strong> 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:</p>
<ul class="simple">
<li>If you want users to group metrics by a specific field, mark it as <strong>Groupable</strong>.</li>
<li>If you need to filter on a specific field, mark it as <strong>Filterable</strong>.</li>
<li>Is this field something you’d like to get the distinct count of? Check the <strong>Count
Distinct</strong> box.</li>
<li>Is this a metric you want to sum, or get basic summary statistics for? The <strong>Sum</strong>,
<strong>Min</strong>, and <strong>Max</strong> columns will help.</li>
<li>The <strong>is temporal</strong> field should be checked for any date or time fields. We’ll cover
how this manifests itself in analyses in a moment.</li>
</ul>
<p>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:</p>
<img alt="_images/tutorial_14_field_config.png" src="_images/tutorial_14_field_config.png" />
<p>As with the configurations above, click the <strong>Save</strong> button to save these settings.</p>
</div>
<div class="section" id="exploring-your-data">
<h2>Exploring your data<a class="headerlink" href="#exploring-your-data" title="Permalink to this headline"></a></h2>
<p>To start exploring your data, simply click on the table name you just created in
the list of available tables:</p>
<img alt="_images/tutorial_15_click_table_name.png" src="_images/tutorial_15_click_table_name.png" />
<p>By default, you’ll be presented with a Table View:</p>
<img alt="_images/tutorial_16_datasource_chart_type.png" src="_images/tutorial_16_datasource_chart_type.png" />
<p>Let’s walk through a basic query to get the count of all records in our table.
First, we’ll need to change the <strong>Since</strong> filter to capture the range of our data.
You can use simple phrases to apply these filters, like &#8220;3 years ago&#8221;:</p>
<img alt="_images/tutorial_17_choose_time_range.png" src="_images/tutorial_17_choose_time_range.png" />
<p>The upper limit for time, the <strong>Until</strong> filter, defaults to &#8220;now&#8221;, which may or may
not be what you want.</p>
<p>Look for the Metrics section under the <strong>GROUP BY</strong> header, and start typing &#8220;Count&#8221;
- you’ll see a list of metrics matching what you type:</p>
<img alt="_images/tutorial_18_choose_metric.png" src="_images/tutorial_18_choose_metric.png" />
<p>Select the <em>COUNT(*)</em> metric, then click the green <strong>Query</strong> button near the top
of the explore:</p>
<img alt="_images/tutorial_19_click_query.png" src="_images/tutorial_19_click_query.png" />
<p>You’ll see your results in the table:</p>
<img alt="_images/tutorial_20_count_star_result.png" src="_images/tutorial_20_count_star_result.png" />
<p>Let’s group this by the <em>weather_description</em> field to get the count of records by
the type of weather recorded by adding it to the <em>Group by</em> section:</p>
<img alt="_images/tutorial_21_group_by.png" src="_images/tutorial_21_group_by.png" />
<p>and run the query:</p>
<img alt="_images/tutorial_22_group_by_result.png" src="_images/tutorial_22_group_by_result.png" />
<p>Let’s find a more useful data point: the top 10 times and places that recorded the
highest temperature in 2015.</p>
<p>We replace <em>weather_description</em> with <em>latitude</em>, <em>longitude</em> and <em>measurement_date</em> in the
<em>Group by</em> section:</p>
<img alt="_images/tutorial_23_group_by_more_dimensions.png" src="_images/tutorial_23_group_by_more_dimensions.png" />
<p>And replace <em>COUNT(*)</em> with <em>max__measurement_flag</em>:</p>
<img alt="_images/tutorial_24_max_metric.png" src="_images/tutorial_24_max_metric.png" />
<p>The <em>max__measurement_flag</em> metric was created when we checked the box under <strong>Max</strong> and
next to the <em>measurement_flag</em> field, indicating that this field was numeric and that
we wanted to find its maximum value when grouped by specific fields.</p>
<p>In our case, <em>measurement_flag</em> 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 <em>weather_description</em> is equal to &#8220;Maximum temperature&#8221;, which we do in
the <strong>Filters</strong> section at the bottom of the explore:</p>
<img alt="_images/tutorial_25_max_temp_filter.png" src="_images/tutorial_25_max_temp_filter.png" />
<p>Finally, since we only care about the top 10 measurements, we limit our results to
10 records using the <em>Row limit</em> option under the <strong>Options</strong> header:</p>
<img alt="_images/tutorial_26_row_limit.png" src="_images/tutorial_26_row_limit.png" />
<p>We click <strong>Query</strong> and get the following results:</p>
<img alt="_images/tutorial_27_top_10_max_temps.png" src="_images/tutorial_27_top_10_max_temps.png" />
<p>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.</p>
<p>You may want to do a couple more things with this measure:</p>
<ul class="simple">
<li>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 (<em>Edit Table
Config &gt; List Sql Metric &gt; Edit Metric &gt; D3Format</em>)</li>
<li>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 (<em>Edit Table Config &gt; List Sql Metric &gt; Edit
Metric &gt; SQL Expression</em>)</li>
</ul>
<p>For now, though, let’s create a better visualization of these data and add it to
a dashboard.</p>
<p>We change the Chart Type to &#8220;Distribution - Bar Chart&#8221;:</p>
<img alt="_images/tutorial_28_bar_chart.png" src="_images/tutorial_28_bar_chart.png" />
<p>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:</p>
<img alt="_images/tutorial_29_bar_chart_series_metrics.png" src="_images/tutorial_29_bar_chart_series_metrics.png" />
<p>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:</p>
<a class="reference internal image-reference" href="_images/tutorial_30_bar_chart_results.png"><img alt="_images/tutorial_30_bar_chart_results.png" src="_images/tutorial_30_bar_chart_results.png" style="width: 956.9px; height: 435.4px;" /></a>
</div>
<div class="section" id="creating-a-slice-and-dashboard">
<h2>Creating a slice and dashboard<a class="headerlink" href="#creating-a-slice-and-dashboard" title="Permalink to this headline"></a></h2>
<p>This view might be interesting to researchers, so let’s save it. In Superset,
a saved query is called a <strong>Slice</strong>.</p>
<p>To create a slice, click the <strong>Save as</strong> button near the top-left of the
explore:</p>
<img alt="_images/tutorial_19_click_query.png" src="_images/tutorial_19_click_query.png" />
<p>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:</p>
<a class="reference internal image-reference" href="_images/tutorial_31_save_slice_to_dashboard.png"><img alt="_images/tutorial_31_save_slice_to_dashboard.png" src="_images/tutorial_31_save_slice_to_dashboard.png" style="width: 432.6px; height: 268.8px;" /></a>
<p>Click Save, which will direct you back to your original query. We see that
our slice and dashboard were successfully created:</p>
<a class="reference internal image-reference" href="_images/tutorial_32_save_slice_confirmation.png"><img alt="_images/tutorial_32_save_slice_confirmation.png" src="_images/tutorial_32_save_slice_confirmation.png" style="width: 611.8px; height: 105.7px;" /></a>
<p>Let’s check out our new dashboard. We click on the <strong>Dashboards</strong> menu:</p>
<img alt="_images/tutorial_33_dashboard.png" src="_images/tutorial_33_dashboard.png" />
<p>and find the dashboard we just created:</p>
<img alt="_images/tutorial_34_weather_dashboard.png" src="_images/tutorial_34_weather_dashboard.png" />
<p>Things seemed to have worked - our slice is here!</p>
<a class="reference internal image-reference" href="_images/tutorial_35_slice_on_dashboard.png"><img alt="_images/tutorial_35_slice_on_dashboard.png" src="_images/tutorial_35_slice_on_dashboard.png" style="width: 464.8px; height: 397.6px;" /></a>
<p>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:</p>
<a class="reference internal image-reference" href="_images/tutorial_36_adjust_dimensions.gif"><img alt="_images/tutorial_36_adjust_dimensions.gif" src="_images/tutorial_36_adjust_dimensions.gif" style="width: 576.0px; height: 297.6px;" /></a>
<p>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.</p>
<p>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.</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="security.html" class="btn btn-neutral float-right" title="Security" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="installation.html" class="btn btn-neutral" title="Installation &amp; Configuration" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink