Using the Semantic Model

Building the Semantic Model

Once you’ve defined your semantic model with views, entities, dimensions, and measures, you need to build it before use:

oxy build

This command validates and compiles your semantic model definitions, making them available to agents, workflows, and routing agents. Always run oxy build after creating or modifying semantic model files to ensure your changes are picked up.

In Agents

Add the semantic_query tool to your agent to enable it to query the semantic model directly. The agent can then answer business questions using your defined metrics and dimensions.

Basic Setup

agents/analytics.agent.yml

model: "openai-4o-mini"
description: "Data analyst agent that can answer business questions"

system_instructions: |
  You are a data analyst expert. Your task is to help users answer 
  questions based on data using the semantic model.

  Use the semantic_query tool to query data. The tool gives you access
  to pre-defined business metrics and dimensions.

tools:
  - name: semantic_query
    type: semantic_query
    topic: ecommerce_analytics # The topic to query

Tool Configuration

The semantic_query tool has the following properties:

Property	Type	Required	Description
`name`	string	Yes	Unique identifier for the tool
`type`	string	Yes	Must be `semantic_query`
`topic`	string	Yes	Name of the semantic topic to query

When querying a topic with default_filters, those filters are automatically applied to all queries. User-provided filters are combined with default filters using AND logic. For example, if a topic has a default filter for tenant_id = 'abc123', every query will be scoped to that tenant regardless of additional filters specified by the user.

Example Queries

Once configured, your agent can handle queries like:

“What’s the total revenue by customer segment?”
“Show me the top 5 products by sales this month”
“What’s the average order value for each acquisition channel?”

The agent will use the semantic model to understand available dimensions and measures, then construct appropriate queries.

Multiple Topics

You can add multiple semantic_query tools for different topics:

agents/multi_domain.agent.yml

model: "openai-4o-mini"
description: "Multi-domain analyst with access to various business areas"

tools:
  - name: sales_query
    type: semantic_query
    topic: sales

  - name: marketing_query
    type: semantic_query
    topic: marketing

  - name: finance_query
    type: semantic_query
    topic: finance

In Workflows

Use the semantic_query task type in workflows to execute structured queries against your semantic model. This is ideal for automated reporting, data pipelines, and scheduled analytics.

Basic Workflow Task

workflows/sales_report.workflow.yml

name: weekly_sales_report
description: Generate weekly sales performance report

tasks:
  - name: sales_metrics
    type: semantic_query
    topic: ecommerce_analytics
    dimensions:
      - orders.order_status
      - customers.acquisition_channel
    measures:
      - orders.total_revenue
      - orders.total_orders
      - orders.avg_order_value
    orders:
      - field: orders.total_revenue
        direction: desc
    limit: 10

  - name: create_report
    type: agent
    agent_ref: agents/report_generator.agent.yml
    prompt: |
      Create a weekly sales report based on this data:
      {{ sales_metrics }}

      Include insights on:
      - Top performing channels
      - Order status breakdown
      - Key trends

Semantic Query Task Properties

Property	Type	Required	Description
`type`	string	Yes	Must be `semantic_query`
`topic`	string	Yes	Name of the semantic topic to query
`dimensions`	array	No	List of dimensions to include (view.field format)
`measures`	array	No	List of measures to calculate (view.field format)
`filters`	array	No	Filters to apply to the query
`orders`	array	No	Sort order for results
`limit`	number	No	Maximum number of rows to return

Field Referencing

Reference dimensions and measures using the format view_name.field_name:

dimensions:
  - orders.order_date # From orders view
  - customers.customer_name # From customers view
  - products.product_category # From products view

measures:
  - orders.total_revenue # Sum measure from orders
  - orders.avg_order_value # Average measure from orders
  - customers.total_customers # Count measure from customers

Filtering Data

Apply filters to narrow down your results. These filters are combined with any default_filters defined in the topic using AND logic:

- name: high_value_orders
  type: semantic_query
  topic: ecommerce_analytics
  dimensions:
    - orders.order_id
    - customers.customer_name
  measures:
    - orders.total_revenue
  filters:
    - field: orders.total_amount
      operator: ">="
      value: 1000
    - field: orders.order_status
      operator: "="
      value: "delivered"
  orders:
    - field: orders.total_revenue
      direction: desc
  limit: 20

If the topic ecommerce_analytics has default filters (e.g., tenant_id = 'xyz'), they are automatically applied along with the filters specified above. All default filters and user filters must be satisfied.

Ordering Results

Control the sort order of your results:

orders:
  - field: orders.total_revenue
    direction: desc # Sort by revenue descending
  - field: customers.customer_name
    direction: asc # Then by customer name ascending

Advanced Example

workflows/customer_analysis.workflow.yml

name: customer_segmentation_analysis
description: Analyze customer segments and buying patterns

