Domains Overview

What Are Semantic Domains?

Semantic Domains provide a powerful way to model your data in Semaphor, making it easier for users to explore and analyze information without writing SQL. A semantic domain defines:

• Datasets: Your data sources (tables, views, or custom queries)
• Fields: Identifiers, facts, and dimensions, with user-friendly names, descriptions, and data types
• Relationships: How datasets connect to each other
• Metrics: Governed aggregates such as revenue or profit margin
• Context: Instructions, other names, and example questions that help agents answer natural-language questions

Key Benefits

By setting up a semantic domain, you enable:

• Auto-join resolution: Automatically join datasets based on defined relationships
• Self-service analytics: Users can explore data without knowing SQL
• Consistent naming: Standardized field names across your organization
• Governed data access: Control which datasets and fields users can access

Core Components

Datasets

Datasets represent your data sources. Each one reads its rows from a database table or view, or from SQL stored directly in the domain template (a SQL dataset, also called a virtual dataset). Both are first-class: end users query them the same way. Each dataset contains:

• Name: A unique identifier used in relationships
• Label: User-friendly display name
• Source: The table or SQL query its rows come from
• Keys: The fields that identify one row, used to plan safe joins
• Fields: Columns and row-level expressions from the table or query

See Virtual Datasets for how to author SQL-backed datasets from the domain UI.

Fields

Fields are the individual columns (or row-level expressions) within datasets. Each one is an identifier (a key used for joins), a fact (a quantity you aggregate, like amount), or a dimension (an attribute you group and filter by, like region). Fields are configured with:

• Labels: Clear, user-friendly names
• Descriptions: Help text for users
• Data Types: A logical type (string, number, date, datetime, boolean, and more), plus the database's exact type when known
• Default Aggregates: SUM, AVG, COUNT, MIN, MAX, and more, for facts

Relationships

Relationships define how datasets connect, enabling automatic joins when users select fields from multiple datasets. Each relationship includes:

• From and To: The many side (from) and the side whose fields identify one row (to)
• Join Keys: Fields used to match records
• Cardinality: Many-to-one, one-to-one, or many-to-many
• Join Type: INNER, LEFT, RIGHT, FULL
• Auto-join: Whether to automatically resolve joins

Metrics and Calculated Fields

Domains can include reusable metrics and calculated fields that are available across all dashboards using that domain.

• Metrics: Aggregates such as profit margin or average order value. A metric aggregates one dataset, or combines inputs from several (e.g., net revenue from orders and returns)
• Fact and dimension expressions: Row-level calculations on a dataset (e.g., amount in dollars, fiscal quarter)

Domain-level calculations provide consistent business logic organization-wide. Users can reference these fields just like regular columns, but the calculations are centrally managed by administrators.

Context

Every domain object can carry context: instructions, other names people use, and example questions. Agents and natural-language questions read it to pick the right dataset, field, or metric.

How It Works

For Administrators

1. Create a Domain: Define your semantic layer with a name and connection
2. Add Datasets: Include tables, views, or custom SQL queries
3. Configure Fields: Set user-friendly names and types
4. Define Relationships: Specify how datasets connect
5. Test and Publish: Validate your domain configuration

For End Users

1. Select a Domain: Choose a semantic domain when creating a dashboard card
2. Drag and Drop Fields: Select fields from any dataset
3. Auto-join Resolution: Semaphor automatically joins datasets based on relationships
4. Analyze Data: Create visualizations without writing SQL

Use Cases

Star Schema Analytics

Model fact tables (orders, sales) with dimension tables (customers, products, stores) for easy business intelligence queries.

Snowflake Schema

Support multi-hop joins through intermediate dimensions (orders → stores → countries) for hierarchical analysis.

Self-Service Reporting

Enable business users to explore data across multiple datasets without technical expertise.

Governed Data Access

Centralize data modeling and ensure consistent join logic across all users and dashboards.

Getting Started

Prerequisites

Before creating a semantic domain, you need:

• A Semaphor project with at least one data connection configured
• Access to the project (Author or Admin role)
• Knowledge of your data model and how tables/datasets relate to each other

Next Steps

Ready to get started? Head over to the Admin Setup Guide to learn how to create your first semantic domain.