> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.staple.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.staple.ai/_mcp/server.

# Filters and drill-through

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:

| **Kind**             | **For**                      |
| -------------------- | ---------------------------- |
| **Date picker**      | Date range, specific date…   |
| **Time grouping**    | Day, week, month, year…      |
| **Location**         | Country, State, Postal Code… |
| **Text or Category** | Contains, is, starts with…   |
| **Number**           | Between, greater than…       |
| **Boolean**          | True, false…                 |
| **ID**               | Primary 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.

| **Option**                 | **What it does**                                                          |
| -------------------------- | ------------------------------------------------------------------------- |
| **See these records**      | The individual rows behind that one point                                 |
| **See this month by week** | Same 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 value**   | Applies 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.

| **Choice**                           | **What you get**                                          |
| ------------------------------------ | --------------------------------------------------------- |
| **Export chart** · *As displayed*    | The summarised numbers as the charts show them, formatted |
| **Raw table values** · *Unformatted* | The 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.