QT/superset2
1
0
Fork 0
mirror of https://github.com/apache/superset.git synced 2026-08-05 05:22:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(build): migrate from Prettier to Oxfmt for performant code formatting (#42434)

Browse Source
This commit is contained in:
Đỗ Trọng Hải
2026-08-04 00:27:05 +07:00
committed by GitHub
parent 10f7927603
commit e4ef84ca72
2328 changed files with 90728 additions and 32682 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
docs/user_docs_versioned_docs/version-6.1.0/using-superset/creating-your-first-dashboard.mdx
View File

@@ -5,13 +5,13 @@ sidebar_position: 1
version: 1
---
import useBaseUrl from "@docusaurus/useBaseUrl";
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
(data analysts, business analysts, data
scientists, etc).
:::tip
@@ -37,22 +37,44 @@ 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/>
<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/>
<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/>
<img
src={useBaseUrl(
'/img/tutorial/tutorial_03a_database_connection_string_link.png',
)}
width="600"
/>
<br />
<br />
Please note, if you are trying to connect to another locally running database (whether on host or another container), and you get the message `The port is closed.`, then you need to adjust the HOST to `host.docker.internal`
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/>
<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)
@@ -76,13 +98,13 @@ 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" )} />
<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" )} />
<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.
@@ -105,15 +127,15 @@ To install Superset as a PWA, look for the install icon in your browser's addres
### 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:
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))
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" )} />
<img src={useBaseUrl('/img/tutorial/tutorial_column_properties.png')} />
### Superset semantic layer
@@ -121,59 +143,62 @@ Superset has a thin semantic layer that adds many quality of life improvements f
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.
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" )} />
<img src={useBaseUrl('/img/tutorial/tutorial_sql_metric.png')} />
You can also certify metrics if you'd like for your team in this view.
1. 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.
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" )} />
<img src={useBaseUrl('/img/tutorial/tutorial_calculated_column.png')} />
:::resources
- [Using Metrics and Calculated Columns](https://docs.preset.io/docs/using-metrics-and-calculated-columns) - In-depth guide to the semantic layer
- [Blog: Understanding the Superset Semantic Layer](https://preset.io/blog/understanding-superset-semantic-layer/)
- [Blog: Unlocking the Power of Virtual Datasets](https://preset.io/blog/unlocking-the-power-of-virtual-datasets-in-apache-superset/)
:::
:::
### 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.
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/>
<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.
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.
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" )} />
<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" )} />
<img src={useBaseUrl('/img/tutorial/tutorial_explore_settings.jpg')} />
### Creating a slice and dashboard
@@ -184,26 +209,32 @@ To save your chart, first click the **Save** button. You can either:
In the following screenshot, we save the chart to a new "Superset Duper Sales Dashboard":
<img src={useBaseUrl("/img/tutorial/tutorial_save_slice.png" )} />
<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).
(the query, chart type, options selected, name, etc).
<img src={useBaseUrl("/img/tutorial/tutorial_first_dashboard.png" )} style={{width: "100%", maxWidth: "500px"}} />
<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.
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" />
<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"}} />
<img
src={useBaseUrl('/img/tutorial/tutorial_chart_resize.png')}
style={{ width: '100%', maxWidth: '500px' }}
/>
Click **Save** to persist the changes.
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
@@ -218,14 +249,14 @@ For detailed information on configuring dashboard access, see the
[Dashboard Access Control](/admin-docs/security/#dashboard-access-control) section in the
Security documentation.
<img src={useBaseUrl("/img/tutorial/tutorial_dashboard_access.png" )} />
<img src={useBaseUrl('/img/tutorial/tutorial_dashboard_access.png')} />
### Publishing a Dashboard
If you would like to make your dashboard available to other users, click on the `Draft` button next to the
title of your dashboard.
<img src={useBaseUrl("/img/tutorial/publish_button_dashboard.png" )} />
<img src={useBaseUrl('/img/tutorial/publish_button_dashboard.png')} />
:::warning
Draft dashboards are only visible to the dashboard owners and admins. Published dashboards are visible to all users with access to the underlying datasets or if RBAC is enabled, to the roles that have been granted access to the dashboard.
@@ -263,6 +294,7 @@ The **Table** chart type has several advanced capabilities worth knowing:
#### Conditional Formatting
Conditional formatting rules highlight cells based on their values. Rules can be applied to:
- **Numeric columns** — color cells above/below a threshold, or use a gradient across a range
- **String columns** — highlight cells matching specific text values or patterns
- **Boolean columns** — color cells that are `true` or `false`, or `null`/`not null`
@@ -284,6 +316,7 @@ Column headers display a tooltip with the column's **Description** from the data
#### Display Controls
In dashboard view mode (without entering Edit mode), charts with configurable display options expose a **Display Controls** panel accessible from the chart's context menu. This surfaces controls such as Time Grain, Time Column, and layer visibility for applicable chart types — making it easy to adjust a chart's view without going to Explore.
### AG Grid Interactive Table
The **AG Grid Interactive Table** chart type is Superset's fully-featured data grid, suitable for large paginated datasets where the standard Table chart is not enough.
@@ -294,12 +327,12 @@ AG Grid supports server-side column filters that query the full dataset — not
**Available filter types:**
| Column type | Filter options |
|---|---|
| Text | Contains, equals, starts with, ends with |
| Number | Equals, not equal, less than, greater than, between |
| Date | Before, after, between, blank |
| Set | Select from a list of distinct values |
| Column type | Filter options |
| ----------- | --------------------------------------------------- |
| Text | Contains, equals, starts with, ends with |
| Number | Equals, not equal, less than, greater than, between |
| Date | Before, after, between, blank |
| Set | Select from a list of distinct values |
**AND / OR logic:** Each column supports combining multiple conditions with AND or OR. Filters from different columns are always combined with AND.
@@ -363,6 +396,7 @@ Charts can display a "Last queried at" timestamp showing when the chart data was
When saving or adding a chart to a dashboard from Explore, you can select which tab it should land on using the tab tree-select dropdown in the "Add to dashboard" modal.
:::resources
- [Dashboard Customization](https://docs.preset.io/docs/dashboard-customization) - Advanced dashboard styling and layout options
- [Blog: BI Dashboard Best Practices](https://preset.io/blog/bi-dashboard-best-practices/)
:::
:::

28
docs/user_docs_versioned_docs/version-6.1.0/using-superset/embedding.mdx
View File

@@ -5,32 +5,32 @@ sidebar_position: 6
{/*
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
*/}
# Embedding Superset
Superset dashboards can be embedded directly in host applications using the `@superset-ui/embedded-sdk` package.
:::info Prerequisites
- The `EMBEDDED_SUPERSET` feature flag must be enabled.
- The embedding domain and allowed origins must be configured by an admin.
:::
:::
## Quick Start
@@ -46,7 +46,7 @@ Embed a dashboard:
import { embedDashboard } from '@superset-ui/embedded-sdk';
embedDashboard({
id: 'dashboard-uuid-here', // from Dashboard → Embed
id: 'dashboard-uuid-here', // from Dashboard → Embed
supersetDomain: 'https://superset.example.com',
mountPoint: document.getElementById('superset-container'),
fetchGuestToken: () => fetchTokenFromYourBackend(),
@@ -116,11 +116,11 @@ Must be `True` to enable the embedded SDK and the guest token endpoint. Without
The following URL parameters can be passed through the `urlParams` option in `dashboardUiConfig` or appended to the embedded iframe URL:
| Parameter | Values | Effect |
|-----------|--------|--------|
| `standalone` | `0`, `1`, `2`, `3` | `0`: normal; `1`: hide nav; `2`: hide nav + title; `3`: hide nav + title + tabs |
| `show_filters` | `0`, `1` | Show or hide the native filter bar |
| `expand_filters` | `0`, `1` | Start with filter bar expanded or collapsed |
| Parameter | Values | Effect |
| ---------------- | ------------------ | ------------------------------------------------------------------------------- |
| `standalone` | `0`, `1`, `2`, `3` | `0`: normal; `1`: hide nav; `2`: hide nav + title; `3`: hide nav + title + tabs |
| `show_filters` | `0`, `1` | Show or hide the native filter bar |
| `expand_filters` | `0`, `1` | Start with filter bar expanded or collapsed |
---
@@ -128,4 +128,4 @@ The following URL parameters can be passed through the `urlParams` option in `da
- **Guest tokens expire** — their lifetime is controlled by the `GUEST_TOKEN_JWT_EXP_SECONDS` config (default: 5 minutes). Refresh tokens before they expire using a token refresh mechanism in your host app.
- **Row-level security** — pass `rls` rules in the guest token request to restrict which rows are visible to the embedded user.
- **Allowed domains** — restrict which host origins can embed a dashboard by setting **Allowed Domains** per-dashboard in the *Embed* settings modal. Superset checks the request's `Referer` header against this list before serving the embedded view; an empty list allows any origin, so configure this explicitly for production.
- **Allowed domains** — restrict which host origins can embed a dashboard by setting **Allowed Domains** per-dashboard in the _Embed_ settings modal. Superset checks the request's `Referer` header against this list before serving the embedded view; an empty list allows any origin, so configure this explicitly for production.

67
docs/user_docs_versioned_docs/version-6.1.0/using-superset/exploring-data.mdx
View File

@@ -5,7 +5,7 @@ sidebar_position: 2
version: 1
---
import useBaseUrl from "@docusaurus/useBaseUrl";
import useBaseUrl from '@docusaurus/useBaseUrl';
## Exploring Data in Superset
@@ -32,12 +32,12 @@ explains how to enable this functionality for the examples database.
In the top menu, select **Settings ‣ Data ‣ Database Connections**. Find the **examples** database in the list and
select the **Edit** button.
<img src={useBaseUrl("/img/tutorial/edit-record.png" )} />
<img src={useBaseUrl('/img/tutorial/edit-record.png')} />
In the resulting modal window, switch to the **Advanced** tab and open **Security** section.
Then, tick the checkbox for **Allow file uploads to database**. End by clicking the **Finish** button.
<img src={useBaseUrl("/img/tutorial/allow-file-uploads.png" )} />
<img src={useBaseUrl('/img/tutorial/allow-file-uploads.png')} />
### Loading CSV Data
@@ -45,16 +45,16 @@ Download the CSV dataset to your computer from
[GitHub](https://raw.githubusercontent.com/apache-superset/examples-data/master/tutorial_flights.csv).
In the top menu, select **Settings ‣ Data ‣ Database Connections**. Then, **Upload file to database ‣ Upload CSV**.
<img src={useBaseUrl("/img/tutorial/upload_a_csv.png" )} />
<img src={useBaseUrl('/img/tutorial/upload_a_csv.png')} />
Then, select select the CSV file from your computer, select **Database** and **Schema**, and enter the **Table Name**
as _tutorial_flights_.
<img src={useBaseUrl("/img/tutorial/csv_to_database_configuration.png" )} />
<img src={useBaseUrl('/img/tutorial/csv_to_database_configuration.png')} />
Next enter the text _Travel Date_ into the **File settings ‣ Columns to be parsed as dates** field.
<img src={useBaseUrl("/img/tutorial/parse_dates_column.png" )} />
<img src={useBaseUrl('/img/tutorial/parse_dates_column.png')} />
Leaving all the other options in their default settings, select **Upload** at the bottom of the page.
@@ -70,7 +70,7 @@ By default, Apache Superset only shows the last week of data. In our example, we
of the data in the dataset. Click the **Time ‣ Time Range** section and change
the **Range Type** to **No Filter**.
<img src={useBaseUrl("/img/tutorial/no_filter_on_time_filter.png" )} />
<img src={useBaseUrl('/img/tutorial/no_filter_on_time_filter.png')} />
Click **Apply** to save.
@@ -80,24 +80,24 @@ example, we want to understand different Travel Classes, we select **Travel Clas
Next, we can specify the metrics we would like to see in our table with the **Metrics** option.
- `COUNT(*)`, which represents the number of rows in the table
(in this case, quantity of flights in each Travel Class)
(in this case, quantity of flights in each Travel Class)
- `SUM(Cost)`, which represents the total cost spent by each Travel Class
<img src={useBaseUrl("/img/tutorial/sum_cost_column.png" )} />
<img src={useBaseUrl('/img/tutorial/sum_cost_column.png')} />
Finally, select **Run Query** to see the results of the table.
<img src={useBaseUrl("/img/tutorial/tutorial_table.png" )} />
<img src={useBaseUrl('/img/tutorial/tutorial_table.png')} />
To save the visualization, click on **Save** in the top left of the screen. In the following modal,
- Select the **Save as**
option and enter the chart name as Tutorial Table (you will be able to find it again through the
**Charts** screen, accessible in the top menu).
option and enter the chart name as Tutorial Table (you will be able to find it again through the
**Charts** screen, accessible in the top menu).
- Select **Add To Dashboard** and enter
Tutorial Dashboard. Finally, select **Save & Go To Dashboard**.
Tutorial Dashboard. Finally, select **Save & Go To Dashboard**.
<img src={useBaseUrl("/img/tutorial/save_tutorial_table.png" )} />
<img src={useBaseUrl('/img/tutorial/save_tutorial_table.png')} />
### Dashboard Basics
@@ -109,7 +109,7 @@ On this dashboard you should see the table you created in the previous section.
dashboard** and then hover over the table. By selecting the bottom right hand corner of the table
(the cursor will change too), you can resize it by dragging and dropping.
<img src={useBaseUrl("/img/tutorial/resize_tutorial_table_on_dashboard.png" )} />
<img src={useBaseUrl('/img/tutorial/resize_tutorial_table_on_dashboard.png')} />
Finally, save your changes by selecting Save changes in the top right.
@@ -124,7 +124,7 @@ tutorial_flights again as a datasource, then click on the visualization type to
visualization menu. Select the **Pivot Table** visualization (you can filter by entering text in the
search box) and then **Create New Chart**.
<img src={useBaseUrl("/img/tutorial/create_pivot.png" )} />
<img src={useBaseUrl('/img/tutorial/create_pivot.png')} />
In the **Time** section, keep the Time Column as Travel Date (this is selected automatically as we
only have one time column in our dataset). Then select Time Grain to be month as having daily data
@@ -134,7 +134,7 @@ January 2011 and 30th June 2011 respectively by either entering directly the dat
calendar widget (by selecting the month name and then the year, you can move more quickly to far
away dates).
<img src={useBaseUrl("/img/tutorial/select_dates_pivot_table.png" )} />
<img src={useBaseUrl('/img/tutorial/select_dates_pivot_table.png')} />
Next, within the **Query** section, remove the default COUNT(\*) and add Cost, keeping the default
SUM aggregate. Note that Apache Superset will indicate the type of the metric by the symbol on the
@@ -146,7 +146,7 @@ selections we defined in the Time section.
Within **Columns**, first select Department and then Travel Class. All set – let’s **Run Query** to
see some data!
<img src={useBaseUrl("/img/tutorial/tutorial_pivot_table.png" )} />
<img src={useBaseUrl('/img/tutorial/tutorial_pivot_table.png')} />
You should see months in the rows and Department and Travel Class in the columns. Publish this chart
to your existing Tutorial Dashboard you created earlier.
@@ -161,7 +161,7 @@ time for the Time range select No filter as we want to look at entire dataset.
Within Metrics, remove the default `COUNT(*)` metric and instead add `AVG(Cost)`, to show the mean value.
<img src={useBaseUrl("/img/tutorial/average_aggregate_for_cost.png" )} />
<img src={useBaseUrl('/img/tutorial/average_aggregate_for_cost.png')} />
Next, select **Run Query** to show the data on the chart.
@@ -178,7 +178,7 @@ tab on the left hand pane. Within this pane, try changing the Color Scheme, remo
filter by selecting No in the Show Range Filter drop down and adding some labels using X Axis Label
and Y Axis Label.
<img src={useBaseUrl("/img/tutorial/tutorial_line_chart.png" )} />
<img src={useBaseUrl('/img/tutorial/tutorial_line_chart.png')} />
Once you’re done, publish the chart in your Tutorial Dashboard.
@@ -191,14 +191,14 @@ dashboards. Got into edit mode by selecting **Edit dashboard**.
Within the Insert components pane, drag and drop a Markdown box on the dashboard. Look for the blue
lines which indicate the anchor where the box will go.
<img src={useBaseUrl("/img/tutorial/blue_bar_insert_component.png" )} />
<img src={useBaseUrl('/img/tutorial/blue_bar_insert_component.png')} />
Now, to edit the text, select the box. You can enter text, in markdown format (see
[this Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) for
more information about this format). You can toggle between Edit and Preview using the menu on the
top of the box.
<img src={useBaseUrl("/img/tutorial/markdown.png" )} />
<img src={useBaseUrl('/img/tutorial/markdown.png')} />
To exit, select any other part of the dashboard. Finally, don’t forget to keep your changes using
**Save changes**.
@@ -213,7 +213,7 @@ If you would like to make your dashboard available to other users, simply select
title of your dashboard on the top left to change your dashboard to be in Published state. You can
also favorite this dashboard by selecting the star.
<img src={useBaseUrl("/img/tutorial/publish_dashboard.png" )} />
<img src={useBaseUrl('/img/tutorial/publish_dashboard.png')} />
### Annotations
@@ -230,7 +230,7 @@ Next, add an annotation by navigating to Manage ‣ Annotations and then create
selecting the green plus sign. Then, select the Volcanic Eruptions layer, add a short description
Grímsvötn and the eruption dates (23-25 May 2011) before finally saving.
<img src={useBaseUrl("/img/tutorial/edit_annotation.png" )} />
<img src={useBaseUrl('/img/tutorial/edit_annotation.png')} />
Then, navigate to the line chart by going to Charts then selecting Tutorial Line Chart from the
list. Next, go to the Annotations and Layers section and select Add Annotation Layer. Within this
@@ -241,11 +241,11 @@ dialogue:
- Set the Annotation Source as Superset annotation
- Specify the Annotation Layer as Volcanic Eruptions
<img src={useBaseUrl("/img/tutorial/annotation_settings.png" )} />
<img src={useBaseUrl('/img/tutorial/annotation_settings.png')} />
Select **Apply** to see your annotation shown on the chart.
<img src={useBaseUrl("/img/tutorial/annotation.png" )} />
<img src={useBaseUrl('/img/tutorial/annotation.png')} />
If you wish, you can change how your annotation looks by changing the settings in the Display
configuration section. Otherwise, select **OK** and finally **Save** to save your chart. If you keep
@@ -267,7 +267,7 @@ datasource and the **Line Chart** visualization type. Within the Time section, s
Next, in the query section, change the Metrics to the sum of Cost. Select **Run Query** to show the
chart. You should see the total cost per day for each month in October 2011.
<img src={useBaseUrl("/img/tutorial/advanced_analytics_base.png" )} />
<img src={useBaseUrl('/img/tutorial/advanced_analytics_base.png')} />
Finally, save the visualization as Tutorial Advanced Analytics Base, adding it to the Tutorial
Dashboard.
@@ -286,7 +286,7 @@ on 7 days and we avoid any ramp up period.
After displaying the chart by selecting **Run Query** you will see that the data is less variable
and that the series starts later as the ramp up period is excluded.
<img src={useBaseUrl("/img/tutorial/rolling_mean.png" )} />
<img src={useBaseUrl('/img/tutorial/rolling_mean.png')} />
Save the chart as Tutorial Rolling Mean and add it to the Tutorial Dashboard.
@@ -301,13 +301,15 @@ Next, in the Time Comparison subsection of **Advanced Analytics**, enter the Tim
“minus 1 week” (note this box accepts input in natural language). Run Query to see the new chart,
which has an additional series with the same values, shifted a week back in time.
<img src={useBaseUrl("/img/tutorial/time_comparison_two_series.png" )} />
<img src={useBaseUrl('/img/tutorial/time_comparison_two_series.png')} />
Then, change the **Calculation type** to Absolute difference and select **Run Query**. We can now
see only one series again, this time showing the difference between the two series we saw
previously.
<img src={useBaseUrl("/img/tutorial/time_comparison_absolute_difference.png" )} />
<img
src={useBaseUrl('/img/tutorial/time_comparison_absolute_difference.png')}
/>
Save the chart as Tutorial Time Comparison and add it to the Tutorial Dashboard.
@@ -319,7 +321,7 @@ As in the previous section, reopen the Tutorial Advanced Analytics Base chart.
Next, in the Python Functions subsection of **Advanced Analytics**, enter 7D, corresponding to seven
days, in the Rule and median as the Method and show the chart by selecting **Run Query**.
<img src={useBaseUrl("/img/tutorial/resample.png" )} />
<img src={useBaseUrl('/img/tutorial/resample.png')} />
Note that now we have a single data point every 7 days. In our case, the value showed corresponds to
the median value within the seven daily data points. For more information on the meaning of the
@@ -351,10 +353,11 @@ The **Custom** time range picker accepts natural language expressions alongside
These expressions are evaluated at query time, so saved charts always display data relative to the current date.
:::resources
- [Chart Walkthroughs](https://docs.preset.io/docs/chart-walkthroughs) - Detailed guides for most chart types
- [Blog: Why Apache ECharts is the Future of Apache Superset](https://preset.io/blog/2021-4-1-why-echarts/)
- [Blog: ECharts Time-Series Visualizations in Superset](https://preset.io/blog/echarts-time-series-visualizations-in-superset/)
- [Blog: Finding New Insights with Drill By](https://preset.io/blog/drill-by/)
- [Blog: From Drill Down to Drill By](https://preset.io/blog/drill-down-and-drill-by/)
- [Blog: Cross-Filtering in Apache Superset](https://preset.io/blog/cross-filtering-in-Superset-and-Preset/)
:::
:::

74
docs/user_docs_versioned_docs/version-6.1.0/using-superset/handlebars-chart.mdx
View File

@@ -28,11 +28,11 @@ Superset registers several custom helpers on top of the standard Handlebars buil
Formats a date value using [Day.js](https://day.js.org/) format strings.
```handlebars
{{dateFormat my_date format="MMMM YYYY"}}
{{dateFormat my_date format='MMMM YYYY'}}
```
| Option | Default | Description |
|--------|---------|-------------|
| Option | Default | Description |
| -------- | ------------ | --------------------------------- |
| `format` | `YYYY-MM-DD` | A Day.js-compatible format string |
---
@@ -52,11 +52,11 @@ Converts an object to a JSON string, or any other value to its string representa
Formats a number using locale-aware formatting.
```handlebars
{{formatNumber myNumber "en-US"}}
{{formatNumber myNumber 'en-US'}}
```
| Option | Default | Description |
|--------|---------|-------------|
| Option | Default | Description |
| -------- | ------- | --------------------- |
| `locale` | `en-US` | A BCP 47 language tag |
---
@@ -76,7 +76,7 @@ Parses a JSON string into an object that can be used in your template.
Groups an array of objects by a key, powered by [handlebars-group-by](https://github.com/nicktindall/handlebars-group-by).
```handlebars
{{#groupBy data "department"}}
{{#groupBy data 'department'}}
<h3>{{value}}</h3>
{{#each items}}
<p>{{this.name}}</p>
@@ -92,47 +92,47 @@ Superset also registers all helpers from the [just-handlebars-helpers](https://g
#### Comparison
| Helper | Description | Example |
|--------|-------------|---------|
| `eq` | Strict equality | `{{#if (eq status "active")}}` |
| `eqw` | Weak equality | `{{#if (eqw count "5")}}` |
| `neq` | Strict inequality | `{{#if (neq role "admin")}}` |
| `lt` | Less than | `{{#if (lt score 50)}}` |
| `lte` | Less than or equal | `{{#if (lte score 100)}}` |
| `gt` | Greater than | `{{#if (gt price 0)}}` |
| `gte` | Greater than or equal | `{{#if (gte age 18)}}` |
| Helper | Description | Example |
| ------ | --------------------- | ------------------------------ |
| `eq` | Strict equality | `{{#if (eq status "active")}}` |
| `eqw` | Weak equality | `{{#if (eqw count "5")}}` |
| `neq` | Strict inequality | `{{#if (neq role "admin")}}` |
| `lt` | Less than | `{{#if (lt score 50)}}` |
| `lte` | Less than or equal | `{{#if (lte score 100)}}` |
| `gt` | Greater than | `{{#if (gt price 0)}}` |
| `gte` | Greater than or equal | `{{#if (gte age 18)}}` |
#### Logical
| Helper | Description | Example |
|--------|-------------|---------|
| `and` | Logical AND | `{{#if (and isActive isVerified)}}` |
| `or` | Logical OR | `{{#if (or isAdmin isMod)}}` |
| `not` | Logical NOT | `{{#if (not isDisabled)}}` |
| `ifx` | Inline conditional | `{{ifx isActive "Yes" "No"}}` |
| Helper | Description | Example |
| ---------- | ----------------------------- | ---------------------------------------- |
| `and` | Logical AND | `{{#if (and isActive isVerified)}}` |
| `or` | Logical OR | `{{#if (or isAdmin isMod)}}` |
| `not` | Logical NOT | `{{#if (not isDisabled)}}` |
| `ifx` | Inline conditional | `{{ifx isActive "Yes" "No"}}` |
| `coalesce` | Returns first non-falsy value | `{{coalesce nickname name "Anonymous"}}` |
#### String
| Helper | Description | Example |
|--------|-------------|---------|
| `capitalize` | Capitalizes first letter | `{{capitalize name}}` |
| `uppercase` | Converts to uppercase | `{{uppercase status}}` |
| `lowercase` | Converts to lowercase | `{{lowercase email}}` |
| `truncate` | Truncates a string | `{{truncate description 100}}` |
| `contains` | Checks if string contains substring | `{{#if (contains tag "urgent")}}` |
| Helper | Description | Example |
| ------------ | ----------------------------------- | --------------------------------- |
| `capitalize` | Capitalizes first letter | `{{capitalize name}}` |
| `uppercase` | Converts to uppercase | `{{uppercase status}}` |
| `lowercase` | Converts to lowercase | `{{lowercase email}}` |
| `truncate` | Truncates a string | `{{truncate description 100}}` |
| `contains` | Checks if string contains substring | `{{#if (contains tag "urgent")}}` |
#### Math
| Helper | Description | Example |
|--------|-------------|---------|
| `add` | Addition | `{{add a b}}` |
| `subtract` | Subtraction | `{{subtract total discount}}` |
| Helper | Description | Example |
| ---------- | -------------- | ----------------------------- |
| `add` | Addition | `{{add a b}}` |
| `subtract` | Subtraction | `{{subtract total discount}}` |
| `multiply` | Multiplication | `{{multiply price quantity}}` |
| `divide` | Division | `{{divide total count}}` |
| `ceil` | Ceiling | `{{ceil value}}` |
| `floor` | Floor | `{{floor value}}` |
| `round` | Round | `{{round value}}` |
| `divide` | Division | `{{divide total count}}` |
| `ceil` | Ceiling | `{{ceil value}}` |
| `floor` | Floor | `{{floor value}}` |
| `round` | Round | `{{round value}}` |
For the full list of available helpers, see the [just-handlebars-helpers documentation](https://github.com/leapfrogtechnology/just-handlebars-helpers).

39
docs/user_docs_versioned_docs/version-6.1.0/using-superset/sql-templating.mdx
View File

@@ -7,19 +7,19 @@ keywords: [sql templating, jinja, sql lab, virtual datasets, dynamic queries]
{/*
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
*/}
@@ -101,12 +101,12 @@ Superset provides built-in macros for common use cases.
### User Context
| Macro | Description |
|-------|-------------|
| `{{ current_username() }}` | Returns the logged-in user's username |
| `{{ current_user_id() }}` | Returns the logged-in user's account ID |
| `{{ current_user_email() }}` | Returns the logged-in user's email |
| `{{ current_user_roles() }}` | Returns an array of the user's roles |
| Macro | Description |
| ---------------------------- | --------------------------------------- |
| `{{ current_username() }}` | Returns the logged-in user's username |
| `{{ current_user_id() }}` | Returns the logged-in user's account ID |
| `{{ current_user_email() }}` | Returns the logged-in user's email |
| `{{ current_user_roles() }}` | Returns an array of the user's roles |
**Example: Row-level filtering by user**
@@ -128,10 +128,10 @@ WHERE role IN {{ current_user_roles()|where_in }}
Access dashboard and chart filter values in your queries:
| Macro | Description |
|-------|-------------|
| Macro | Description |
| ------------------------------- | ------------------------------- |
| `{{ filter_values('column') }}` | Returns filter values as a list |
| `{{ get_filters('column') }}` | Returns filters with operators |
| `{{ get_filters('column') }}` | Returns filters with operators |
**Example: Using filter values**
@@ -148,8 +148,8 @@ The `where_in` filter converts the list to SQL format: `('value1', 'value2', 'va
For charts with time range filters:
| Macro | Description |
|-------|-------------|
| Macro | Description |
| --------------------------------- | -------------------------------------------------- |
| `{{ get_time_filter('column') }}` | Returns time filter with `from_expr` and `to_expr` |
**Example: Time-filtered virtual dataset**
@@ -214,9 +214,7 @@ Add to the Parameters menu:
```json
{
"_filters": [
{"col": "region", "op": "IN", "val": ["US", "EU"]}
]
"_filters": [{ "col": "region", "op": "IN", "val": ["US", "EU"] }]
}
```
@@ -269,6 +267,7 @@ Using `remove_filter=True` applies the filter in the inner query for better perf
- **Format SQL is Jinja-aware**: The "Format SQL" button in SQL Lab correctly preserves `{{ }}` and `{% %}` template syntax and applies your selected database's SQL dialect when formatting.
:::resources
- [Admin Guide: SQL Templating Configuration](/admin-docs/configuration/sql-templating)
- [Blog: Intro to Jinja Templating in Apache Superset](https://preset.io/blog/intro-jinja-templating-apache-superset/)
:::
:::

78
docs/user_docs_versioned_docs/version-6.1.0/using-superset/using-ai-with-superset.mdx
View File

@@ -47,6 +47,7 @@ Ask your AI assistant to browse what's available in your Superset instance:
- **Get chart and dashboard details** -- understand what a chart shows, its query, and configuration
**Example prompts:**
> "What datasets are available?"
> "Show me the columns in the sales_orders dataset"
> "Find dashboards related to revenue"
@@ -62,6 +63,7 @@ Describe the visualization you want and AI creates it for you:
- **Get Explore links** -- open any chart in Superset's Explore view for further refinement
**Example prompts:**
> "Create a bar chart showing monthly revenue by region from the sales dataset"
> "Update chart 42 to use a line chart instead"
> "Give me a link to explore this chart further"
@@ -84,6 +86,7 @@ Build dashboards from a collection of charts:
- **Add charts to existing dashboards** -- place a chart on an existing dashboard with automatic positioning
**Example prompts:**
> "Create a dashboard called 'Q4 Sales Overview' with charts 10, 15, and 22"
> "Add the revenue trend chart to the executive dashboard"
@@ -95,6 +98,7 @@ Discover what database connections are configured in your Superset instance:
- **Get database details** -- name, backend type (PostgreSQL, Snowflake, etc.), and connection status
**Example prompts:**
> "What databases are connected to Superset?"
> "Show me details about the data warehouse connection"
@@ -106,6 +110,7 @@ Build ad-hoc SQL datasets that can be used as the basis for charts:
- **Use immediately in charts** -- the returned dataset ID can be passed directly to chart creation
**Example prompts:**
> "Create a dataset from: SELECT region, SUM(revenue) as total_revenue FROM orders GROUP BY region"
> "Make a virtual dataset called 'monthly_signups' from the users table filtered to last 12 months"
@@ -118,6 +123,7 @@ Execute SQL directly through your AI assistant:
- **Save queries** -- save a SQL query to SQL Lab's Saved Queries for later reuse
**Example prompts:**
> "Run this query: SELECT region, SUM(revenue) FROM sales GROUP BY region"
> "Open SQL Lab with a query to show the top 10 customers by order count"
> "Save this query as 'Weekly Revenue Report'"
@@ -130,6 +136,7 @@ Pull the raw data behind any chart:
- **Inspect results** -- useful for verifying what a visualization shows or feeding data into other tools
**Example prompts:**
> "Get the data behind chart 42"
> "Export chart 15 data as CSV"
@@ -139,6 +146,7 @@ Pull the raw data behind any chart:
- **Instance info** -- get high-level statistics about your Superset instance (number of datasets, charts, dashboards)
**Example prompts:**
> "Is Superset healthy?"
> "How many dashboards are in this instance?"
@@ -232,56 +240,56 @@ Ask your admin for the MCP server URL and any authentication tokens you need.
### Exploration & Discovery
| Tool | Description |
|------|-------------|
| `health_check` | Verify the MCP server is running and connected |
| `get_instance_info` | Get instance statistics (dataset, chart, dashboard counts) |
| `get_schema` | Discover available charts, datasets, and dashboards with schema info |
| Tool | Description |
| ------------------- | -------------------------------------------------------------------- |
| `health_check` | Verify the MCP server is running and connected |
| `get_instance_info` | Get instance statistics (dataset, chart, dashboard counts) |
| `get_schema` | Discover available charts, datasets, and dashboards with schema info |
### Datasets
| Tool | Description |
|------|-------------|
| `list_datasets` | List datasets with filtering and search |
| `get_dataset_info` | Get dataset metadata (columns, metrics, filters) |
| `create_virtual_dataset` | Create a virtual dataset from a SQL query |
| Tool | Description |
| ------------------------ | ------------------------------------------------ |
| `list_datasets` | List datasets with filtering and search |
| `get_dataset_info` | Get dataset metadata (columns, metrics, filters) |
| `create_virtual_dataset` | Create a virtual dataset from a SQL query |
### Charts
| Tool | Description |
|------|-------------|
| `list_charts` | List charts with filtering and search |
| `get_chart_info` | Get chart metadata and configuration |
| `get_chart_data` | Retrieve chart data (JSON, CSV, or Excel) |
| `get_chart_preview` | Generate a chart preview (URL, ASCII, table, or Vega-Lite) |
| `get_chart_type_schema` | Get the configuration schema for a chart type |
| `generate_chart` | Create a new chart from a specification (defaults to preview mode — review before saving) |
| `update_chart` | Modify an existing chart's configuration (pass `generate_preview=False` to persist immediately instead of returning a preview URL) |
| `update_chart_preview` | Update a cached chart preview without saving |
| `generate_explore_link` | Generate an Explore URL for interactive visualization |
| Tool | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `list_charts` | List charts with filtering and search |
| `get_chart_info` | Get chart metadata and configuration |
| `get_chart_data` | Retrieve chart data (JSON, CSV, or Excel) |
| `get_chart_preview` | Generate a chart preview (URL, ASCII, table, or Vega-Lite) |
| `get_chart_type_schema` | Get the configuration schema for a chart type |
| `generate_chart` | Create a new chart from a specification (defaults to preview mode — review before saving) |
| `update_chart` | Modify an existing chart's configuration (pass `generate_preview=False` to persist immediately instead of returning a preview URL) |
| `update_chart_preview` | Update a cached chart preview without saving |
| `generate_explore_link` | Generate an Explore URL for interactive visualization |
### Dashboards
| Tool | Description |
|------|-------------|
| `list_dashboards` | List dashboards with filtering and search |
| `get_dashboard_info` | Get dashboard metadata and layout |
| `generate_dashboard` | Create a new dashboard with specified charts |
| `add_chart_to_existing_dashboard` | Add a chart to an existing dashboard |
| Tool | Description |
| --------------------------------- | -------------------------------------------- |
| `list_dashboards` | List dashboards with filtering and search |
| `get_dashboard_info` | Get dashboard metadata and layout |
| `generate_dashboard` | Create a new dashboard with specified charts |
| `add_chart_to_existing_dashboard` | Add a chart to an existing dashboard |
### SQL
| Tool | Description |
|------|-------------|
| `execute_sql` | Run a SQL query with RBAC enforcement |
| `save_sql_query` | Persist a SQL query to SQL Lab's saved queries |
| `open_sql_lab_with_context` | Open SQL Lab with a pre-populated query |
| Tool | Description |
| --------------------------- | ---------------------------------------------- |
| `execute_sql` | Run a SQL query with RBAC enforcement |
| `save_sql_query` | Persist a SQL query to SQL Lab's saved queries |
| `open_sql_lab_with_context` | Open SQL Lab with a pre-populated query |
### Databases
| Tool | Description |
|------|-------------|
| `list_databases` | List configured database connections |
| Tool | Description |
| ------------------- | ------------------------------------------------ |
| `list_databases` | List configured database connections |
| `get_database_info` | Get details about a specific database connection |
---