Skip to main content

​
Overview

A semantic model is a conceptual representation of data that defines business terms, metrics, relationships, and rules in a way that makes sense to business users. It’s essentially a blueprint that maps raw data into business-friendly concepts. Think of it like translating technical database schemas into business terminology.
Oxy also supports a more structured semantic layer approach using views and topics. See the Semantic Layer documentation for an alternative way to organize your semantic definitions.

​
Organization and Formatting Rules

  • A semantic model should be organized under the data folder.
  • Use the .sem.yml extension to distinguish it from other files in the data folder. e.g. finance.sem.yml

​
Core Components

Let’s take a look at Semantic model components:
ComponentDescriptionRequired
tableSpecifies the source tableRequired
databaseThe database that the table is used withinRequired
descriptionA description of the tableRequired
entitiesRepresents unique identifiers that define the grain of analysisRequired
dimensionsDefines attributes used to slice and filter dataRequired
measuresDefines business metrics with specific aggregation rulesRequired
Within the entities, dimensions, and measures keys, the following fields are allowed:
ComponentDescriptionRequired
nameColumn nameRequired
descriptionDescription of the columnOptional
synonymsSynonyms for this columnOptional
sampleA sample of values for this columnOptional
Moreover, for the measures key, the following fields attributes are available:
ComponentDescriptionRequired
sqlSnippet of SQL that defines the calculation. For pre-aggregated data, this can just be a column name.Required

​
Sample semantic model config

The following example displays a complete configuration:
data/anon_youtube.sem.yml
table: content_level_monthly_stats_fruits_veggies.csv
database: local
description: Lorem ipsum

entities:
  - name: content_id
    description: content_id
    sample: [1, 2, 3, 4]

dimensions:
  - name: month
    sample:
      - "2024-08"
  - name: property_grouping
    synonyms:
      - "property_grouping"
    sample:
      - "Fruit"
      - "Vegetable"

measures:
  - name: count_content_id
    sql: sum(distinct content_id)

​
How to enable use of semantic model in agents

For agents to utilize the semantic model, you need to include the semantic model in the context section of your agent config. 
context:
  - name: anon_youtube_model
    type: semantic_model
    src: data/anon_youtube.sem.yml
For more information, refer to context objects in the Agents documentation.

Semantic Layer

Alternative semantic layer with views and topics

Agents

Using semantic models with agents

Context

Providing context to agents