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.

Every dashboard filter has a Cards tab, whether it sits in the filter bar or in a Document's input bar. It lists regular cards and Document section cards alike, so one filter can map onto both. The Global Date Filter is the exception: it uses each card's primary date instead.

A filter's sheet scope sets the boundary for these card mappings. Choosing a field for a card does not extend the filter to a sheet outside its scope. Filter scope explains how shared and sheet-specific filters work.

The Cards tab controls where a selection applies. Narrow available options by, in Basic, controls which other selections change the choices in the filter menu. See Cascading Filters for examples of independent and related option lists.

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, or in a Document's input 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 first: from the filter bar, or from the Inputs group of a Document's side panel. 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 Done 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 it reaches. Cards are grouped by sheet. A card in a Document section also shows the section's title. Select Review as table to see every card with its status in one list.

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.
• Suggested · Region means the card has a field with the same name on another dataset. The card isn't filtered until you select Use.
• Auto · through Project means the card applies the filter through its semantic domain's relationships. See Cards on related datasets.
• Choose a path means the filter reaches the card through more than one relationship path. Select the path the card should use.
• Not applicable means the card does not have a compatible field in its configured data sources, and no relationship connects it to the filter.
• Not applied means the author set the card to Don't apply this filter.

The settings icon on the filter shows a warning only when something needs fixing: a card needs a field chosen, or a saved mapping no longer works. Suggestions and paths to choose appear in the Cards tab without a warning.

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 Done.

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, open its field menu and choose Don't apply this filter. The card shows Not applied and continues to run normally when viewers change the filter. A required filter does not hold it back.

Document section cards

When a filter reaches a Document sheet, the Cards tab lists the cards in that Document's table, Matrix, and KPI sections. Map them the way you map any card: keep Auto, choose a field, or choose Don't apply this filter.

For example, an Account filter can apply to account_id on a statement table and to billing_account_id on a KPI that reads from a billing dataset. The report's tables and KPIs then stay in step with one selection in the input bar.

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.

A filter on another dataset of the card's semantic domain reaches the card through the domain's relationships, without a new join. See Cards on related datasets. For cards on database tables, or cards with joins you configured, add the source and its join to the card first, then return to the filter's Cards tab and select the field.

Cards on related datasets

When a card is built on a semantic domain, a filter on a related dataset applies to it automatically. A Project filter filters a Dashboards card through the domain's relationship from Dashboard to Project, even though the card shows only dashboard fields. Any field of the filter's dataset works: the project's name, its region, or the organization two relationships away.

It works in both directions:

Each row is counted once, however many related rows match, so totals and lists stay correct.

An exclusion keeps the rows that have at least one related row that matches it. For example, Dashboard type is not Report on a Projects card keeps every project with at least one dashboard that isn't a report, including a project that also has reports. A project with no dashboards drops out while the filter has a value.

See how each card applies it

The Cards tab shows what each card will do:

• Auto · through Project means the card applies the filter through its relationship to Project.
• Auto · Projects with at least one matching Dashboard means the card keeps each project that has a matching dashboard.
• Choose a path means two relationships connect the card to the filter equally well, for example a dashboard's current project and the project it was archived from. Open the card's menu and pick a path under Paths. Until you do, the card isn't filtered by it, and Automatic at the top of the menu says so. You can switch to another path, or back to Automatic, at any time.
• Not applicable with a reason, such as Not related to Dashboard, means the domain has no relationship that connects them.

You can still choose a field on the card instead, or choose Don't apply this filter. If someone with access to the semantic domain changes a relationship a card's chosen path uses, the card shows The relationship this card used changed; choose it again. Select Automatic or pick a path again.

When you can edit the semantic domain, Manage relationships opens it from the Cards tab.

Viewers see the same explanation in each card's filter details, for example Filtered through Project or Connects through more than one path.

Cards on database tables, SQL cards, and cards with joins you configured apply filters as described in the rest of this page.

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 in SQL.

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.