mirror of
https://github.com/apache/superset.git
synced 2026-05-12 19:35:17 +00:00
docs: Refactor Documentation Structure (#28161)
Co-authored-by: Evan Rusackas <evan@preset.io> Co-authored-by: Sam Firke <sfirke@users.noreply.github.com>
This commit is contained in:
Braum
212
docs/docs/using-superset/creating-your-first-dashboard.mdx
Normal file
212
docs/docs/using-superset/creating-your-first-dashboard.mdx
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
title: Creating Your First Dashboard
|
||||
hide_title: true
|
||||
sidebar_position: 1
|
||||
version: 1
|
||||
---
|
||||
|
||||
import useBaseUrl from "@docusaurus/useBaseUrl";
|
||||
|
||||
## Creating Your First Dashboard
|
||||
|
||||
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](http://preset.io/) maintains an updated set of end-user
|
||||
documentation at [docs.preset.io](https://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](/docs/installation/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:
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_01_add_database_connection.png")} width="600" />{" "} <br/><br/>
|
||||
|
||||
Then select your database type in the resulting modal:
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_02_select_database.png" )} width="600" />{" "} <br/><br/>
|
||||
|
||||
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:
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_03a_database_connection_string_link.png" )} width="600" />{" "} <br/><br/>
|
||||
|
||||
Once you've clicked that link you only need to specify two things (the database name and SQLAlchemy URI):
|
||||
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_03b_connection_string_details.png" )} width="600" />{" "} <br/><br/>
|
||||
|
||||
As noted in the text below the form, you should refer to the SQLAlchemy documentation on
|
||||
[creating new connection URIs](https://docs.sqlalchemy.org/en/12/core/engines.html#database-urls)
|
||||
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.
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_08_sources_tables.png" )} />
|
||||
|
||||
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.
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_09_add_new_table.png" )} />
|
||||
|
||||
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](https://en.wikipedia.org/wiki/ISO_8601))
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_column_properties.png" )} />
|
||||
|
||||
### 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.
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_sql_metric.png" )} />
|
||||
|
||||
You can also certify metrics if you'd like for your team in this view.
|
||||
|
||||
2. 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.
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_calculated_column.png" )} />
|
||||
|
||||
### 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.
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_launch_explore.png" )} /><br/><br/>
|
||||
|
||||
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.
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_explore_run.jpg" )} />
|
||||
|
||||
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.
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_explore_settings.jpg" )} />
|
||||
|
||||
### 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":
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_save_slice.png" )} />
|
||||
|
||||
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).
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_first_dashboard.png" )} style={{width: "100%", maxWidth: "500px"}} />
|
||||
|
||||
To resize the chart, start by clicking the Edit Dashboard button in the top right corner.
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_edit_button.png" )} width="300" />
|
||||
|
||||
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.
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_chart_resize.png" )} style={{width: "100%", maxWidth: "500px"}} />
|
||||
|
||||
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](/docs/configuration/configuring-superset#feature-flags) 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.
|
||||
|
||||
<img src={useBaseUrl("/img/tutorial/tutorial_dashboard_access.png" )} />
|
||||
|
||||
### 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`
|
||||
Reference in New Issue
Block a user