Native Filters#

Native Filters is Superset's first-class dashboard filtering system. Filters are configured per-dashboard, stored in json_metadata under native_filter_configuration, and rendered in either a vertical sidebar or a horizontal header bar. At runtime, each filter's selected value is tracked as a dataMask object in Redux and applied to charts via formData injection.

Key Entry Points#

dataMask — Filter State Shape#

Every filter's state is a DataMaskWithId object 1:

{
  id: string; // filter ID (prefixed with NATIVE_FILTER_PREFIX)
  extraFormData: {}; // merged into chart query formData
  filterState: {}; // UI state: { value, label, validateStatus, ... }
  ownState: {}; // filter-type-specific internal state
}

The global Redux slice is DataMaskStateWithId — a flat map keyed by filter ID 2. useNativeFiltersDataMask() narrows this map to only native filter entries by checking for NATIVE_FILTER_PREFIX.

The reducer (dataMaskReducer) handles four cases 3:

• UPDATE_DATA_MASK — merges a single filter's new mask into Redux state.
• CLEAR_DATA_MASK_STATE — wipes the entire map (e.g. on dashboard unmount).
• HYDRATE_DASHBOARD — initializes the map from native_filter_configuration on load, merging any restored dataMask (e.g. from a permalink).
• SET_DATA_MASK_FOR_FILTER_CHANGES_COMPLETE — reconciles after filter config edits: removes deleted filters, resets modified ones, and preserves state for filters with enableEmptyFilter or defaultToFirstItem 4.

Dual-State Pattern (Local Draft → Redux)#

FilterBar uses a local draft + Redux applied pattern 5:

1. Local draft (dataMaskSelected) — maintained via useImmer, updated immediately on every filter interaction via handleFilterSelectionChange. Drives the UI (e.g., Apply button enabled/disabled state).
2. Applied state (dataMaskApplied) — the committed Redux dataMask. Charts query against this state only.
3. Apply action — handleApply dispatches updateDataMask for all selected filters, promoting the draft into Redux.

Filters marked with requiredFirst: true bypass the Apply step and are dispatched to Redux immediately on initialization 6.

Orientation: Vertical vs Horizontal#

FilterBarOrientation is an enum stored in Redux under dashboardInfo.filterBarOrientation 7. DashboardBuilder reads it and renders the appropriate layout.

Vertical (sidebar): rendered inside a sticky FiltersPanel with collapsible state 8. Requires a verticalConfig object with filtersOpen, toggleFiltersBar, width, height, and offset props 9. The Vertical component manages scroll detection and renders an expand/collapse toggle.

Horizontal (header): rendered inside the dashboard header area, above any tabs 10. Accepts only hidden and orientation props — layout config is handled internally by Horizontal.tsx 11. Embedded/report mode (isReport) hides the bar via the hidden prop without unmounting it, preserving filter logic 12.

Filter State Persistence#

When a logged-in user applies filters, FilterBar calls publishDataMask (debounced) which serializes dataMaskApplied to JSON, stores it via the keyValue API, and writes the resulting cache key to the URL as native_filters_key. On dashboard load, this key is read back and used to restore filter state 13. Embedded users skip this step — the user?.userId guard prevents persistence for unauthenticated contexts 14.

Filter Scope#

Each filter's scope object (rootPath + excluded) determines which charts it affects. See the Native Filter Scope Management article for full details on how scope is resolved and the common crash patterns around undefined scope.