may 27, 2025
Apache Superset: Frequently Asked Questions (FAQs)
Frequently Asked Questions
Is it possible to join/query multiple tables at once?
Not in the Explore or visualisation UI. A Superset SQLAlchemy datasource can only be a single table or view.
When working with multiple tables, a common solution is to materialise a table that contains all the fields required for your analysis, typically through some scheduled batch process.
A view is a simple logical layer that abstracts arbitrary SQL queries as a virtual table. This allows you to join and union multiple tables and apply certain transformations using arbitrary SQL expressions. The main limitation is the performance of your database, since Superset effectively runs a query on top of your view. A good practice is to limit joins on your main large table to only one or a few small tables, and to avoid using GROUP BY where possible, as Superset performs its own GROUP BY, and doubling the work can impact performance.
Whether you use a table or a view, a key consideration is whether your database is fast enough to serve it interactively to ensure a good user experience in Superset.
However, if you are using SQL Lab, this restriction does not apply — you can write SQL queries to join multiple tables, provided your DB account has access to them.
How big can my data source be?
It can be huge! Superset acts as a thin layer on top of your databases or data processing engines.
As mentioned above, the key factor is whether your database can execute queries and return results within a timeframe acceptable to your users. Many distributed databases are capable of running queries that scan terabytes of data interactively.
Why has the waiting time for my enquiries expired ?
There are several reasons why a query might time out.
By default, Superset allows long-running queries in SQL Lab to execute for up to 6 hours. If you need to increase the query execution time, you can set the timeout in the configuration. For example:
If you’re encountering timeouts (e.g. 504 Gateway Time-out) while loading a dashboard or an Explore chart, it’s likely that you’re behind a gateway or proxy server (such as Nginx). If the gateway doesn’t receive a timely response from the Superset server (which is handling the long query), it will return a 504 status code directly to the client.
Superset implements a client-side timeout mechanism to handle this. If a query does not return within the client-side timeout (default is 60 seconds), Superset will show a warning message to avoid triggering a gateway timeout. If your gateway has a higher timeout threshold, you can adjust the client-side timeout in superset_config.py:
Why Isn’t themap displaying in the geospatial visualisation?
You need to register for a free account at Mapbox.com, obtain an API key, and add it to your .env and .env-non-dev files under the MAPBOX_API_KEY setting:
How to add dynamic filters to the toolbar?
Use the Filter Box widget — create a chart using it and add it to your dashboard.
The Filter Box widget allows you to define a query that populates dropdown lists which can then be used for filtering. To create a list of distinct values, Superset runs the query and sorts the result based on the metric you provide, in descending order.
The widget also includes a Time Filter checkbox, which enables time-based filtering capabilities on the dashboard. Once checked and the widget is refreshed, you’ll see “From” and “To” dropdowns appear.
By default, the filtering will apply to all slices built on top of a datasource that has a column with the same name as the one used in the filter. It’s also required that the column is marked as filterable in the Columns tab of the dataset editor.
But what if you don’t want certain widgets to be affected by dashboard-level filtering? You can achieve this by editing the dashboard and modifying the metadata JSON field in the form — specifically, the filter_immune_slices key. This key accepts an array of slice IDs that should never be impacted by global filters on the dashboard.
In the large JSON blob mentioned above, slices 324, 65, and 92 will not be affected by any dashboard-level filtering.
Now, take note of the filter_immune_slice_fields key. This allows you to be more specific by defining, for a given slice_id, which filter fields should be ignored.
Also note the use of the special keyword __time_range, which is reserved for handling the time range filtering described above.
But what happens when working with slices from different tables or databases? If the column name is shared, the filter will be applied — it’s that simple.
How to limit the refresh time on the toolbar?
By default, the dashboard auto-refresh feature allows each chart (slice) to be re-queried automatically according to the specified schedule. However, there are situations where you may not want all slices to refresh — particularly when some data updates infrequently or certain queries are resource-intensive.
To exclude specific slices from the timed refresh process, you can add the timed_refresh_immune_slices key to the dashboard’s metadata JSON field. This key should contain a list of slice IDs that should not be refreshed on schedule.
In the example above, if a timed refresh is set for the dashboard, every slice except slice 324 will be automatically re-queried according to the schedule.
Each slice will also refresh with a slight delay between them. You can disable this staggering by setting stagger_refresh to false, and you can adjust the delay period by setting the stagger_time value (in milliseconds) in the dashboard’s metadata JSON field.
In this case, the entire dashboard will refresh at once if periodic auto-refresh is enabled. The 2.5-second staggering delay will be ignored.
Why does «flask fab» or Superset hang/freeze/become unresponsive on startup (when my home directory is mounted via NFS)?
By default, Superset creates and uses an SQLite database at ~/.superset/superset.db. SQLite is known to perform poorly when used over NFS, due to unreliable file locking mechanisms in NFS.
You can override this path by setting the SUPERSET_HOME environment variable.
Another workaround is to change the location where Superset stores the SQLite database by adding the following to superset_config.py:
What should i do if the table schema has changed?
Table schemas evolve, and Superset needs to reflect those changes. It’s quite common in the dashboard lifecycle to add a new dimension or metric. To make Superset detect your new columns, simply go to Data → Datasets, click the edit icon next to the dataset whose schema has changed, and click Sync columns from source on the Columns tab.
Behind the scenes, Superset will merge in the new columns. After that, you can re-edit the table to configure the Columns tab, check the appropriate boxes, and save it again.
What database engine can I use as the backend for Superset?
To clarify, the database backend refers to the OLTP database that Superset uses to store its internal information, such as your user list, chart definitions, and dashboards.
Superset is tested with MySQL, PostgreSQL, and SQLite as its backend. It’s recommended to deploy Superset in production using one of these database servers.
Using columnar stores or non-OLTP databases like Vertica, Redshift, or Presto as the backend simply won’t work, as these databases are not designed for that type of workload. Installing Superset with Oracle, Microsoft SQL Server, or other OLTP databases might work, but these configurations are not officially tested.
Note that virtually any database with a SQLAlchemy integration should work perfectly as a datasource for Superset — just not as the OLTP backend.
How to set a default filter on a dashboard?
Simply apply the filter and save the dashboard while the filter is active.
Is there a way to force specific colours?
This is possible on a per-dashboard basis by providing a label-to-colour mapping in the dashboard’s JSON metadata using the label_colors key.
Does Superset work with [some database engine]?
For a database engine to be supported in Superset via a SQLAlchemy connector, it must have a Python-compatible SQLAlchemy dialect and a corresponding DBAPI driver. A database with limited SQL support may still work — for example, Druid can be connected via a SQLAlchemy connector, even though it doesn’t support joins or subqueries.
Another key element for database support is the Superset Database Engine Specification interface. This interface allows for database-specific configuration and logic that go beyond SQLAlchemy and DBAPI. It covers features such as:
- SQL functions for date manipulation, allowing Superset to query different levels of time granularity for time series.
- Whether the engine supports subqueries. If set to false, Superset can use a two-phase querying approach to work around this limitation.
- Methods for handling logs and determining query progress percentage.
- Technical details for managing cursors and connections if the driver doesn’t conform to standard DBAPI behaviour.
Beyond using a SQLAlchemy connector, it is also technically possible — though significantly more complex — to extend Superset by writing a custom connector. The only example of this to date is the Druid connector, which is now being phased out thanks to Druid’s growing SQL support and the availability of a DBAPI driver and SQLAlchemy dialect.
If the database you intend to integrate offers any level of SQL support, it’s generally preferable to go the SQLAlchemy route. Keep in mind that to support a custom connector, the database must support OLAP-style queries and typical SQL operations such as:
- Data aggregation
- Applying filters
- Using HAVING filters
- Schema awareness, including column names and data types
Does Superset offer a public API?
Yes, Superset provides a public REST API, and the surface of this formal API is steadily expanding.
Some of the initial ideas and the /api/v1 endpoint set were originally outlined in SIP-17, and the API continues to evolve to support more and more use cases.
The available API is documented using Swagger, and the documentation can be made accessible at /swagger/v1 by enabling the following flag in superset_config.py:
There are other undocumented (private) methods of programmatic interaction with Superset. These are not guaranteed to be stable and are not recommended for long-term use, but they might temporarily suit your specific use case:
- Using the ORM (SQLAlchemy) directly
- Using the internal FAB ModelView API (deprecated in Superset)
- Modifying the source code in your own fork
What does the Hours Offset do in «Edit dataset» ?
In the «Edit Dataset» view, you can specify a time offset. This field allows you to set the number of hours to be added to or subtracted from the time column. This can be used, for example, to convert UTC time to local time.
