| "use strict";(self.webpackChunkdocs_v_2=self.webpackChunkdocs_v_2||[]).push([[1964],{99898:(e,t,r)=>{r.r(t),r.d(t,{assets:()=>s,contentTitle:()=>o,default:()=>p,frontMatter:()=>i,metadata:()=>l,toc:()=>c});var n=r(83117),a=(r(67294),r(3905));const i={title:"Migrating from Legacy to Native Filters",sidebar_position:5,version:1},o=void 0,l={unversionedId:"miscellaneous/native-filter-migration",id:"miscellaneous/native-filter-migration",title:"Migrating from Legacy to Native Filters",description:"The superset native-filters CLI command group\u2014somewhat akin to an Alembic migration\u2014",source:"@site/docs/miscellaneous/native-filter-migration.mdx",sourceDirName:"miscellaneous",slug:"/miscellaneous/native-filter-migration",permalink:"/docs/miscellaneous/native-filter-migration",draft:!1,editUrl:"https://github.com/apache/superset/tree/master/docs/docs/miscellaneous/native-filter-migration.mdx",tags:[],version:"current",sidebarPosition:5,frontMatter:{title:"Migrating from Legacy to Native Filters",sidebar_position:5,version:1},sidebar:"tutorialSidebar",previous:{title:"Chart Parameters Reference",permalink:"/docs/miscellaneous/chart-params"},next:{title:"Contributing to Superset",permalink:"/docs/contributing/contributing-page"}},s={},c=[{value:"Upgrading",id:"upgrading",level:3},{value:"Quality Control",id:"quality-control",level:4},{value:"Downgrading",id:"downgrading",level:3},{value:"Cleanup",id:"cleanup",level:3},{value:"Quality Control",id:"quality-control-1",level:4}],d={toc:c},u="wrapper";function p(e){let{components:t,...r}=e;return(0,a.kt)(u,(0,n.Z)({},d,r,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("h2",{id:""}),(0,a.kt)("p",null,"The ",(0,a.kt)("inlineCode",{parentName:"p"},"superset native-filters")," CLI command group\u2014somewhat akin to an Alembic migration\u2014\ncomprises of a number of sub-commands which allows administrators to upgrade/downgrade\nexisting dashboards which use the legacy filter-box charts\u2014in combination with the\nfilter scopes/filter mapping\u2014to use the native filter dashboard component."),(0,a.kt)("p",null,"Even though both legacy and native filters can coexist the overall user experience (UX)\nis substandard as the already convoluted filter space becomes overly complex. After\nenabling the ",(0,a.kt)("inlineCode",{parentName:"p"},"DASHBOARD_NATIVE_FILTERS")," it is strongly advised to run the migration ASAP to\nensure users are not exposed to the hybrid state."),(0,a.kt)("h3",{id:"upgrading"},"Upgrading"),(0,a.kt)("p",null,"The"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"superset native-filters upgrade\n")),(0,a.kt)("p",null,"command\u2014which provides the option to target either specific dashboard(s) or all\ndashboards\u2014migrates the legacy filters to native filters."),(0,a.kt)("p",null,"Specifically, the command performs the following:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Replaces every filter-box chart within the dashboard with a markdown element which\nprovides a link to the deprecated chart. This preserves the layout whilst simultaneously\nproviding context to help owners review/verify said change."),(0,a.kt)("li",{parentName:"ul"},"Migrates the filter scopes/filter mappings to the native filter configuration.")),(0,a.kt)("h4",{id:"quality-control"},"Quality Control"),(0,a.kt)("p",null,"Dashboard owners should:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Verify that the filter behavior is correct."),(0,a.kt)("li",{parentName:"ul"},"Consolidate any conflicting/redundant filters\u2014this previously may not have been\nobvious given the embedded nature of the legacy filters and/or the non-optimal UX of the\nlegacy filter mapping (scopes and immunity)."),(0,a.kt)("li",{parentName:"ul"},"Rename the filters\u2014which may not be uniquely named\u2014to provide the necessary context\nwhich previously was likely provided by both the location of the filter-box and the\ncorresponding filter-box title.")),(0,a.kt)("p",null,"Dashboard owners may:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Remove\u2020 the markdown elements from their dashboards and adjust the layout accordingly.")),(0,a.kt)("p",null,"\u2020 Note removing the markdown elements\u2014which contain metadata relating to the replaced\nchart\u2014prevents the dashboard from being fully restored and thus this operation should\nonly be performed if it is evident that a downgrade is not necessary."),(0,a.kt)("h3",{id:"downgrading"},"Downgrading"),(0,a.kt)("p",null,"Similarly the"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"superset native-filters downgrade\n")),(0,a.kt)("p",null,"command reverses said migration, i.e., restores the dashboard to the previous state."),(0,a.kt)("h3",{id:"cleanup"},"Cleanup"),(0,a.kt)("p",null,"The ability to downgrade/reverse the migration requires temporary storage of the\ndashboard metadata\u2014relating to both positional composition and filter configuration."),(0,a.kt)("p",null,"Once the upgrade has been verified it is recommended to run the"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"superset native-filters cleanup\n")),(0,a.kt)("p",null,"command\u2014which provides the option to target either specific dashboard(s) or all\ndashboards. Note this operation is irreversible."),(0,a.kt)("p",null,"Specifically, the command performs the following:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Removes the temporary dashboard metadata."),(0,a.kt)("li",{parentName:"ul"},"Deletes the filter-box charts associated with the dashboard\u2020.")),(0,a.kt)("p",null,"\u2020 Note the markdown elements will still remain however the link to the referenced filter-box\nchart will no longer be valid."),(0,a.kt)("h4",{id:"quality-control-1"},"Quality Control"),(0,a.kt)("p",null,"Dashboard owners should:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Remove the markdown elements from their dashboards and adjust the layout accordingly.")))}p.isMDXComponent=!0},3905:(e,t,r)=>{r.d(t,{Zo:()=>d,kt:()=>m});var n=r(67294);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function i(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,n)}return r}function o(e){for(var t=1;t<arguments.length;t++){var r=null!=arguments[t]?arguments[t]:{};t%2?i(Object(r),!0).forEach((function(t){a(e,t,r[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(r)):i(Object(r)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(r,t))}))}return e}function l(e,t){if(null==e)return{};var r,n,a=function(e,t){if(null==e)return{};var r,n,a={},i=Object.keys(e);for(n=0;n<i.length;n++)r=i[n],t.indexOf(r)>=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n<i.length;n++)r=i[n],t.indexOf(r)>=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var s=n.createContext({}),c=function(e){var t=n.useContext(s),r=t;return e&&(r="function"==typeof e?e(t):o(o({},t),e)),r},d=function(e){var t=c(e.components);return n.createElement(s.Provider,{value:t},e.children)},u="mdxType",p={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},h=n.forwardRef((function(e,t){var r=e.components,a=e.mdxType,i=e.originalType,s=e.parentName,d=l(e,["components","mdxType","originalType","parentName"]),u=c(r),h=a,m=u["".concat(s,".").concat(h)]||u[h]||p[h]||i;return r?n.createElement(m,o(o({ref:t},d),{},{components:r})):n.createElement(m,o({ref:t},d))}));function m(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var i=r.length,o=new Array(i);o[0]=h;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l[u]="string"==typeof e?e:a,o[1]=l;for(var c=2;c<i;c++)o[c]=r[c];return n.createElement.apply(null,o)}return n.createElement.apply(null,r)}h.displayName="MDXCreateElement"}}]); |