Filters
What a dashboard filter is, where it applies, what viewers choose from, and how selections reach cards.
A filter lets viewers narrow many cards from one place. Select United States in Country and every card that uses Country shows US data.
As an author you decide three things for each filter:
- Where it appears: which sheets, and which cards respond.
- What viewers choose from: the field behind the choices and the label they read.
- How choices react to other filters: whether Country narrows the City list.
Most filters use a column from a table or semantic dataset; Semaphor loads the values. You can also supply the choices with custom SQL.
Every dashboard filter works the same way, on regular sheets and on Document sheets. A filter you add from the filter bar, one you add in a Document's input bar, and one written through the API or MCP are the same kind of filter, with the same settings.
Where a filter applies
Sheet scope decides which sheets a dashboard filter appears on. Set it on the Scope tab of the filter's settings while editing.
| Option | Effect |
|---|---|
| All sheets | Available on every sheet, with one shared selection. |
| Only specific | Available only on the sheets you check. |
| All except | Available everywhere except the sheets you check. |
A filter you add from the filter bar reaches regular sheets. To show it on the dashboard's Document sheets too, check Include Document tabs, or check a Document under Only specific. A filter you add in a Document starts on that Document only; widen it the same way.
A filter keeps one selection across every sheet in its scope. Outside its scope it neither appears nor applies.
Card scope, on the same tab, narrows which cards on those sheets the filter reaches: All cards, Only specific, or All except.
Within its reach, the Cards tab sets the field the filter applies to on each card, Document section cards included. Choose Don't apply this filter for a card to leave it unchanged, for example a worldwide benchmark next to a regional chart.
Scope alone does not connect a card. Config-driven cards need a compatible field, and SQL cards need a subscription in their query. See Map Filters to Cards and Filters in SQL.
Filters placed inside a card are local to that card and have no sheet scope.
What viewers choose from
On the Basic tab, Option Value Field is what queries receive and Option Label Field is what viewers read. They are usually the same field. Use different fields when your data keys on identifiers: a Customer filter can show names while sending customer ids, so two customers with the same name stay distinct.
Default values
Set what a filter starts with under Default Values on the Basic tab. You pick values in the same list viewers use, and choose Include to show only those values or Exclude to show everything except them. For example, Exclude with 0 selected hides rows where the value is 0. Every viewer opens the dashboard with that default.
Viewers can switch a filter between Include and Exclude in its dropdown. That changes only their view: the saved default stays as you set it, even when you switch it yourself while editing. To change the default, open the filter's settings.
Date filters that use the Day or Month picker also offer Always keep a selection. When a viewer clears the filter, it returns to its default instead of showing all dates.
Clear all, at the end of the filter bar and of a Document's input bar, clears every filter value there. When a filter keeps its selection, the button reads Reset filters: it clears the others and returns that filter to its default.
Require a value
Turn on Required on the Basic tab when cards make no sense without a selection, such as a statement for one customer. Until the filter has a value, the cards it applies to wait instead of running unfiltered. A card set to Don't apply this filter on the Cards tab runs as usual. On a Document sheet, a required filter with no value also holds back PDF export.
Narrow choices with other filters
By default, related filters narrow each other's choices: pick a country and the City list shows only that country's cities. Narrow available options by on the Basic tab sets this to all applicable filters, selected filters, or none, and semantic filters can name the dataset that gives a choice its meaning.
Narrowing changes only what viewers can pick next. It never changes which cards a selection filters.
See Cascading Filters for the modes, one-way setups, what viewers see, and when narrowing needs a modeled relationship.
How a selection reaches cards
Three settings answer three different questions:
| Question | Setting | Where |
|---|---|---|
| Which sheets and cards can use this filter? | Sheet scope, Card scope | Scope tab |
| Which field on each card? | Card mapping | Cards tab |
| Which other selections narrow the choices? | Narrow available options by | Basic tab |
A City filter with narrowing set to None still filters all its mapped cards. Excluding a card does not make the City list independent of Country.
For one date range applied to each card's primary date field, use the Global Date Filter. It reaches regular sheets and uses each card's primary date, so it has no Cards tab.
Custom SQL filters
A custom SQL filter supplies its choices through a query you write. Its SQL and template expressions decide which other selections narrow those choices; the narrowing modes above do not apply to it. A regular filter can still filter a SQL card, and a custom SQL filter can still apply its selection to cards.
Filters in SQL and code
Subscribing SQL cards with {{ filters | where }}, filtering API connections,
loading an embedded dashboard with filters applied, and SQL authoring
practices moved to Filters in SQL.