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.
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 keeps one selection across every sheet in its scope. Outside its scope it neither appears nor applies.
Within those sheets, the Cards tab decides which cards respond. Mark a card Not applied to leave it unchanged, for example a worldwide benchmark next to a regional chart. Where the settings show a Card scope section instead, use All cards, Only specific, or All except.
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.
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 can use this filter? | Sheet scope | Scope tab |
| Which cards, and which field on each? | 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.
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.