Guides

Filter a dashboard

Every chart on a dashboard reads saved data. A filter narrows that saved data in your browser. No query runs, and nothing you filter changes the dashboard. In this guide, you learn about the controls on the canvas, filtering by a click on a chart, where each filter reaches, and the link that carries your exact view. Authors also learn about the defaults that the dashboard stores.

Use a control

Controls are the widgets on the canvas: value lists, date pickers, and tests you type. Each control filters the blocks it reaches, for you alone.

Pick values in a list

A one-value list opens on All, which filters nothing. Pick a value to filter. A many-value list stays open while you check values, and its field shows the count beside the selection.

The filter box searches all the values of the column, including the values that the list does not show. Type a few letters to narrow the list. The list shows at most 200 matches, and says how many more match. To reach a rare value, type more of it. When you type a value that the list does not have, a Use "…" row appears at the top. Select that row to use the typed value.

When the column has rows with no value, the list ends with (Blank), in italics, which finds those rows. A column with no blank value shows no such row. On a many-value list, it checks beside the other values, so "North, (Blank)" keeps the named rows and the blank rows together. A one-value list offers (Blank) and (Not blank) as rows of their own.

A many-value list carries an Exclude chip beside its label. With Exclude on, the selection removes its values instead of keeping them, and the field reads "not …". An excluding selection keeps the rows with a blank value. To remove those rows too, check (Blank). While anything is selected, the label row shows Clear.

Pick a period or exact dates

A date-range control is one field and a popover. The field states the current range in words: a preset name, a pair of dates, or All time when nothing filters. The popover gives three ways to set a range:

• Presets — rolling day counts (Last 7 days), calendar periods with their "to date" versions (This month, This month to date), and whole previous periods (Last month).
• Typed From and To bounds.
• A calendar — the first click starts the range, and the second click ends it. While you point at a day, the calendar previews the range.

When you pick a preset, the control changes it to fixed dates, so a link you share holds the exact dates you saw. To end rolling ranges yesterday, turn on Exclude today (rolling). Use it when the data for today is not complete.

Type a test

A text or number control applies a test. The test is on the label row, and the value goes in the box under it. The test menu offers the tests that fit the column: contains and starts with on text, is greater than and is between on numbers, and is blank on both.

1. Select the test on the label row.
2. Type the value. is between takes two bounds, and the blank tests take none.
3. To apply the test, press Enter or click away.

An is between with one bound filters nothing, and you read under the control that it takes both bounds. A negated test, such as does not contain or is not, also matches the rows with a blank value, and you read this under the control too. Clear empties the value and sets the test back to the author's default.

Reach every filter from one list

On a big dashboard, a control can be far from the chart you read. The Controls panel lists every filter of the dashboard in one place, including the filters that have no control on the canvas, and the parameters beside them. You need no edit access.

1. Click the funnel icon in the icon rail at the right edge of the screen. The panel opens beside the canvas. On a phone, it opens at the bottom of the screen.
2. Change a filter in the panel. The panel and the controls on the canvas show the same value, and the charts update.
3. To find the control of a filter on the canvas, click Show on canvas. The canvas moves the control to its center.
4. To go back to the author's defaults, click Reset all. The reset changes only your view of the dashboard.

The number on the funnel icon is the count of filters that are set. When the icon shows no number, no dashboard filter is set. When the panel says the dashboard has no filters, its editors add them with a Control block.

Click a chart to filter the rest

On some blocks, the author lets a click filter the other blocks. This filter is a cross-filter. Before the first click, the filter chip in the header of the block opens a list that ends with A click on this block filters by …. To learn about the tag, read the section See where a filter reaches.

1. Click a bar, a point, a slice, a legend entry, or a table cell. Every block in the reach of the filter narrows to that value. On the chart you clicked, the other marks fade.
2. To add a value, hold Ctrl, Cmd, or Shift and click it. The same click on a value already in the filter removes it. A filter that takes one value only changes to the new value.
3. To clear the filter, click the same value again, or click the empty space of the chart.

On a chart with the rich tooltip, you can also filter from the tooltip: select Keep only or Exclude in it (see Read the values under the pointer).

