Feature Flags in Apache Superset and Preset

A feature flag, in the simplest of terms, is a software development technique that allows developers to turn features or functionality on and off at runtime without deploying new code. Apache Superset is full of these feature flags, enabling developers (and sometimes customers, in the case of Preset) to control the enabling or release of new features to specific deployments or groups of users. This allows developers or test new functionality, and easily roll back problematic changes.

In Superset, we have a whole slew of settings available to those who maintain or deploy instances of Superset. These are all found in the config.py file and are available for you to experiment with. We’ll go into the different types of flags, the philosophies around creating/maintaining/removing them from the codebase, and define some of the key ones you should be aware of.

What makes a flag a flag?

Superset has a whole slew of configuration options, some of which are feature flags, while some are not. So what exactly is the rubric for deciding what’s a flag, and what’s simply a configuration setting? Well, there are two key characteristics:

1. Feature flags are boolean. We’re simply flipping things on and off. If there’s some more detailed configuration object, parameters to set, etc., then it’s simply not a flag.

2. Flags affect the user experience. This is to say that there are plenty of boolean settings elsewhere in the config, but these are used to configure how Superset operates under the hood, usually to change how Superset is deployed, rather than how it’s presented to the end user.

Using (and overriding) feature flags

As you’ll see when looking through Superset’s configuration, the feature flags themselves are defined in there in DEFAULT_FEATURE_FLAGS. If you manage a Superset instance and simply want to flip a flag, you can certainly just change the value here. However, this is really just the core of the feature flag onion in Superset. These flags (and settings, therefore) can be overridden in a few ways.

If you’re using Docker, you’ll find that /docker/pythonpath_dev/superset_config.py contains a FEATURE_FLAGS object that gets merged onto the aforementioned DEFAULT_FEATURE_FLAGS, so you can make overrides here as well.

If you prefer to start up Superset via the command line, you can also set a flag via an environment variable by simply prefixing the flag name with SUPERSET_FEATURE_. For example, you could enable/disable the ENABLE_TEMPLATE_PROCESSING flag by setting SUPERSET_FEATURE_ENABLE_TEMPLATE_PROCESSING as an environment variable before starting Superset.

You’ll also find some additional functions to leverage these feature flags when if you’re developing or customizing Superset, but that’s beyond the scope of this article.

While it was mentioned previously, it’s worth mentioning again that the more flags there are in any codebase, the more combinations there are. The number of code paths enabled or disabled by various flags can get quite complex in nature. I would advise you to test and enable features incrementally, and if you do encounter any bugs or edge cases that seem relevant to a given feature flag, please report which flags you’ve changed when filing or reporting any issues. It helps more than you would think!

Now that we’ve covered all that, you’re probably here to understand what these things really are, so let’s get right to it!

The species and lifecycles of Feature Flags in Superset

There are a few main types of feature flags that we support in Superset. These categories and all of the feature flags that go into them can be viewed in FEATURE_FLAGS.md 🔗 in the codebase. That said, I’ll lend a little more color to those category definitions here, and then we’ll get into the flags themselves further below:

In Development

These flags are often added to the codebase without much fanfare or official process. Their purpose in life is to get a larger feature into the world more smoothly by acting as a feature release gate. This allows developers to merge several pull requests for a feature without having as much concern about an individual change negatively (or confusingly) affecting the user experience since the new feature should have no impact on the UX unless the feature is turned on. You might not want to enable these flags, unless you want to try alpha-stage features, or contribute to their development — enable at your own risk!

These flags should be considered non-permanent in nature. The flag can be implemented at the beginning of a feature’s development and kept in effect as long as needed. Once the bulk of the feature is built and stabilized, it can go one of two routes for its end-of-life. If the flag was introduced and removed between official Apache release cycles, it can be considered a non-breaking change to simply delete it. If, however, the flag is released as part of an Apache release it would typically be most prudent to move it to the “In Testing” category and remove it as part of the next major version of Superset.

