Skip to main content

AML FilterBlock

Knowledge Checkpoint

A grasp of these concepts will help you understand this documentation better:

FilterBlock adds a user-controlled filter to the dashboard. Viewers interact with it to narrow down the data shown in connected visualization blocks, or to limit the values suggested on another filter block. Either way, it's wired up via a FilterInteraction.

block <name>: FilterBlock {
  label: 'Filter Label'
  description: ''                    // optional
  type: 'field'                      // or: 'text' / 'number' / 'date' / 'truefalse'
  source: FieldFilterSource { ... }   // optional, only for type: 'field'
  default {                          // optional
    operator: '...'
    value: '...'
  }
  settings { ... }                   // optional
  theme: BlockTheme { ... }          // optional
}

Parameters​

ParameterDescription
labelDisplay name shown on the filter control.
descriptionOptional description. Supports Markdown.
typeFilter type: 'field', 'text', 'number', 'date', 'truefalse'. See Filter Types for what each type does.
sourceA FieldFilterSource specifying which field the filter controls. Only used when type is 'field'.
defaultOptional default filter condition applied when the dashboard loads. See default.
settingsDisplay and drill-through settings for the control.
themeOptional BlockTheme override for visual styling.

FieldFilterSource​

FieldFilterSource points to the field the filter controls. Field filters are recommended when all your dashboard's viz blocks come from the same dataset: they support value suggestions and automatic mapping. See Field filters.

ParameterDescription
datasetThe dataset name.
fieldReference to the field using r(model.field) syntax.

default​

The default block sets the initial filter state when the dashboard loads.

ParameterDescriptionAccepted values
operatorHow to apply the filter'is', 'is_not', 'contains', 'does_not_contain', 'starts_with', 'ends_with', 'is_null', 'not_null', 'matches_user_attribute', 'top', 'bottom', 'matches', 'last', 'next', 'between', 'before', 'after', 'match_ranges', 'less_than', 'greater_than'
valueThe default filter valueString, Number, Boolean, or a List of these
modifierTime unit for date-based operators (e.g. 'last', 'next')'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute'
optionsExtra behavior for specific operators. See optionsObject

options​

ParameterDescriptionAccepted values
include_current_periodFor date operators like 'last'/'next': whether to include the current, still-in-progress periodBoolean

settings​

ParameterDescriptionAccepted values
input_typeHow viewers select a value'single', 'multiple', 'nullable-single'
hide_labelHides the control's labelBoolean
hide_controlsHides the filter's input controls from viewersBoolean
enable_drillthroughWhether this filter can be targeted by drill-through from other dashboards. Only available when type is 'field'Boolean
drillthroughAdvanced drill-through configuration. See Drillthrough. Only available when type is 'field'Drillthrough object

Drillthrough​

ParameterDescriptionAccepted values
enabledWhether advanced drill-through configuration is activeBoolean
sourcesWhich source dashboards can drill through to this filterList of AutoDrillthroughSource or CustomDrillthroughSource

AutoDrillthroughSource automatically links all dashboards sharing the same dataset, except any listed in excluded_sources. See Advanced Drill-through configurations.

ParameterDescriptionAccepted values
excluded_sourcesDashboards to exclude from auto-linkingList of dashboard names

CustomDrillthroughSource links only the dashboards you explicitly list, instead of auto-linking by dataset. See Advanced Drill-through configurations.

ParameterDescriptionAccepted values
sourcesDashboards to link for drill-throughList of dashboard names

Examples​

Date range filter with default​

block date_filter: FilterBlock {
  label: 'Order Date'
  type: 'field'
  source: FieldFilterSource {
    dataset: ecommerce
    field: r(orders.created_at)
  }
  default {
    operator: 'matches'
    value: 'last 30 days'
  }
}

Categorical filter with multi-value default​

block status_filter: FilterBlock {
  label: 'Order Status'
  type: 'field'
  source: FieldFilterSource {
    dataset: ecommerce
    field: r(orders.status)
  }
  default {
    operator: 'is'
    value: ['active', 'pending']
  }
}

Filter with user attribute default​

block region_filter: FilterBlock {
  label: 'Region'
  type: 'field'
  source: FieldFilterSource {
    dataset: ecommerce
    field: r(orders.region)
  }
  default {
    operator: 'matches_user_attribute'
    value: 'region'
  }
}

Date filter with relative period and current period included​

block f_text: FilterBlock {
  label: 'Text'
  type: 'date'
  default {
    operator: 'last'
    value: '1'
    modifier: 'month'
    options {
      include_current_period: true
    }
  }
}

Single-select filter with drillthrough​

block f_users_role: FilterBlock {
  label: 'Users Role'
  type: 'field'
  source: FieldFilterSource {
    dataset: users
    field: r(public_users.name)
  }
  default {
    operator: 'is'
    value: 'Admin'
  }
  settings {
    input_type: 'single'
    drillthrough: Drillthrough {
      enabled: true
      sources: [
        AutoDrillthroughSource {
          excluded_sources: [
            'adventure_works_big'
          ]
        }
      ]
    }
  }
}

Single-select filter with custom drillthrough sources​

block f_users_role: FilterBlock {
  label: 'Users Role'
  type: 'field'
  source: FieldFilterSource {
    dataset: users
    field: r(public_users.name)
  }
  default {
    operator: 'is'
    value: 'Admin'
  }
  settings {
    input_type: 'single'
    drillthrough: Drillthrough {
      enabled: true
      sources: [
        CustomDrillthroughSource {
          sources: [
            'adventure_works_big',
            'ecommerce_dashboard_test_ai'
          ]
        }
      ]
    }
  }
}

See also​

Open Markdown
Let us know what you think about this document :)