On a chart with a bar for each week or each month, a click filters to the dates of that bar: a week bar sets the seven days of that week, a month bar the days of that month. The filter is a date range of its own, so your range on a date-range control of the same column stays as it is, and the other blocks draw only the dates that both ranges hold. To move the range, click another bar. To clear it, click the same bar again. When you move the control so that it no longer holds the bar you clicked, the click clears.

The author of the chart can make its click set the date-range control instead: then a click on a bar changes the control's range to that bar's dates.

To filter to a stretch of dates, drag across the chart from the first date to the last. The range covers every bar the drag touches, and a shaded band marks it on a line chart. On a chart of numbers, such as a scatter plot or a histogram, a drag across the axis filters to the numbers between its two ends, and a drag on a scatter plot draws a box across both axes. A drag works with a mouse or a pen. On a touch screen a drag moves the canvas, and a tap filters.

The block you click does not filter itself. It keeps the full chart, so your next click can pick a different value, and it fades the marks outside the filter so you see what you picked. A control bound to the same filter shows the clicked value, and its Clear removes the filter.

Filter with the keyboard

1. Press Tab until the chart has focus. A screen reader reads the chart's title, a summary of its data, and the keys to use.
2. Press the arrow keys to move from mark to mark. A ring shows the mark, and a box beside it shows its values, as the pointer's tooltip does. On a chart with the rich tooltip, the box is the rich tooltip. A screen reader reads the same values. Up and Down move to the next series. Home and End move to the first and the last mark.
3. Press Enter to filter by the mark. Press Space to add the mark to the filter.
4. Press Escape to close the box of values. Press Escape again to clear the filter of the chart.

See where a filter reaches

A filter does not always reach every block. On the control and on each block, you see where a filter applies.

Open a control, or rest the pointer on it, and the canvas outlines the blocks that its filter reaches. A chart that filters by click does the same: rest the pointer on a bar or a point you can click, or move through its marks with the keyboard, and the canvas outlines the blocks the click filters. After a click, the outlines stay until the pointer leaves the chart.

• An accent outline — the filter reaches this block.
• A warning outline — the block is in scope, but its data does not have the column. The filter does not apply there.
• A dashed outline — this chart sets the same filter by click. It filters the other blocks, and not itself.
• An accent outline with a tint — a control whose value the click changes.

Each data block (a chart, a scorecard or a table) that a filter touches shows a chip in its header, such as 2 filters: the count of the filters that apply to it, fixed filters included. Not filtered means that a filter is set, but no filter applies to this block. A block with no chip has no filter on it. With Clean view on, you see the chip only when you point at the block or move the keyboard focus to it (see Read the charts without the filter labels). Click the chip to see each filter, with its value and its result here:

• Filters this block — the filter applies here.
• Set by a click on this block — the block sets this filter by click, so the filter skips it.
• A skipped filter names its reason: the data has no "…" column, the block is outside the filter's scope, or the block ignores this filter. The scope and the ignore are choices the author made, and only an editor changes them. On a block whose datasource has no saved data yet, the row says so instead: an editor runs the datasource in the Data workspace.
• Fixed on this block — a filter that the author fixed on the block itself. No control sets it, and it has no Clear. To change it, ask an editor of the dashboard.
• A click on this block filters by … — a click here filters the other blocks. Nothing is selected yet.

Each filter that a control or a click sets has Clear, and Show the control when a control on the dashboard sets it. Clear removes the filter from every block it reaches, in your view only, and the blocks redraw. Show the control moves the canvas to that control. Press Escape or click outside the list to close it.

Share the view

The page address holds every value you set: the selections, the dates, the tests, the Exclude mode, and your Chart options adjustments.

1. Set the filters.
2. Copy the address from the address bar of the browser.
3. Send the link. The recipient sees your exact filtered view, if they have access to the dashboard.

A reload keeps your values. Opening a different dashboard resets them.

For authors: set the defaults

Which controls exist, what they open on, and which blocks they reach are part of the dashboard. The author sets them in edit mode.

Add a control

A control is the widget, and a param is the value it sets. Two controls on one param share one value: a pick in one of them shows in the other, and both filter the same way.

