> ## Documentation Index
> Fetch the complete documentation index at: https://oxy.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the Semantic Model

> How to use your semantic model in agents, workflows, and routing agents

<RewriteBanner />

## Building the Semantic Model

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

```bash theme={null}
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

```yaml agents/analytics.agent.yml theme={null}
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 |

<Note>
  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.
</Note>

### 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:

```yaml agents/multi_domain.agent.yml theme={null}
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

```yaml workflows/sales_report.workflow.yml theme={null}
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`:

```yaml theme={null}
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:

```yaml theme={null}
- 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
```

<Info>
  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.
</Info>

### Ordering Results

Control the sort order of your results:

```yaml theme={null}
orders:
  - field: orders.total_revenue
    direction: desc # Sort by revenue descending
  - field: customers.customer_name
    direction: asc # Then by customer name ascending
```

### Advanced Example

```yaml workflows/customer_analysis.workflow.yml theme={null}
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

```yaml agents/_routing.agent.yml theme={null}
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

```yaml agents/_data_router.agent.yml theme={null}
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

## Related Documentation

<CardGroup cols={2}>
  <Card title="Topics" icon="folder" href="/docs/guide/build/semantic-model/topics">
    Organize views into topics
  </Card>

  <Card title="Agents" icon="robot" href="/docs/guide/build/agents">
    Learn more about agents
  </Card>

  <Card title="Workflows" icon="sitemap" href="/docs/guide/build/automations">
    Learn more about workflows
  </Card>

  <Card title="Overview" icon="book" href="/docs/guide/build/semantic-model/simple-model">
    Back to semantic model overview
  </Card>
</CardGroup>