Map Filters to Cards

Dashboard filters often need to work across cards built from different datasets or tables. The fields may represent the same business concept without having the same name.

For example, one Customer filter can apply to:

• customer_id on an Orders card
• cust_id on a Payments card
• account_customer_id on a Customer activity card

Semaphor lets you configure this once in the filter settings. Viewers make one selection, and each card applies that selection to the field you chose for it. No join between the cards is required.

Open the filter settings

You configure filter options and card fields from the filter's settings:

1. Open the dashboard and select Edit.
2. Find the filter in the dashboard filter bar.
3. Select the Settings icon next to the filter.
4. Use Basic to configure the filter's option value and label.
5. Use Cards to review or change the field used by each card.

If the dashboard does not have the filter yet, add it from the filter bar first, then open its settings.

Choose what viewers see and what queries use

In the filter settings, select the Basic tab.

Two settings determine how filter options work:

• Option Value Field is the value Semaphor sends to card queries.
• Option Label Field is the text viewers see in the filter menu and in the selected filter.

The fields can be the same. Use different fields when the query needs a stable identifier but viewers should see a friendly name.

For example, a Project filter might use:

Viewers see Beacon Platform, while Semaphor sends 5112 to each card. The label is for display only; it is never substituted for the value in a query.

To use separate fields:

1. Select the field that should supply the Option Value Field.
2. Turn on Use a different field for the option label.
3. Select the field that should supply the Option Label Field.
4. Select Accept to save the filter.

Review which field each card uses

Open the Cards tab in the filter settings to see how the filter applies to the cards on the dashboard.

Semaphor checks each card's configured data source and looks for a compatible field:

• Auto means Semaphor found one compatible field and will use it automatically.
• Choose a field means more than one field could receive the filter. Select the field that represents the filter's value on that card.
• Not applicable means the card does not have a compatible field in its configured data sources.
• Not applied means the author intentionally excluded the card from the filter.

You only need to save exceptions. Cards with an unambiguous compatible field continue to use Auto, including compatible cards added to the dashboard later.

Change the field for one card

Suppose the dashboard filter uses customer_id, but a Payments card stores the same value as cust_id:

1. Open the filter settings and select Cards.
2. Find the Payments card.
3. Open its field menu.
4. Select cust_id.
5. Select Accept.

The filter continues to use automatic fields on the other cards. Only the Payments card uses the override.

Leave a card unaffected

If a card should not respond to the filter, choose Not applied for that card. The card continues to run normally when viewers change the filter.

Config-driven cards

For cards built with the visual editor, Semaphor reads fields from the card's base data source and any joins already configured on the card.

The target field does not have to be displayed in the visualization. For example, a chart can group dashboard counts by month and still receive a Project filter through project_id, even when Project is not shown on the chart.

Semaphor does not add a new join merely to apply a filter. If the field you need belongs to another table or dataset, add that source and relationship to the card first. Then return to the filter's Cards tab and select the field.

SQL cards

SQL cards can receive the same dashboard filters as config-driven cards. To make the available fields explicit, configure both the card's data source and its SQL filter helper.

1. Select the card's data source

In the SQL card editor, add the dataset or table used by the query to the card's Data Source. Semaphor uses the selected sources to populate the field menu in the filter's Cards tab.

Semaphor does not inspect custom SQL to guess which datasets, tables, aliases, or fields it uses. If no data source is selected, the Cards tab asks you to select one in the SQL editor.

2. Add the dashboard filter helper

If the SQL does not already contain a WHERE clause, add:

SELECT *
FROM customers
{{ filters | where }}

If the SQL already contains a WHERE clause, add:

SELECT *
FROM customers
WHERE status = 'active'
{{ filters | and }}

The helper tells the SQL card where to add the active dashboard filters. If it is missing, the Cards tab explains that dashboard filters are not enabled for the card.

3. Select the SQL field

Return to the dashboard filter's Cards tab and select the field the SQL card should receive. For example, a Customer filter can use customer_id normally and use cust_id for one SQL card.

The selected name is the name Semaphor sends to the SQL filter helper. Make sure it is valid for the custom SQL you authored.

For additional SQL filtering patterns, including selecting or excluding specific filters, see Filters.

Apply one date range to different date fields

A regular dashboard date filter can represent the same date concept across cards even when those cards use different field names.

For example, a Purchases dashboard might contain:

Viewers choose one range, and each card applies it to the selected date field.

Use a mapped dashboard date filter when you need to choose a particular date field for each card, include SQL cards, or offer more than one independent date filter. If you want one automatic time window based on each config-driven card's primary date, use the Global Date Filter instead.

When a card's data source changes

Changing a card's dataset, table, or joins can make a previously selected field unavailable. Open the filter's Cards tab after changing a card's data source and select a compatible field if Semaphor asks you to update it.

Cards for which Semaphor can still identify one compatible field continue to use Auto.