In Testing

Feature flags that are in testing fall into two camps - they’re either sure-to-be-mainstream features that are in a “beta” phase of testing/feedback, or they’re up for consideration to see if they make the cut in terms of product adoption. Use these flags with a modicum of caution… they should be safe to use, but might have edge-case bugs, or might not be around for the long haul.

While non-permanent in nature, these flags should be created and released sparingly, as they tend to create an exponential degree of difficulty in testing/shipping deployments or releases of Superset. Different combinations of these flags can cause unexpected complexities, so once a feature is deemed ready for general adoption, it should be removed by Apache consensus. This consensus will typically happen via Superset’s dev mailing list as we approach a major version, wherein it will be moved to the “Stable” category and potentially defaulted to “True” or removed from the codebase.

Stable

These are flags that are battle-tested by Preset and/or other organizations and individuals deploying Superset and are generally considered ready for production. They’re here because not everyone managing Superset might want to enable or support these features. in other words, these are most likely here for the long haul.

These flags also pose a combinatoric risk factor - the more they are, the more likely we are to encounter edge cases with various combinations. Efforts may be made in major version release windows to consolidate these flags, change their defaults, or (in some cases) remove them, but these instances are rare.

Deprecated

These are flags that are being phased out. By placing these flags here, we’re hoping to provide ample notice that these flags will be removed in the next (or an upcoming) major release of Superset (e.g. X.0.0) since removing them otherwise would constitute a breaking change and violate our semantic versioning (SemVer) policies.

These removals are in most cases agreed upon by official Apache consensus. Their removal does not necessarily herald the removal of a feature - many times flags are removed to cement a feature in place. Whether the flag is permanently sent to True or False, this categorization warns anyone managing deployments that these settings will no longer be available at all once the logical forks and related code paths have been removed.

Feature flags at Preset

Preset ships a highly-tuned and customized version of Superset, making every attempt to bring its latest and greatest features to our customers, meaning many of Superset’s in-testing feature flags are enabled for our customers by default. We have extensive automated and manual QA processes that make sure our configuration of supported flags is stable and production-ready. If you happen to be an Enterprise Plan customer and need to many any adjustments to suit your business’ use case, you can open a ticket with our customer support team. For example, many customers recently wanted to help us beta-test GENERIC_CHART_AXES, and thanks to this testing and support, we’re happy to announce is now enabled by default for all our customers, and is being defaulted to True on the Superset repo as of today! Also note that certain features like EMBEDDED_SUPERSET incur an additional cost due to the added configuration and infrastructure overhead.

Preset ships with numerous feature flags enabled (along with related configuration and infra) and ready to roll. Here are just a few examples

Feature	Starter	Professional	Enterprise
Thumbnails	✅	✅	✅
Drill to Detail	✅	✅	✅
Drill By	✅	✅	✅
Generic X Axis	✅	✅	✅
Alerts and Reports		✅	✅
Embedded Dashboards			✅
SSH Tunneling			✅

Noteworthy flags and where to learn more about them

Similar to the way FEATURE_FLAGS.md 🔗 attempts to track the category/state of the flags, many of them have simple notes and definitions in config.py 🔗. That said, some of these are worth highlighting here with a little explanation of their purpose, and some additional links and context. Some of these are stable enough to warrant experimentation if you feel so inclined, while others represent in-progress feature development efforts we’re excited to make you aware of.

The following list is not an attempt to be comprehensive in documenting Superset’s feature flags. This is an attempt to help you discover some of the most-frequently-discussed flags — some of which are stable enough to warrant experimentation, and some of which represent in-progress feature development efforts we’re excited to make you aware of.

