Docs/Semantic Layer/Filter Mappings

Filter Mappings

Tie one canonical filter name to the node.field locations it should apply across multiple nodes, so a single global filter touches the right column everywhere.

WeaverLuminaryUpdated June 2026 · 6 min read

✦

In this section

Part of Celiq's semantic layer platform. Connect your warehouse, model your data once, query it everywhere.

💡

Tip

What it is: A governance object that maps one canonical filter name (like Country or Date Range) to the physical node.field locations it should apply across many nodes.
When to use it: When a single global or cross-node filter needs to hit the right column on every node — even when those columns are named differently from node to node.
Where to find it: Context Studio → Filter Mappings.
Who can use it: Weaver and Luminary can create, edit, and delete mappings. Everyone in the workspace can view them.

A filter mapping records, once, that the canonical filter "Country" lives in orders.country, customers.country, and marketing.country. With that mapping in place, Celiq knows which physical field a global filter for Country should touch on each node, so one filter reaches the right column everywhere instead of only on the node you happened to be looking at.

📝

Note

You may hear this feature called Cross Filter Mappings. That is naming drift — the product UI and API both say Filter Mappings. This page uses the real name.

Overview

Filter Mappings is a workspace-level list managed in Context Studio. Each row is one canonical filter name plus the set of node.field locations it maps to. The section shows:

Filter Mappings header with an + Add mapping button.
One card per mapping. Each card shows the canonical name in bold and a row of badges, one per mapped field, each printed as node.field.
A delete control on each card.
An empty state — "No filter mappings yet." — when the workspace has none.

The list is sorted alphabetically by canonical name and excludes anything that has been deleted, so what you see is the live set of active mappings for the workspace.

When to use it

One filter, many nodes. You want a Country or Date Range filter that applies to orders, customers, and marketing at once, and each node stores that value in its own column.
Inconsistent column names. The same business concept is called country on one node and country_code or ship_country on another — a mapping records exactly which field to use on each.
Governing cross-node filtering centrally. Rather than re-wiring filters per dashboard, you define the canonical-to-physical mapping once and let it apply across the workspace.

Concepts

Term	Meaning
Canonical name	The single business-facing name of the filter, such as `Country` or `Date Range`. This is what a global filter refers to.
Mapping	One `node.field` location the canonical filter resolves to. A filter mapping holds a list of these.
node.field format	How each mapped field is written: the node name, a dot, then the field name — for example `orders.country`.
Status	The lifecycle flag on a mapping. Active mappings appear in the list; deleting one sets its status to `deleted` so it is hidden but not physically removed.
Soft delete	Deletion marks the row `status = 'deleted'` rather than dropping it, so it disappears from the list while the record is retained.

Getting started

You need a workspace with modelled nodes, and you need to know which node and field each canonical filter should map to. Creating, editing, and deleting mappings requires the Weaver or Luminary role.

Open Context Studio

From the main navigation, go to Context Studio.

Open Filter Mappings

In Context Studio, select Filter Mappings. The current list loads automatically.

Confirm your role

The + Add mapping button and the delete control are available to Weaver and Luminary. If you only have view access, you can read mappings but not change them.

Step-by-step

Start a new mapping

Click + Add mapping. A small form appears with two inputs.

Name the canonical filter

In the first input, type the canonical name — for example Country or Date Range. This field is required; an empty name cannot be saved.

List the fields it maps to

In the second input, enter the physical fields as a comma-separated list in node.field format, for example:

orders.country, customers.country, marketing.country

Celiq splits this on commas and parses each entry into a node and field pair, so the helper text reads "Use node.field format. This tells Celiq which physical fields a global filter should touch."

Save

Click Save. The new mapping is added to the top of the list, and the form clears. Click Cancel at any time to discard the form without saving.

Review the card

The saved mapping appears as a card: its canonical name in bold, and one badge per mapped field rendered as node.field.

Delete a mapping you no longer need

Click the trash control on a card and confirm "Delete this filter mapping?". The mapping is removed from the list. This is a soft delete — the record is marked status = 'deleted' and stops appearing in the list.

Examples

Suppose Country is stored on three different nodes, each in its own column. You create a single mapping:

Canonical name: Country
Fields: orders.country, customers.country, marketing.country

Celiq stores the parsed mapping as a list of node/field pairs:

json

{
  "canonical_name": "Country",
  "mappings": [
    { "node": "orders",    "field": "country" },
    { "node": "customers", "field": "country" },
    { "node": "marketing", "field": "country" }
  ]
}

A Date Range mapping where the columns differ by node looks like this — note ship_date on orders:

json

{
  "canonical_name": "Date Range",
  "mappings": [
    { "node": "orders",    "field": "ship_date" },
    { "node": "marketing", "field": "event_date" }
  ]
}

Each entry is split on the first dot, so the part before the dot becomes node and the remainder becomes field. After saving, the card for Date Range shows two badges: orders.ship_date and marketing.event_date.

Best practices

Use exactly one mapping per canonical concept. Keep all of Country's locations in a single Country mapping rather than splitting them across several rows.
Match node and field names to your model. The node and field you type must correspond to real nodes and columns, since this is what a global filter resolves against.
Name canonically, not physically. The canonical name is business-facing (Country), while the node.field entries carry the physical detail — keep that division clean.
Add every node the concept appears on. A mapping only reaches the fields you list; a node you leave out will not be touched by the global filter.

Tips

💡

Tip

When a concept is stored under different column names across nodes — country here, ship_country there — that is exactly what a filter mapping is for. List each node with its own correct field, and one canonical filter resolves correctly on all of them.

Common mistakes

⚠️

Warning

Leaving the canonical name blank. The name is required and a blank name is rejected — fill in the first input before saving.

Skipping the node.field format. The Fields input is split on commas and each entry on its dot. Write orders.country, not just country, so Celiq can tell which node and field you mean.

Creating duplicate canonical names. Two separate rows for the same concept (for example two "Country" mappings) fragment the mapping — keep all locations in one row.

Troubleshooting

Symptom	Cause	Fix
Save does nothing	The canonical name input is empty or whitespace only; the form will not submit.	Type a non-empty canonical name, then click Save.
A field badge shows the whole text instead of node.field	The entry had no dot, so it could not be split into a node and a field.	Re-enter the field in `node.field` format, e.g. `orders.country`.
A mapping you deleted is gone but you want it back	Delete is a soft delete — the row is marked `status = 'deleted'` and hidden from the list.	Re-create the mapping with the same canonical name and fields.
+ Add mapping / delete controls are missing	You do not have a role that can change mappings.	Creating, editing, and deleting require the Weaver or Luminary role.
"Loading filter mappings…" stays on screen	The list could not be fetched.	Reload the page; if it persists, confirm you are signed in to the workspace.