Semaphor
Semantic Domains

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

  1. 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.
  2. 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 ID was.
  3. 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

  1. Start from orders: pick it in the dataset dropdown and drag revenue to Metrics
  2. Open the Customer folder and drag segment to Rows
  3. Result: the query joins orders to customers through the relationship your administrator defined

What happens behind the scenes:

  • The card reads fields from orders and customers
  • 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)

Example:

Auto-Resolved Joins

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:

  1. Pick orders from Sales Analytics in the dataset dropdown
  2. Drag revenue → Metrics
  3. Open the Customer folder and drag customer_segment → Rows

Result:

  • Semaphor auto-joins orders to customers
  • 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:

  1. Pick orders from Sales Analytics in the dataset dropdown
  2. Drag revenue → Metrics
  3. 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]
  • 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:

  1. Explore your data: Start building dashboards with auto-join enabled
  2. Leverage relationships: Use multi-hop joins to answer complex questions
  3. Review joins: Check the Resolved joins panel to understand join logic
  4. Ask for help: Request new relationships from your admin when needed
  5. Share insights: Document your analyses and share with your team

If you encounter issues, check the Troubleshooting guide for solutions to common problems.

On this page