Migrating from Legacy to Native Filters

The superset native-filters CLI command group—somewhat akin to an Alembic migration— comprises of a number of sub-commands which allows administrators to upgrade/downgrade existing dashboards which use the legacy filter-box charts—in combination with the filter scopes/filter mapping—to use the native filter dashboard component.

Even though both legacy and native filters can coexist the overall user experience (UX) is substandard as the already convoluted filter space becomes overly complex. After enabling the DASHBOARD_NATIVE_FILTERS it is strongly advised to run the migration ASAP to ensure users are not exposed to the hybrid state.

Upgrading

The

  1. superset native-filters upgrade

command—which provides the option to target either specific dashboard(s) or all dashboards—migrates the legacy filters to native filters.

Specifically, the command performs the following:

  • Replaces every filter-box chart within the dashboard with a markdown element which provides a link to the deprecated chart. This preserves the layout whilst simultaneously providing context to help owners review/verify said change.
  • Migrates the filter scopes/filter mappings to the native filter configuration.

Quality Control

Dashboard owners should:

  • Verify that the filter behavior is correct.
  • Consolidate any conflicting/redundant filters—this previously may not have been obvious given the embedded nature of the legacy filters and/or the non-optimal UX of the legacy filter mapping (scopes and immunity).
  • Rename the filters—which may not be uniquely named—to provide the necessary context which previously was likely provided by both the location of the filter-box and the corresponding filter-box title.

Dashboard owners may:

  • Remove† the markdown elements from their dashboards and adjust the layout accordingly.

† Note removing the markdown elements—which contain metadata relating to the replaced chart—prevents the dashboard from being fully restored and thus this operation should only be performed if it is evident that a downgrade is not necessary.

Downgrading

Similarly the

  1. superset native-filters downgrade

command reverses said migration, i.e., restores the dashboard to the previous state.

Cleanup

The ability to downgrade/reverse the migration requires temporary storage of the dashboard metadata—relating to both positional composition and filter configuration.

Once the upgrade has been verified it is recommended to run the

  1. superset native-filters cleanup

command—which provides the option to target either specific dashboard(s) or all dashboards. Note this operation is irreversible.

Specifically, the command performs the following:

  • Removes the temporary dashboard metadata.
  • Deletes the filter-box charts associated with the dashboard†.

† Note the markdown elements will still remain however the link to the referenced filter-box chart will no longer be valid.

Quality Control

Dashboard owners should:

  • Remove the markdown elements from their dashboards and adjust the layout accordingly.