Semantics Layer

The Semantics is where you define the business meaning of your data.
Rather than just knowing that a column called amt exists in a table called txn, your Agent learns that it represents "Total Transaction Amount" and how to aggregate it correctly.

Semantic objects are the building blocks of this understanding. Each object maps a business concept to a specific piece of SQL logic.

Structure: Subject Areas and Objects

Semantic objects are organised into Subject Areas (folders).
A subject area groups related concepts together.

Example:
A "Revenue" subject area might contain:

• Total Revenue
• Average Order Value
• Revenue by Region

You must create at least one subject area before adding objects.

Subject Areas

Create a Subject Area

1. Click the folder icon in the left panel header
2. Type a name and press Enter

Rename a Subject Area

• Hover over the folder → click the three dots (⋯) → select Rename → enter the new folder name → press Enter

Delete a Subject Area

• Hover over the folder → click the three dots (⋯) → select Delete
• This permanently deletes the folder and all objects inside it

Semantic Objects

There are two types of semantic objects:

1. Attribute

An Attribute represents a dimension or descriptive field — something you:

• Group by
• Filter on
• Display as a label

Examples:

• Customer Name
• Product Category
• Region
• Order Status

Fields

Field	Required	Description
Name	Yes	Business name (e.g. "Customer Region")
Description	No	Plain-English explanation
Object Type	Yes	Select Attribute
Table	Yes	Source database table
Column	Yes	Specific column
Synonyms	No	Alternative names (e.g. "area", "territory")
Metadata	No	Custom key-value pairs

2. Metric

A Metric represents a calculated or aggregated value — something you measure.

Examples:

• Total Revenue
• Average Order Size
• Number of Active Users

Metrics have two subtypes:

2.1 Simple Metric

Aggregates a single column.

Field	Required	Description
Name	Yes	Business name (e.g. "Total Revenue")
Description	No	What this metric measures
Object Type	Yes	Select Metric
Metric Type	Yes	Select Simple
Table	Yes	Source table
Column	Yes	Column to aggregate
Aggregation	Yes	SUM, AVG, COUNT, MIN, MAX, ROUND, etc.
Synonyms	No	Alternative names
Metadata	No	Custom key-value pairs

2.2 Derived Metric

Uses a custom SQL formula, often combining multiple columns or tables.

Field	Required	Description
Name	Yes	Business name (e.g. "Gross Margin %")
Description	No	What this metric measures
Object Type	Yes	Select Metric
Metric Type	Yes	Select Derived
Formula	Yes	SQL expression (e.g. SUM(revenue.amount) / COUNT(orders.id))
Synonyms	No	Alternative names
Metadata	No	Custom key-value pairs

Formula Rules

• Must be a read-only SQL expression
• The following are blocked:
  • DROP, DELETE, INSERT, UPDATE, ALTER, TRUNCATE
  • UNION statements
  • SQL comments

Creating a Semantic Object

1. In the left panel:
   • Right-click a subject area → select Create,
     OR
   • Select a subject area → click Create Object in the right panel
2. Fill in the fields in the form
3. Click Save

Editing a Semantic Object

1. Click the object name in the left panel
2. Its details will load in the right panel