Structural Controls
Let viewers switch metrics, dimensions, aggregations, and time grains on visual cards
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), not raw SQL cards.
When a viewer changes a structural control, Semaphor rebuilds the card's query based on the new configuration and re-fetches data automatically.
Field Selector
Lets viewers choose which dimension field to group by.
Example: A bar chart showing "Revenue by Country" can have a field selector that lets viewers switch to "Revenue by State" or "Revenue by City" -- without editing the card.
The author defines a field allowlist specifying which dimension fields are available. Each option maps to a complete field configuration including the column name, data type, and display settings.
When to use: Dashboards where viewers need to explore data across different grouping levels (geographic, temporal, categorical) on the same chart.
Metric Selector
Lets viewers choose which metric to display.
Example: A KPI card showing "Total Revenue" can have a metric selector that lets viewers switch to "Total Orders" or "Average Order Value".
The author defines a metric allowlist specifying which metrics are available. Each option includes the column, aggregation function, and display formatting.
When to use: Cards that compare related KPIs, or dashboards where different viewers care about different measures.
Aggregation Selector
Lets viewers change the aggregation function applied to metrics.
Available aggregations: SUM, AVG, COUNT, MIN, MAX, MEDIAN, DISTINCT.
Example: A card showing the SUM of revenue can let viewers switch to AVG to see average revenue per row, or COUNT to see the number of records.
When to use: Analytical cards where the same underlying data benefits from different summary statistics.
Grain Selector
Lets viewers change the time granularity for temporal groupings.
Available grains: second, minute, hour, day, week, month, quarter, year.
Example: A time-series chart grouped by month can let viewers switch to a daily view for more detail or a quarterly view for high-level trends.
When to use: Time-series charts where viewers need to zoom in or out across different time horizons.
Dashboard-Scoped Structural Controls
When you create a structural control at the dashboard level, you can select which cards participate. Semaphor finds compatible fields or metrics across those cards and creates the mappings automatically.
When a viewer changes the control, all participating cards update together. This keeps related charts in sync -- for example, switching the time grain from "month" to "week" on a dashboard control updates every time-series chart at once.
Cards that do not participate in the dashboard control are unaffected.
Current Card Setup Option
Structural controls support a "Current card setup" option that preserves the card's existing configuration. This acts as a default -- the card renders normally until the viewer makes a different selection.
This is useful when the card already has a good default configuration and the structural control is an optional way to explore alternatives.