Filters

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.

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.

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.

Number filters: Range or List

A filter on a number field shows as a Range or a List. Choose it under Show as on the Basic tab.

• Range lets viewers pick a condition and type or drag its numbers: Between, Not between, At least, At most, Greater than, Less than, Equal to, Not equal to, Is empty and Is not empty. Use it for amounts, quantities, weights and prices: an Order amount of at least 500, or a Discount between 5 and 20.
• List lets viewers tick values, as a text filter does. Use it for numbers that are codes, such as ZIP codes or order numbers. Under Advanced, List search sets whether typing >100 in the search narrows the list to those values, or searches the digits as text.

New filters on a number field start as a Range. Filters you already have keep showing as they do.

In a Range, the bars behind the slider show how the field's values spread under the filters that narrow its choices, and the footer says about how many rows most conditions keep before you apply it. Type 1,200, 1.2k or 2m; Enter applies, like Apply. Between includes both numbers. Not equal and Not between leave out rows with no value; use Is empty to find those.

A Range's default is a condition: set it under Default condition on the Basic tab with the same editor viewers use, and every viewer opens the dashboard with it.

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.

Year to last completed month

A date filter, its default or a card filter can use Year to last completed month, the last preset under Year. It covers January 1 through the last day of the most recent full month, in your report's time zone, so a revenue dashboard shows only finished months:

It follows your calendar: with a fiscal year that starts in April, on Oct 27, 2026 it covers Apr 1 to Sep 30, 2026. It moves forward on its own, and scheduled reports and PDF exports use the months finished by the day they run. A PDF filter line reads Order date: Year to last completed month.

Comparisons. Previous period compares the same finished months one year earlier: on Oct 27, 2026, orders from Jan 1 to Sep 30, 2026 against Jan 1 to Sep 30, 2025. On Mar 10, 2029 it compares Jan 1 to Feb 28, 2029 with Jan 1 to Feb 29, 2028, each through the end of its February. Previous year gives the same answer. If another date filter narrows the range, for example a card filter for April to June, the comparison uses the narrowed range, as it does for any range. Match weekdays shifts the range by whole weeks, as it does for any range.

An agent connected through MCP can set it too, as a filter's default or a card's timeWindow, with the same window the editor saves: { "kind": "periods", "unit": "year", "from": 0, "to": 0, "toDate": true, "anchor": { "lastComplete": "month" } }.

Any number of days, weeks or months

The date picker's Relative tab builds a range as a sentence: choose Last, This or Next, type a number and pick a unit. Last 28 days, Last 13 months and Next 2 weeks each take one step. Include today (or Include this month, and so on) decides whether the current period counts: Last 3 months with it on covers this month and the two before; with it off, the three full months before this one. With This, Up to now stops the range at the current moment.

Before you select Apply, the top of the picker shows the dates the range covers today. Every preset sits in one list on the Presets tab, grouped under Day, Week, Month, Quarter and Year.

Before or after a date measured from today

The Relative tab also offers Before and After, measured from today instead of from a fixed date:

The date moves forward on its own: a dashboard that opens on Before 90 days ago always shows rows older than 90 days, and a scheduled report uses the date of its run. The filter reads its sentence, for example Order date: Before 90 days ago. A filter's default can be one too.

On a card filter, the condition you pick (Is before, Is on or after, and so on) decides the side, and the Relative tab asks only for the date. The Global Date filter keeps ranges only, because cards compare it with the period before. Comparisons on a card leave out a before or after condition, as they do a fixed date.

An agent connected through MCP reads these filters but can't set them yet; it can replace one with a range.

Minutes and hours

On a timestamp column, such as an order's created time, the date picker's Presets tab has a Time category: Last 30 minutes, Last 1 hour, Last 4 hours, Last 12 hours and Last 24 hours. For any other length, open the Relative tab, choose Last, type a number and pick minutes or hours: for example, Last 45 minutes of orders.

The same choices are there for a dashboard filter, its default and a card filter. A date column without a time has no Time category, because it has no clock to count back from.

A range in minutes or hours ends at the moment the dashboard or card runs and starts that long before it. It moves forward on its own, so a dashboard that opens on Last 45 minutes always shows the latest 45 minutes, and a scheduled report uses the 45 minutes before it runs.

You can enter up to 5,256,000 minutes or 87,600 hours, which is ten years. A count that isn't a whole number of 1 or more, or is over the limit, can't be applied, and the picker says what to enter.

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:

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.

Next steps