User Guide

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

Using semantic domains is simple:

1. Create a card → Select "Semantic Domain" as data source
2. Drag fields → Select fields from any dataset (green = can join, gray = can't join)
3. Query runs automatically → Semaphor joins datasets and displays results
4. Review joins → Check Auto-Resolved Joins panel to see how data was joined

Key benefit: No manual join configuration required!

---

Now let's walk through each step in detail.

Step 1: Create a Card with Semantic Domain

1. Open a dashboard or create a new one
2. Click "Add Card" to create a new visualization
3. In the Data Source dropdown, select "Semantic Domain"
4. Choose your domain from the list of available domains
5. Click "Continue" or "Next"

Step 2: Understanding the Field Explorer

After selecting a semantic domain, you'll see the Fields List on the left side of the Visual tab. This shows all available fields organized by dataset.

Field Explorer Features:

• Search bar: Filter fields by name, dataset, or data type
• Category tabs: View all fields, dimensions only, or metrics only
• Dataset grouping: Fields are grouped by their source dataset
• Visual indicators: Color-coded badges show field draggability

Step 3: Understanding Field States

Fields show visual indicators based on whether they can be joined to your current selection:

Hover over any field to see its description, data type, and join path (if applicable).

Step 4: Selecting Fields Across Datasets

You can drag and drop fields from multiple related datasets into your chart. Semaphor automatically resolves the necessary joins.

Example Workflow: Sales by Customer Segment

1. Start with your fact table: Drag revenue from the orders dataset to Metrics
2. Add a dimension: Drag customer_segment from the customers dataset to Dimensions
3. Result: Semaphor automatically joins orders to customers using the relationship defined by your admin

What Happens Behind the Scenes:

• Semaphor detects you're using fields from orders and customers
• It finds the relationship between these datasets (e.g., orders.customer_id = customers.id)
• It automatically creates a LEFT JOIN
• The query executes with the join applied

No manual join configuration required!

Step 5: Viewing Auto-Resolved Joins

After running a query with auto-joined datasets, you'll see the Auto-Resolved Joins panel in the Visual tab.

This collapsible panel 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:

When to review auto-joins:

• You want to understand why certain data is included/excluded
• Query results seem unexpected (check join types)
• You're learning how datasets relate to each other
• You need to verify the join logic for documentation

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:

• Yellow indicator on field badges
• Join path shown in hover tooltip
• Multiple joins listed in Auto-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. Select semantic domain: Sales Analytics
2. Drag revenue from orders → Metrics (establishes base dataset)
3. Drag customer_segment from customers → Dimensions (shows green - can join)
4. Click "Run Query"

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. Select semantic domain: Sales Analytics
2. Drag revenue from orders → Metrics
3. Drag country_name from countries → Dimensions (shows yellow - indirect join)
4. Hover to see join path: orders → stores → countries
5. Click "Run Query"

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

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 auto-joins: Check the Auto-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.