john-bodley commented on code in PR #23269: URL: https://github.com/apache/superset/pull/23269#discussion_r1167320890
########## docs/docs/miscellaneous/native-filter-migration.mdx: ########## @@ -0,0 +1,103 @@ +--- +title: Migrating from Legacy to Native Filters +sidebar_position: 5 +version: 1 +--- + +## + +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 strongly advised to run the migration ASAP to +ensure users are not exposed to the hybrid state. + +### Upgrading + +The + +``` +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 aid with 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 + +``` +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 + +``` +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†. Review Comment: Previously I had logic which actually deleted all filter-box charts if the `--all` option was included (irrespective of whether they were part of a dashboard) but later changed said logic. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