variables:
  min_orders:
    type: number
    description: Minimum number of orders for analysis
    default: 5

tasks:
  - name: customer_segments
    type: semantic_query
    topic: ecommerce_analytics
    dimensions:
      - customers.acquisition_channel
      - customers.customer_name
    measures:
      - orders.total_orders
      - orders.total_revenue
      - orders.avg_order_value
    filters:
      - field: orders.total_orders
        operator: ">="
        value: "{{ min_orders }}"
    orders:
      - field: orders.total_revenue
        direction: desc
    limit: 50

  - name: channel_performance
    type: semantic_query
    topic: ecommerce_analytics
    dimensions:
      - customers.acquisition_channel
      - orders.order_status
    measures:
      - orders.total_revenue
      - orders.total_orders
    orders:
      - field: customers.acquisition_channel
        direction: asc

  - name: generate_insights
    type: agent
    agent_ref: agents/analyst.agent.yml
    prompt: |
      Analyze this customer data and provide strategic insights:

      Customer Segments:
      {{ customer_segments }}

      Channel Performance:
      {{ channel_performance }}

      Focus on:
      1. Which channels drive the most value?
      2. Customer retention patterns
      3. Recommendations for optimization

In Routing Agents

Routing agents can include semantic topics as routes, enabling intelligent task routing based on semantic understanding.

Adding Topics to Routes

agents/_routing.agent.yml

model: "openai-4o-mini"
type: routing
description: "Main routing agent for data analysis"

routes:
  # Include specific topics
  - "semantics/topics/ecommerce_analytics.topic.yml"
  - "semantics/topics/sales.topic.yml"

  # Or use glob patterns to include all topics
  - "semantics/topics/*.topic.yml"

  # Mix with other route types
  - "agents/specialized_analyst.agent.yml"
  - "workflows/*.workflow.yml"

route_fallback: agents/default.agent.yml

Complete Routing Example

agents/_data_router.agent.yml

model: "openai-4o-mini"
type: routing
description: "Intelligent data analysis router"

system_instructions: |
  You are a routing agent for data analysis tasks.

  Route to semantic topics for:
  - Metrics and KPI queries
  - Standard business questions
  - Data exploration requests

  Route to specialized agents for:
  - Complex analysis requiring custom logic
  - Tasks needing multiple data sources

  Route to workflows for:
  - Automated reporting
  - Multi-step processes

routes:
  # Semantic model topics
  - "semantics/topics/sales.topic.yml"
  - "semantics/topics/marketing.topic.yml"
  - "semantics/topics/finance.topic.yml"
  - "semantics/topics/operations.topic.yml"

  # Specialized agents
  - "agents/data_scientist.agent.yml"
  - "agents/report_generator.agent.yml"

  # Automated workflows
  - "workflows/daily_reports.workflow.yml"
  - "workflows/data_quality.workflow.yml"

route_fallback: agents/general_assistant.agent.yml

reasoning:
  effort: low

Best Practices

Agent Usage

Provide clear system instructions on when to use semantic queries
Include multiple topics for agents that span business domains
Let the agent decide which dimensions and measures to use based on the question

Workflow Usage

Use semantic queries for repeatable analysis patterns
Leverage variables for dynamic filtering
Chain semantic queries with agent tasks for insights generation

Routing Agent Usage

Include semantic topics alongside specialized agents and workflows
Use glob patterns to automatically include all topics
Provide clear routing instructions in system_instructions
Configure appropriate fallback routes

Performance

Use limit to constrain result set size when appropriate
Be selective with dimensions—only include what you need
Consider adding indexes on frequently filtered columns
Use default_filters in topics for common business rules

Error Handling

Test your semantic queries before deploying to production
Handle cases where queries return no results
Provide meaningful error messages to users
Monitor query performance and optimize as needed

Topics

Organize views into topics

Agents

Learn more about agents

Workflows

Learn more about workflows

Overview

Back to semantic model overview

​Building the Semantic Model

​In Agents

​Basic Setup

​Tool Configuration

​Example Queries

​Multiple Topics

​In Workflows

​Basic Workflow Task

​Semantic Query Task Properties

​Field Referencing

​Filtering Data

​Ordering Results

​Advanced Example

​In Routing Agents

​Adding Topics to Routes

​Complete Routing Example

​Best Practices

​Agent Usage

​Workflow Usage

​Routing Agent Usage

​Performance

​Error Handling

​Related Documentation

Topics

Agents

Workflows

Overview

Building the Semantic Model

In Agents

Basic Setup

Tool Configuration

Example Queries

Multiple Topics

In Workflows

Basic Workflow Task

Semantic Query Task Properties

Field Referencing

Filtering Data

Ordering Results

Advanced Example

In Routing Agents

Adding Topics to Routes

Complete Routing Example

Best Practices

Agent Usage

Workflow Usage

Routing Agent Usage

Performance

Error Handling

Related Documentation