Skip to main content
Users need the Admin role to create and edit filters. Analysts can use existing filters but cannot modify them.
Prominent filters appear in the top toolbar and apply to all tiles in your Doc at once. They let viewers slice data by custom dimensions like region, industry, product, etc.
Prominent filters in toolbar

​
Creating prominent filters

You can add prominent filters in two ways:

​
Using Fi

Ask Fi to add filters to your Doc:
  • “Add a prominent filter for industry”
  • “Add a filter for region to the toolbar”
  • “Create filters for CRM source and stage name”
Fi adds the appropriate YAML configuration automatically.

​
Manually via YAML

  1. Click the ⋯ menu in the top toolbar
  2. Select View YAML
  3. Add a filters section after metadata and before datasets:
version: 1
schemaVersion: "2025-01"
kind: dashboard

metadata:
  name: "Your Dashboard Name"
  description: "Your dashboard description"

# Filters appear between metadata and datasets
filters:
  - id: region_filter          # Unique identifier
    label: Region              # Display name in toolbar
    target:
      dimension: orders.region # Format: cube_name.dimension_name
    operator: equals           # Options: equals, notEquals, contains, notContains
    display: prominent         # Shows filter in toolbar (remove to hide)
    values:                    # Optional: preset values
      - North America
      - Europe
      - Asia Pacific

  - id: product_filter
    label: Product
    target:
      dimension: orders.product_name
    operator: equals
    display: prominent
    values:
      - Pro Plan
      - Enterprise Plan

datasets:
  my_dataset:
    engine: cube
    ...
Each filter requires:
PropertyDescriptionExample
idUnique identifier for the filterregion_filter
labelDisplay name shown in the toolbarRegion
target.dimensionThe cube and dimension to filterorders.region
operatorFilter operationequals
displaySet to prominent to show in toolbarprominent
values(Optional) Preset values for the filter["North America", "Europe"]

​
Using prominent filters

  1. Click a filter in the toolbar (e.g., “Industry”, “Region”, “Source”)
  2. Select one or more values from the dropdown
  3. Click Apply to see your filtered data

​
Local vs. saved filters

When you apply a filter, you have two options:
ActionWho sees itPersistenceUse case
ApplyOnly youTemporary (resets on page reload)Exploring data on your own
Save for everyoneAll usersPermanent (becomes the default view)Setting the default filter state for the Doc
To save filters for everyone, click the dropdown arrow next to the Apply button and select Save for everyone.
Local vs saved filters
If you reload the page after using Apply, the filters revert to the last “saved for everyone” state. To make your selections permanent, click Save for everyone.
To reset filters and show all data, click Reset.

​
Filter display modes

Filters have two display modes, controlled by the display property:
ModeBehavior
prominentShown directly in the toolbar (always visible)
popoverHidden behind a filter button/popover (default)
filters:
  - id: status_filter
    display: prominent         # Always visible in toolbar
    label: Status
    target:
      dimension: sales.status
    operator: equals
    values:
      - Active

  - id: source_filter
    display: popover           # Hidden behind filter button (default)
    label: Source
    target:
      dimension: sales.source
    operator: equals
You can also add optional fields like options (predefined choices) and excludeDatasets (skip specific datasets when applying the filter).

​
Parameters in SQL datasets

Parameters are a separate mechanism from filters. While filters target Cube dimensions, parameters inject values directly into SQL queries using Jinja-style {{ "{{" }} parameters.<id> {{ "}}" }} syntax.
Parameters only work with engine: sql datasets. They do not work with Cube or Python datasets. For Cube datasets, use filters (above) instead.
Define parameters at the top level of your Doc YAML, then reference them in SQL: 
parameters:
  - id: start_date
    type: time
    label: "Start Date"
    default: "2024-01-01"

datasets:
  filtered_data:
    engine: sql
    sql: SELECT * FROM sales WHERE date >= '{{ "{{" }} parameters.start_date {{ "}}" }}'
Parameters appear in the Doc UI as input controls that viewers can adjust.

​
Parameter properties

PropertyRequiredDescription
idYesUnique identifier, referenced in SQL
typeYesData type (e.g., time). Call get_doc_schema() at runtime to see all valid types.
labelYesDisplay name shown in the UI
defaultNoDefault value when the Doc loads

​
Key rules

  • Reference parameters with {{ "{{" }} parameters.<id> {{ "}}" }}
  • Wrap in single quotes for string/date values: '{{ "{{" }} parameters.start_date {{ "}}" }}'
  • Only works with engine: sql datasets
  • Parameters are always shown as input controls in the UI (no display property like filters)