1. In edit mode, click Add in the header.
2. Click Control. The control appears in the middle of the part of the canvas you see, selected, with its Control card at its left. Until the control has a param, it shows a message that it is not bound to a param yet. This message is expected. To move the control, drag it by its header.
3. Give the control its value:
   • To filter on a column, drag the column from a Fields list onto the Field row of the Control card. You can also click Field and pick the column. The control gets a new param, named after the column, with the type that fits the column.
   • To make the control set the same value as another control, click Param and pick that control's param.
   • To make a slider or a dropdown of fields, click Param, choose Create new param…, and read Add a slider or a field choice.

The message on the control goes away, and the control shows its widget, such as a list of the values of the column. Pick a value, and the blocks that the filter reaches redraw with the filtered rows. To set the default, the type, and the blocks the filter reaches, read Configure a control.

Add a slider or a field choice

A filter narrows the rows. A slider and a field choice filter nothing: they hold a value that charts, scorecards and titles read. Use a slider for a what-if number, such as a growth rate. Use a field choice to let the reader change what a chart shows, such as its breakdown or its metric.

1. Add a control. In its Control card, click Param and choose Create new param….
2. In What it does, choose Sets a number (a slider) or Picks a field (a dropdown).
3. Type a Name, such as growth, and click Create param. Formulas and titles use this name, so use letters, digits and underscores only, with no spaces.
4. For a slider, click Range in the Control card and set the Minimum, the Maximum and the Step. The slider holds the plain number, so a rate from 0% to 20% runs from 0 to 0.2. In Format, type .0% to show 0.05 as 5%, or ,.2f for a number with two decimals.
5. For a field choice, click Choices in the Control card and tick the columns and the measures the reader may pick. A measure is a named SQL calculation on the datasource, such as revenue per order: read How a dashboard works.
6. To set the value the control opens on, set the control on the canvas, then make it the default: read Configure a control.

The control now shows a slider set to its default, or a dropdown of the fields you ticked. Then make the blocks read the value:

• A slider in a number. Define a measure on the datasource whose SQL reads the slider as @ and its name, such as sum(revenue) * (1 + @growth), and show that measure in a scorecard or a chart. The number changes as the reader moves the slider.
• A slider in a title. Type the name in braces in a block's title, such as Revenue at {growth} growth. To edit a title, double-click it. The title shows the value in the slider's format, such as 5%.
• A field choice in a chart. Select the chart, and open the block of the channel that holds the breakdown: X for the bars of a bar chart, or Color for its series. Set Follows to the param. The chart then shows the field the reader picks, with its axis title and its number format. The same Follows row sits under a scorecard's field.

A chart does not draw a choice that its datasource lacks. If a choice shows nothing, open the Findings panel: it names each choice that a block cannot draw. A name in braces that matches no param stays in the title as typed.

Configure a control

In edit mode, select the control. Its Control card shows at its left, and each row of the card says what it holds now. Click a row to change it. Each change applies as you make it, and the canvas is the preview.

• The type, at the top of the card — Select (one value), Multi (a set), Dates (a date range), Text, or Number. Only the types that fit the field take a click. A change of type clears the default when the new type cannot hold it, and a notice names what it cleared. Then set a new default.
• Param — the value that the control sets. The control is the widget, the param is the value, and one param can drive several controls. Create new param… asks first what the param does. For a filter, pick the column, and the name and the best-fit type fill in.
• Field — the data column, matched by name in every datasource that has it. Drag a column onto the row, or click the row and pick one. A new control takes the name of its field as its title. The title follows the field until you type a title of your own.
• Applies to — the blocks that the filter reaches. Read Pick the blocks a control filters.
• Default — the value the dashboard opens on. Set the control on the canvas to that value, then click Default and Make this the default. The default keeps everything the control shows: the values, the Exclude mode, and the test of a text or number control. A date range keeps the way you picked it: Last 30 days or This month to date moves with the calendar, and dates you picked by hand stay fixed. A dot after the row says that the canvas shows another value than the default. Clear default makes the control open with no value. A control with no default shows a dim dash in the row: point at it to read "No default". In the popover, an empty value also shows as a dim dash.
• Order — on a list, sorts the options by a measure. Each sorted option shows a bar with the number beside it.
• Match case — on a text control, makes its tests match case.
• Title, in the folded Block card under the Control card — the title of the block, and the Label the control shows above its widget.

