Controls
Add dynamic viewer inputs to dashboards that change data or chart structure at runtime
Controls are dynamic inputs -- dropdowns, toggles, text fields, date pickers -- that dashboard authors define and viewers interact with. When a viewer changes a control value, affected cards re-query automatically.
Controls and Filters
Controls work alongside filters, not as a replacement. Filters narrow rows in the result set using {{ filters | where }} syntax. Controls are more general -- they let viewers control the logic flow of queries, switch which metric or dimension is displayed, change aggregation functions, or adjust time granularity. You can use both on the same dashboard.
Dashboard Controls vs Card Controls
Controls can be defined at two scopes:
| Scope | Where it appears | Who uses it | Best for |
|---|---|---|---|
| Dashboard | Dashboard toolbar, alongside filters | All cards that reference it | Shared inputs like "Region" or "Time Grain" that affect many cards |
| Card | Card header area | Only the card it belongs to | Card-specific toggles like "Show Estimated vs Actual" or a metric switcher local to one chart |
Dashboard controls let multiple cards reference the same input. When a viewer selects a value, every card that references that control updates together.
Card controls are scoped to a single card. They appear in the card header and only affect that card's query or configuration.
Control Types
Controls fall into two categories: value controls that produce a literal value for use in SQL, and structural controls that modify a card's visual configuration.
Value Controls
Value controls produce a literal value that you can reference in SQL queries using the [[param.control_id]] placeholder syntax.
| Type | Input Widget | Value Type |
|---|---|---|
enum | Single-select dropdown | string |
multi_enum | Multi-select dropdown with checkboxes | string[] |
text | Text input | string |
number | Numeric input | number |
boolean | Toggle switch | boolean |
date | Date picker | ISO date string |
See SQL Controls for placeholder syntax and examples.
Structural Controls
Structural controls modify a card's visual configuration rather than substituting values in SQL. They work with cards built using the visual explorer (drag-and-drop mode).
| Type | What it changes |
|---|---|
field_selector | Swaps the dimension or grouping field |
metric_selector | Swaps which metric is displayed |
aggregation_selector | Changes the aggregation function (SUM, AVG, COUNT, MIN, MAX, MEDIAN, DISTINCT) |
grain_selector | Changes the time granularity (day, week, month, quarter, year, hour, minute, second) |
See Structural Controls for configuration details.
Where Options Come From
Each control needs a set of options for the viewer to choose from. Semaphor supports several sources depending on the control type:
| Source | Description | Used by |
|---|---|---|
| Manual list | Author defines a fixed set of options with labels and values | enum, multi_enum |
| Dataset values | Options loaded dynamically from distinct values of a field in the connected database | enum, multi_enum |
| Field allowlist | A set of dimension fields the viewer can choose from | field_selector |
| Metric allowlist | A set of metrics the viewer can choose from | metric_selector |
For aggregation_selector and grain_selector, the available options come from the built-in list of supported aggregations and time grains.
Control Properties
Every control supports a common set of properties that govern its behavior and visibility.
| Property | Description |
|---|---|
defaultValue | The initial value when the dashboard loads |
required | Must have a value before the query runs. If required and no value is set, the card shows an error state |
hidden | Control exists and has a value but is not visible to viewers. Useful for programmatic or embed-only controls |
locked | Control is visible but viewers cannot change its value. Useful for showing context without allowing edits |
helpText | Tooltip text shown to viewers on hover |
placement | Where the control appears: toolbar (dashboard toolbar), card_header (card title area), or advanced (behind a "More options" button) |