Skip to navigation

Filters and drill-through

View as Markdown

This chapter explains how to add filters to a dashboard so readers can narrow what they see, and how to click into the detail behind a number.


What a filter is for

A filter sits at the top of a dashboard and narrows every chart on it at once. Without one, a reader who wants last month instead of last year has to ask you to build a second dashboard.

The default Staple Dashboard carries four, which is a good model to copy: Date, Queue, Time scale and Document Type. Between them a reader can answer “how did invoices do in the Singapore queue last month” without touching a single chart.

1. Adding a filter to a dashboard

  1. Select the pencil to enter edit mode.
  2. In the toolbar, select Add a filter or parameter.
  3. Choose the kind of filter you want.

Seven kinds are offered, each with an example of what it can ask:

KindFor
Date pickerDate range, specific date…
Time groupingDay, week, month, year…
LocationCountry, State, Postal Code…
Text or CategoryContains, is, starts with…
NumberBetween, greater than…
BooleanTrue, false…
IDPrimary key, User ID…

The filter appears at the top of the dashboard and a settings panel opens on the right, carrying Label, Filter or parameter type, Filter operator, Default value and Always require a value.

Set Label to what a reader would say out loud. Date beats created_at, and Queue beats queue_id. It is the only part of the filter anyone else ever sees.

Time grouping is the odd one out. It does not narrow the data, it changes the time grain charts are grouped by: day, week, month, quarter, year. That is what the default dashboard’s Time scale filter is.

2. Connecting a filter to your charts

This is the step people miss, and the symptom is a filter that does nothing.

Adding a filter creates the control. It does not connect it. Until you tell the filter which column to act on for each card, moving it changes nothing.

The moment the filter exists, every card on the dashboard is overlaid with a small panel reading Column to filter on and a Select… button. That overlay is the wiring step. Work through the cards:

  1. On a card, select Select….
  2. Pick the column the filter should act on. The list is grouped by where the column comes from, so a chart built on a data model shows a group named after it, and any column the chart itself computed appears under Summaries. Where a card offers only one usable column, the list is a single line.
  3. Repeat for every card you want the filter to reach. A wired card shows the column as a chip, prefixed with the group it came from.
  4. Select Done in the settings panel.
  5. Select Save on the edit bar.

Two saves again. Done closes the filter’s settings. Save commits the dashboard. Only the second one makes the wiring permanent.

Worth knowing:

  • A card you skip is not filtered. It keeps showing everything while its neighbours narrow.
  • The column has to make sense. Where a card has no column the filter could act on, the overlay reads No valid fields instead of offering a picker. That card cannot use that filter. Either accept it or rebuild the question on data that carries the column.
  • You can undo the wiring. Once a filter is connected to at least one card, the settings panel gains Disconnect from cards, which unwires it everywhere without deleting the filter.

After saving, move the filter and watch every chart change. If one does not, it is not wired.

A shortcut worth knowing. In edit mode, hovering a card shows a row of icons, one of which is Add a filter. Starting from there creates the filter and wires it to that card in one go. It is the easier route when a filter only needs to reach one or two cards.

3. Default values and required filters

A dashboard that opens on all time is slow and rarely what anyone wants. Give the date filter a default, and the dashboard opens useful.

Set it under Default value in the filter’s settings panel. The default dashboard sets Date to Previous 30 days and Time scale to Day, which is a sensible pairing to copy: a month of history at daily granularity.

Readers can still change it. A default is a starting point, not a restriction.

Unless you make it one. The same panel offers Always require a value, described as: “When enabled, people can change the value or reset it, but can’t clear it entirely.” Use it where an unfiltered view would be meaningless or slow, for example a date filter on a chart covering years of documents. Use it sparingly otherwise, since it takes an option away from the reader.

4. Drilling into a number

A chart is a summary. Drilling is how you get from the summary to the rows behind it.

  1. Hover a point, bar or cell. A tooltip shows the value and how it compares with the previous period.
  2. Click it. A menu opens.
OptionWhat it does
See these recordsThe individual rows behind that one point
See this month by weekSame measure, finer time grain. The wording follows your current grouping
Break out by…Splits that point by another column, for example doc type or queue
Filter by this valueApplies that value as a filter, with < > = ≠ for numbers

See these records is the one to reach for when a number looks wrong. It answers “which documents made this number”.

You can download these rows. The drill screen has its own download control, top right, offering .csv, .xlsx and .json. This is how you get from “that number looks wrong” to a spreadsheet of the documents behind it.

Select Back to followed by the dashboard name, top left, to return.

5. Downloading the data

Four routes, depending on what you want to do with it afterwards.

5.1 One chart, as data

Select the … on the card, then Download results.

That opens Download data, offering .csv, .xlsx, .json and .png.

Keep the data formatted is the choice that matters here. Leave it ticked and values arrive as the chart displays them, “E.g. September 6, 2024 or $187.50”. Untick it for the underlying raw values, which is usually what another tool wants. .png is a picture of the chart rather than data, so the formatting choice disappears when you pick it.

5.2 The whole dashboard, as data

Select Export in the header.

ChoiceWhat you get
Export chart · As displayedThe summarised numbers as the charts show them, formatted
Raw table values · UnformattedThe underlying values without formatting applied

For a question that summarises, “raw” means the query’s result rows, not every source document.

5.3 The whole dashboard, as a document

Select Download as PDF, above the dashboard body beside the pencil. That gives you every card laid out as it appears on screen, which is what you want for a pack or a slide rather than for analysis.

It is not in the header. Look beside the pencil rather than next to Export.

5.4 The documents behind a number

Drill in with See these records, then download from that screen. Section 4 covers it, and it is the only route that reaches individual documents rather than summarised rows.

6. Filter patterns worth copying

Date across everything. One date filter wired to every card, defaulted to a recent range. The single highest-value filter on any dashboard, and the one readers reach for first.

Queue as a per-team view. A queue filter turns one dashboard into as many views as you have teams. Instead of building a dashboard per team, build one and let each team select their own queue. Fewer dashboards to maintain, and they cannot drift apart.

Document type for like-for-like comparison. Invoices and delivery orders rarely behave the same. A document-type filter lets a reader stop averaging them together, which is usually where a confusing number comes from.

One caution. Every filter you add is a decision you hand the reader. Four is plenty; ten means nobody touches any of them.