User Guide
Learn how to use semantic domains to build dashboards and explore data
Using Semantic Domains in Dashboards
Once your administrator has set up a semantic domain with datasets and relationships, you can use it to explore data across multiple datasets without writing any SQL or manually configuring joins.
Quick Start
- Pick the card's dataset from the dataset dropdown at the top of the editor. Search it, or choose Browse all data to see everything you can use.
- Open a folder to use a related dataset's fields. Each dataset your dataset reaches is a folder where its key is: Customer sits where
Customer IDwas. - Drag fields onto the shelves. The query joins the related datasets through the relationships your administrator defined.
Key benefit: no join configuration. A card starts from one dataset, and the domain's relationships bring in the rest.
Step 1: Pick the Card's Dataset
A card starts from one dataset. The dropdown lists the datasets already used on this dashboard, then each domain's datasets. Type to search across all of them, or choose Browse all data for the full list.
To change the dataset later, pick another one from the dropdown. Fields the new dataset can still read stay on the card: a field with the same name and type, and any field from a dataset the new one also reaches. The others are removed, and a message lists both, with Undo.
Step 2: Fields in Folders
The field list shows your dataset's fields first. Every related dataset appears as a folder in place of the key that reaches it, and opens to that dataset's fields, with the key itself listed first. A dataset reached through another one is a folder inside that one (Customer › Sales territory).
Field list features:
- Search: filters fields by name, label, or description and opens every folder with a match
- Category tabs: all fields, dimensions, measures, or calculated fields
- Folders: one per related dataset, named after its key when the key points at that dataset
A placed field from a related dataset shows the folder you picked it from first on the shelf: Customer › Segment.
Cards on database tables
A card built on a database table instead of a dataset reaches other tables through joins you set on the card. See Joining Tables on a Card.
Datasets with no relationships
A dataset with no relationships, such as a wide table that already holds every column, shows only its own fields. A card built on it reads that one dataset.
Domain-Level Calculated Fields
Your administrator may have added metrics and calculated fields to the domain. These appear in the field list with a Domain badge.
You can use domain-level calculated fields just like any other field - drag them into your visualizations, use them in filters, and combine them with other fields. However, these fields are managed by administrators, so you cannot edit or delete them.
Table and SQL Datasets
Some datasets read a table and others read a SQL query. They behave identically in the field list: relationships, auto-joins, and filters all work the same way.
Step 3: Folders That Need Attention
- Needs setup: the dataset is related through a relationship that doesn't join automatically. Choose Set up join on the folder to confirm how it joins; the join dialog opens with the relationship's keys filled in.
- Not reached: a saved card may still name a dataset its dataset no longer reaches (a relationship changed). Remove it from the card with the folder's remove button.
Step 4: Selecting Fields Across Datasets
Example workflow: Sales by customer segment
- Start from
orders: pick it in the dataset dropdown and dragrevenueto Metrics - Open the Customer folder and drag
segmentto Rows - Result: the query joins
orderstocustomersthrough the relationship your administrator defined
What happens behind the scenes:
- The card reads fields from
ordersandcustomers - The relationship between them (for example
orders.customer_id = customers.id) says how they join - The query joins them, LEFT unless the relationship says otherwise
Step 5: Viewing Resolved Joins
After running a query with joined datasets, the Resolved joins panel in the Visual tab shows:
- Number of joins resolved automatically
- Join details for each relationship:
- Source and target datasets (e.g.,
orders → customers) - Join type (INNER, LEFT, RIGHT, FULL)
- Join conditions (which fields are matched)
- Source and target datasets (e.g.,
Example:

Understanding Multi-Hop Joins
Multi-hop joins connect datasets through intermediate datasets when no direct relationship exists.
Example: Analyzing orders by country
- Orders connects to Stores (hop 1)
- Stores connects to Countries (hop 2)
- Result: Orders → Stores → Countries
How to identify multi-hop joins:
- A folder inside a folder in the field list (Store › Country)
- Join path shown in the field's hover preview
- Multiple joins listed in the Resolved joins panel
When to use:
- Geographic hierarchies (stores → countries)
- Organizational structures (employees → managers → departments)
- Time rollups (daily → monthly → quarterly)
When to be cautious:
- May be slower on large datasets
- Check row counts match expectations
Common User Scenarios
Scenario 1: Simple Cross-Dataset Analysis (1-Hop)
Goal: Analyze total order revenue by customer segment
Steps:
- Pick
ordersfromSales Analyticsin the dataset dropdown - Drag
revenue→ Metrics - Open the Customer folder and drag
customer_segment→ Rows
Result:
- Semaphor auto-joins
orderstocustomers - Chart shows revenue grouped by customer segment
- Auto-join panel shows:
orders → customers [LEFT JOIN]
Scenario 2: Multi-Hop Join (2-Hop)
Goal: Show order revenue by country name
Steps:
- Pick
ordersfromSales Analyticsin the dataset dropdown - Drag
revenue→ Metrics - Open Store, then Country inside it, and drag
country_name→ Rows
Result:
- Semaphor creates a 2-hop join through
stores - Auto-join panel shows both joins:
- Join 1:
orders → stores [LEFT JOIN] - Join 2:
stores → countries [LEFT JOIN]
- Join 1:
- Chart displays revenue by country
Using Metric Transforms with Domain Fields
You can apply metric transforms (running totals, moving averages, period-over-period deltas, percent of total) to any numeric metric from a semantic domain.
When configuring a transform on a domain metric:
- Order By auto-detects the first date field from your group-by columns
- Reset By (partitioning) auto-populates with all group-by fields except the order-by field
- Transforms work across auto-joined datasets -- you can apply a running total to a metric from one dataset while ordering by a date field from a related dataset
Transforms and Calculated Fields
Metric transforms can be applied to both regular domain metrics and domain-level calculated fields. For example, you can create a calculated metric for "Profit Margin" in the domain and then apply a moving average transform to track how it trends over time.
Next Steps
Now that you understand how to use semantic domains:
- Explore your data: Start building dashboards with auto-join enabled
- Leverage relationships: Use multi-hop joins to answer complex questions
- Review joins: Check the Resolved joins panel to understand join logic
- Ask for help: Request new relationships from your admin when needed
- Share insights: Document your analyses and share with your team
If you encounter issues, check the Troubleshooting guide for solutions to common problems.