ALERT_REPORTS Default: False Status: In Testing	In concert with related settings in `config.py` this enables the Alerts & Reports feature in Superset to send dashboard and charts by Slack or email, based on event-based or chronological triggers. More details are available in the Preset and Superset docs.
ALERTS_ATTACH_REPORTS Default: True Status: Stable	When the Alerts & Reports feature is enabled, this setting determines whether or not screenshots/thumbnails are sent in email or Slack messages for Alerts, specifically. They are always sent with Reports.
ALLOW_ADHOC_SUBQUERY Default: False Status: Stable	When writing custom SQL in chart builder controls (rather than simply dragging in a metric/dimension), enabling this flag allows the use of subqueries. RLS rules are applied to these subqueries, meaning this feature is safe to enable/evaluate.
ALLOW_FULL_CSV_EXPORT Default: False Status: In Testing	Adds a new menu item to Table visualizations in dashboards for Full CSV export of all rows, disregarding the Limit applied to the Table visualization itself. This is disabled by default due to possible server memory/performance issues.
DASHBOARD_CROSS_FILTERS Default: False Status: Stable	In the dashboard context, allows charts to emit and receive filters. For example, click a wedge of a pie chart, or a bar in a bar chart, and the other charts on the dashboard will be filtered by what you clicked. You can read more and see examples.
DASHBOARD_EDIT_CHART_IN_NEW_TAB Default: False Status: In Testing	When a user clicks the “Edit Chart” button from any given dashboard, this flag (when enabled) pops open the chart builder UI in a new tab by default. When false, users can still command-click the “Edit Chart” link to open it in a new tab. Editing a chart in a new tab means that the author doesn’t have to navigate away from the dashboard to edit a chart, with the caveat that the dashboard doesn’t automatically update when a chart is saved.
DASHBOARD_NATIVE_FILTERS Default: True Status: Stable	This is the new and supported filtering experience for Superset dashboards, following up the Filter Box component, which is the road to deprecation and removal in an upcoming major version. Calling it out here since it’s an important (and often asked about) flag in terms of status. It will be removed when the Filter Box disappears from the codebase (perhaps in Superset 4.0)
DASHBOARD_VIRTUALIZATION Default: False Status: In Testing	A relatively new and experimental feature built to optimize performance of extremely large dashboards by removing charts from the browser’s DOM/rendering when they’re scrolled significantly far away from the browser’s viewport.
DATAPANEL_CLOSED_BY_DEFAULT Default: False Status: Stable	A bit of a user preference requested by some, this flag makes the (collapsible) Data Preview / Samples pane in the chart builder UI collapsed by default, rather than open/visible.
DRILL_BY Default: False Status: In Development	Similar to Drill to Detail in many ways, this feature allows dashboard users to right-click an area of a chart and select an additional column to act as a “group by” clause. This can be done for any and all columns, allowing users to explore their datasets with increasing layers of depth. Learn more.
DRILL_TO_DETAIL Default: False Status: In Testing	Allows dashboard users to right-click on various elements in supported visualizations, and get a modal displaying the underlying data (including all columns) with a filter applied for the part of a chart (e.g. a pie chart wedge) that was selected. You can read more and see examples here.
DYNAMIC_PLUGINS Default: False Status: In Testing	A frequently requested feature that’s a work in progress. The idea here is to allow people to add visualization plugins to their Superset instance by simply linking to a remotely hosted JavaScript bundle. This is still undergoing architectural discussions and development, and is not ready for prime-time... yet.
EMBEDDABLE_CHARTS Default: True Status: Stable	Allows the embedding of a single chart using an iFrame. The chart and its content are “static” and do not expose data sources or require authentication.
EMBEDDED_SUPERSET Default: False Status: Stable	Enables the implementation of embeddable Superset Dashboards by way of the @superset-ui/embedded-sdk package on npm. You can learn more in this blog post, this demonstration video, and the Preset docs.
ENABLE_JAVASCRIPT_CONTROLS Default: False Status: In Testing	This enables the JavaScript input fields in DeckGL plugins for custom tooltip creation. While quite useful, this (or any) user input of executable scripts comes with a possible (even if unlikely) security tradeoff.
ENABLE_TEMPLATE_PROCESSING Default: False Status: Stable	Enables the use of Jinja templating in Superset for numerous purposes. You can read more about this in this blog post, this video, and the official docs.
ESTIMATE_QUERY_COST Default: False Status: In Testing	Enables additional UI in SQL Lab that lets users estimate the actual cost to run queries in databases where it is supported and configured (in Bigquery, Postgres, and Presto, by setting `cost_estimate_enabled: true` in the database’s `extra` attributes.
GENERIC_CHART_AXES Default: True Status: In Testing	This feature (often referred to as the “Generic X Axis” feature, allows several visualizations to use a categorical column as the X axis, rather than a temporal one. You can read more about the feature in this blog post.
GLOBAL_ASYNC_QUERIES Default: False Status: In Testing	A feature that boosts dashboard performance by creating asynchronous jobs for chart data requests, storing the results in a Redis cache, and using either polling or web sockets to track in-progress jobs. Docs are available here.
HORIZONTAL_FILTER_BAR Default: False Status: In Testing	Enables dashboard authors to set the orientation of the filter bar to either the left side (default) or the top of the layout. This is particularly useful for embedded dashboard use cases, but is becoming the preference of many dashboard users/authors in other cases as well.
LISTVIEWS_DEFAULT_CARD_VIEW Default: False Status: Stable	For list views of Superset contents (Dashboards, Charts, etc.) this flag simply flips the default view from the table/list to the card-based layout by default
RLS_IN_SQLLAB Default: False Status: In Testing	Applies Row Level Security (RLS) rules to queries run by SQL Lab, so that users do not have the ability to query for data that they should not be able to access according to RLS rules respected elsewhere in the product.
SSH_TUNNELING Default: False Status: In Testing	Enables an SSH tunnel between your Superset instance and your data warehouse, so that you can securely connect to databases that might not be accessible directly due to security policies/configurations. You can read more here in the Preset docs.
TAGGING_SYSTEM Default: False Status: In Development	Enables a recently added feature in the UI to add tags to charts, dashboards, and saved queries. Additional details and screenshots are available on the PR. This is still planned to undergo some final design/component tweaks.
THUMBNAILS Default: True Status: Stable	Enables the API to allow the capture of thumbnails of charts and dashboards, used in Alerts & Reports, the Welcome page, and list views. Requires Celery workers and configuration of related `THUMBNAILS_…` settings in `config.py`.
USE_ANALAGOUS_COLORS Default: False Status: In Testing	By default, when applying a visualization color palette to the various series in a dashboard, the palette is cycled through repeatedly. This feature flag allows the frontend to generate additional analogous colors on-demand so that colors are never duplicated. This has pros and cons for the appearance and interpretability of dashboards.
VERSIONED_EXPORT Default: True Status: In Testing	Exports and imports dashboards as ZIP files with multiple YAML files included, and improves the UI to make it simpler to do so. While defaulted to True for all users, there are use cases where one might need to disable the flag to support import/export for legacy asset exports or older deployments.

There are, of course, MANY more feature flags to explore in Superset. If there are any you think should make this list, any of the above need further documentation, or any other flags that should be added or removed, I’m happy to continue updating the post, or taking up a broader discussion in the #customizing-superset channel on Slack. If you have questions or feelings about the lifecycles of these flags, and their presence in upcoming major versions of Superset (e.g. 3.0) then please join us in the Superset Town Hall and/or the Release Strategy working group, both of which are open to the community as part of the Superset Operational Model.

In looking ahead a little bit, it's also worth mentioning that the Superset community is marching down the road toward Superset 3.0! With that release, some old and deprecated flags may be removed, and the categorization and/or default setting of the above flags may change! Rest assured, we'll be blogging about all these changes (and many others) when the release is out! Stay tuned!