Skip to main content

​
Overview

The semantic layer in Oxy is a powerful abstraction that transforms raw database schemas into business-friendly concepts. It provides a declarative way to define business logic, metrics, and relationships that AI agents can understand and use to answer analytical questions accurately. Think of it as a translation layer between your technical data infrastructure and business questions. Instead of requiring users or AI agents to understand complex database schemas and SQL, they can work with intuitive business concepts like “total revenue,” “customer segments,” or “monthly active users.”
Oxy also supports a simpler semantic model format (.schema.yml) for straightforward use cases. See Semantic Model for a lighter-weight alternative.

​
Key Benefits

  • AI-Optimized: Provides rich context for AI agents to understand your data and generate accurate queries
  • Declarative: Define business logic once in YAML, use it everywhere
  • Consistent: Ensures everyone in your organization uses the same metric definitions
  • Governed: Centralize data access, security, and quality rules
  • Portable: Works across different BI tools and query engines

​
Core Concepts

The semantic layer consists of four main building blocks:

​
Views

Views represent logical data models that define how to access and interpret data. They encapsulate the business logic needed to transform raw tables into meaningful business concepts. A view defines:
  • How to access data (table or custom SQL)
  • What entities exist in the data
  • Available dimensions (attributes)
  • Available measures (metrics and aggregations)
Learn more about Views →

​
Entities

Entities represent distinct objects or concepts in your data model (like customers, orders, or products). They enable automatic relationship discovery and intelligent joins between views. Learn more about Entities →

​
Dimensions

Dimensions are attributes that describe your entities. They’re used for grouping, filtering, and segmenting data (like order status, customer name, or product category). Learn more about Dimensions →

​
Measures

Measures are quantitative calculations and aggregations that provide business insights (like total revenue, average order value, or customer count). Learn more about Measures →

​
Topics

Topics are collections of related views organized by business domain. They help users discover and explore related data concepts together. Learn more about Topics →

​
Project Structure

Organize your semantic layer files in a clear directory structure: 
your-project/
├── config.yml
├── semantics/
│   ├── topics/
│   │   ├── sales.topic.yml
│   │   ├── marketing.topic.yml
│   │   └── finance.topic.yml
│   └── views/
│       ├── orders.view.yml
│       ├── customers.view.yml
│       ├── products.view.yml
│       └── campaigns.view.yml

​
Quick Start

Here’s a simple example to get you started:
semantics/views/orders.view.yml
name: orders
description: "Order transactions and related data"
datasource: "local"
table: "orders.csv"

entities:
  - name: order
    type: primary
    key: order_id

dimensions:
  - name: order_date
    type: date
    expr: order_date
  
  - name: order_status
    type: string
    expr: status
    samples: ["pending", "shipped", "delivered"]

measures:
  - name: total_orders
    type: count
    
  - name: total_revenue
    type: sum
    expr: total_amount
Build your semantic layer: 
oxy build
Then use it in an agent:
agents/analyst.agent.yml
model: "openai-4o-mini"
tools:
  - name: semantic_query
    type: semantic_query
    topic: sales

​
Detailed Guides

Explore each component of the semantic layer in detail:

Views

Create and manage views that represent your data models

Entities

Define entities and relationships for automatic joins

Dimensions

Add dimensions for filtering and grouping

Measures

Define measures and metrics for analysis

Topics

Organize views into business domain topics

Usage

Use the semantic layer in agents, workflows, and routing

​
Examples

​
Performance

  • Use table references when possible instead of complex SQL
  • Pre-aggregate data in SQL-based views when appropriate
  • Index the key columns referenced in entity definitions

​
Next Steps

Now that you understand the semantic layer, dive deeper into specific components:
1

Create Views

Start by creating views that represent your data models. Learn about Views →
2

Define Entities

Add entities to enable automatic joins between views. Learn about Entities →
3

Add Dimensions & Measures

Define the dimensions and measures that users will query. Dimensions → | Measures →
4

Organize with Topics

Group related views into business domain topics. Learn about Topics →
5

Use in Agents & Workflows

Put your semantic layer to work in agents and workflows. Learn about Usage →

Quick Reference

Semantic layer syntax reference

Semantic Model

Simpler semantic model format

Context

Providing context to agents

Data Sources

Configure data sources

Quick Reference

Semantic layer syntax reference

Semantic Model

Simpler semantic model format

Agents

Learn how agents use the semantic layer

Context

Providing context to agents

Data Sources

Configure data sources

Testing

Test your semantic layer definitions