Pick the blocks a control filters

A new control filters every data block whose data has its column. To filter fewer blocks:

1. Select the control, and click Applies to in its Control card.
2. Click Pick on canvas. Each block that the control filters shows a ring and a check mark.
3. Click a block to add it or to take it out. To add or take out every block in a section or a frame, click the button on the label of the section or the frame.
4. Click Done, or press Escape.

The Applies to row now reads how many blocks the control filters, such as 2 of 5 blocks. The same popover holds a checklist for the keyboard. Frames and sections are in it, each above the blocks in it. A block included through its section reads (via its section). When you drag a block into the section, the filter reaches it. When you drag a block out, the filter stops reaching it. A frame works the same way, for every block on that page, and its blocks read (via its frame).

Exempt a block, or fix a filter on it

A chart, a scorecard and a table each have a Filters group: the filtering of the block itself, separate from any control. Select the block and open its Filters block.

• Ignore dashboard filters exempts the block from every control. For example, use it for an all-time total on a dashboard filtered by date.
• Add filter adds a fixed clause that the block always applies: a column, an Is or Is not choice, and a value. Match several values changes the value to a set. No widget sets a fixed clause, and no viewer clears one.

The group cannot set two things, and it says so: an exemption from individual params, and a date-range clause. Write those in the Source panel, or open Code in the block's folded Block card and select Edit as JSON.

Turn on cross-filtering

The Cross-filtering group turns on cross-filtering with one switch. On a chart and on a table it is the Cross-filter block. On a chart, it offers the category fields and the date fields of the spec. On a table, it offers the shown columns. The switch uses a param that already filters that column, or makes a new param named after the column. A date field uses a date-range param, so a click sets the dates of the clicked bar. To remove the click rules of the block, turn the switch off. The param stays.

Compare with an earlier period

A chart can draw its series twice: the current period, and an earlier period for comparison. The earlier period is dashed on a line and lighter on an area, in the same color. A scorecard shows the change against the earlier period under its number. A table that sums values by rows shows a change column after each value. The author turns the comparison on in the Comparison block of the chart or the scorecard, or in the table's settings. A date-range control that reaches the block sets the current period, so one date pick moves both periods.

Previous period follows the period you pick. Pick This month to date, and the earlier period is the previous month up to the same day. Pick Last quarter, and it is the quarter before. Pick dates by hand, and it is the same number of days just before them. Previous year is the same dates one year back.

You can turn the comparison on or off for your own view. Point at a chart, a scorecard or a table in view mode and choose its options button in the header: Chart options, Scorecard options or Table options. The popover holds the Compare with an earlier period switch and the mode: Previous period, Previous year, or Custom range. The adjustment goes into the page address like any filter value. The dashboard keeps the author's default.

Let viewers switch the dates of every chart

A Dates picker switches charts between day, week, month, quarter and year. It also reaches the trend lines of scorecards and tables. A chart takes the picker when:

• it draws one view, with no facet, concat or repeat,
• it has one date field on its x or y axis,
• its value has an aggregate, such as sum, average or count,
• its spec has no transform other than filter and calculate,
• Viewers can switch the date grain is on, under Date grain in the Chart card. It is on by default.

To add the picker:

1. Open Dashboard settings: the gear on the icon rail at the right edge.
2. Under Numbers and dates, turn on the Dates picker switch.
3. In Starts at, pick the grain a reader sees first, or keep Each chart's own grain.
4. Reaches lists only the blocks that the picker can switch. Clear each block that the picker must leave alone.

The Dates picker then shows at the bottom right of the canvas, beside the zoom control. The dashboard saves itself, so readers see the picker when they open it. The published page gets the picker when you update the published copy (see Publish it to the internet).

The picker offers only the grains that every block it reaches can draw. You cannot choose them. For example, a date column by month offers month, quarter and year.

If no block on the dashboard has dates the picker can switch, the section says so. To make a chart eligible, give it a date on its x or y axis and an aggregate on its value. A reader's pick goes into the page address like a filter value. A pick in a chart's own Chart options wins over the picker for that chart.

For downloads, fullscreen, and the age of the data, read Read a dashboard.