Admin Setup Guide

Navigating to Domains

1. Log in to Semaphor
2. Select your project from the project list
3. Click on "Domains" tab in the top navigation

Creating a Domain

Step 1: Create a New Domain

1. On the Domains page, click the "Create Domain" button
2. Fill in the domain details:
   • Name: A unique identifier (e.g., sales_analytics)
   • Label: User-friendly display name (e.g., Sales Analytics)
   • Description: Brief explanation of what this domain covers
   • Connection: Select the data connection this domain uses
3. Click "Create" to save your domain

Quick Setup Summary

Before diving into the details, here's the complete workflow at a glance:

1. Create Domain → Name it and select a connection
2. Add Datasets → Select tables, let AI generate labels (30-60s per dataset)
3. Discover Relationships → Run AI discovery, accept suggestions (1-2 minutes)
4. Save & Test → Save domain, test in a dashboard card

Total time: 5-10 minutes for a typical domain with 4-5 datasets

Now let's walk through each step in detail.

Step 2: Open the Domain Editor

After creating your domain, you'll be taken to the Domain Editor, which has four tabs:

• Datasets: Add and configure your data sources
• Relationships: Define how datasets connect
• Code Editor: View and edit the domain as YAML/JSON
• Preview: Test your domain configuration

Adding Datasets

After creating your domain, you'll add the datasets (tables) you want users to explore.

Step 1: Select Your Datasets

1. In the Domain Editor, ensure you're on the Datasets tab
2. Click the "Add Dataset" button
3. Select the tables or views you want to include from your database
4. Click "Add" to add each dataset

Step 2: Wait for AI Processing

After you add datasets and click Save, Semaphor's AI automatically:

• Generates customer-facing labels for table names (e.g., orders_tbl → "Orders")
• Creates readable field names (e.g., cust_id → "Customer ID")
• Adds helpful descriptions for fields
• Classifies fields as dimensions (groupable) or measures (aggregatable)
• Suggests appropriate aggregation functions (SUM, COUNT, AVG)

Step 3: Review AI-Generated Fields (Optional)

After AI processing completes, you can review and adjust the generated labels:

1. Click the "Edit" button (pencil icon) next to a dataset
2. Review the AI-generated field labels and descriptions
3. Make adjustments if needed (most users find the AI labels work well as-is)
4. Hide any fields that shouldn't be visible to end users

That's all you need to get your datasets ready! The AI handles the labeling and classification automatically. Next, you'll define how these datasets relate to each other.

Creating Relationships

Relationships define how datasets connect to each other, enabling automatic joins when users explore data across multiple datasets.

Using AI-Powered Relationship Discovery

Semaphor can automatically discover potential relationships between your datasets using AI analysis of field names, data types, and semantic patterns. This is the fastest way to set up your domain.

The entire process takes just a few steps:

1. Click "Discover Relationships" in the Relationships tab
2. Click "Run Discovery" and wait 1-2 minutes while AI analyzes your datasets
3. Review the suggestions - each shows confidence (High/Medium/Low) and rationale
4. Select relationships to add - use "Select High Confidence Only" or review each one
5. Click "Accept Selected" - done!

What the AI analyzes:

• Field names (e.g., customer_id likely joins to customers.id)
• Data types (matching types for join keys)
• Semantic patterns (fact tables to dimension tables)
• Table structures (primary/foreign key patterns)

What you'll see in suggestions:

• Source → Target: Which datasets connect (e.g., orders → customers)
• Join Fields: Which fields match (e.g., orders.customer_id = customers.id)
• Confidence: High, Medium, or Low
• Rationale: Why the AI thinks this relationship exists
• Cardinality: One-to-one, one-to-many, etc.

That's it! After accepting relationships, your domain is ready for users to query. The relationships enable automatic joins when users select fields from multiple datasets.

Advanced: Manual Relationship Management

If you need to manually add or edit a relationship:

1. In the Relationships tab, click "Add Relationship"
2. Fill in the relationship details:
   • Name: Identifier (e.g., orders_to_customers)
   • Source/Target Datasets: Which datasets to connect
   • Join Fields: Which fields to match
   • Cardinality: One-to-one, one-to-many, etc.
   • Join Type: INNER, LEFT, RIGHT, or FULL
3. Enable Auto-Join to allow automatic join resolution
4. Click "Save"

When to manually add relationships:

• AI didn't detect a relationship you know exists
• You need to specify a specific join type (e.g., INNER vs LEFT)
• You're working with non-standard naming conventions
• You need composite key relationships (multiple join fields)

Testing Your Domain

Step 1: Save Your Changes

After configuring datasets and relationships:

1. Click the "Save" button in the top-right corner
2. Wait for the confirmation message
3. Your changes are now persisted

Step 2: Preview the Domain

1. Click the "Preview" tab in the Domain Editor
2. You'll see a summary of your domain:
   • All datasets with their field counts
   • All relationships with source/target info
   • Validation warnings (if any)

Step 3: Test in a Dashboard

1. Create a new dashboard or open an existing one
2. Add a new card
3. Select "Semantic Domain" as the data source
4. Choose your domain from the dropdown
5. Try selecting fields from different datasets
   • If relationships are configured correctly, joins happen automatically
   • If fields from unrelated datasets are selected, you'll see an error

Advanced Configuration

Advanced Dataset Configuration

Creating Virtual Datasets

Virtual datasets allow you to define custom SQL queries as reusable datasets. This is useful for:

• Pre-aggregated data (e.g., monthly revenue summaries)
• Complex transformations
• Combining multiple tables with custom logic

To create a virtual dataset:

1. Click "Add Dataset" and select "Virtual Dataset"
2. Enter a dataset name (e.g., monthly_revenue)
3. Write your SQL query:

SELECT
  DATE_TRUNC('month', order_date) as month,
  SUM(total_amount) as revenue,
  COUNT(*) as order_count
FROM orders
GROUP BY DATE_TRUNC('month', order_date)

4. AI will generate field labels for your query results
5. Click "Add Dataset"

Manual Field Configuration

If you need to manually adjust field properties beyond what AI generates:

1. Click "Edit" on a dataset
2. For each field, you can modify:
   • Label: User-friendly display name
   • Description: Help text explaining the field
   • Data Type: String, Number, Date, DateTime, Boolean
   • Field Type: Dimension (groupable) or Measure (aggregatable)
   • Aggregate Function: SUM, AVG, COUNT, MIN, MAX for measures
   • Visibility: Show/hide from users (eye icon)

Best practices:

• Use clear labels: "Order Date" instead of "ord_dt"
• Add descriptions to help users understand fields
• Mark dimensions correctly for proper grouping
• Set default aggregations for measures

Next Steps

Once your semantic domain is configured:

1. Train your users: Share the User Guide with end users
2. Monitor usage: Track which relationships are used most frequently
3. Gather feedback: Ask users which fields or relationships they need
4. Optimize performance: Review query logs for slow multi-hop joins
5. Expand gradually: Add new datasets and relationships based on user needs