Skip to main content
The semantic model is where you define your business’s metrics once, in version-controlled YAML, and let Oxygen compile them into correct SQL on demand. It is the vocabulary layer of the World Model: the place net_sales, labor_cost_pct, and active_customers are given a single, authoritative definition that agents, apps, and automations all share. Under the hood the semantic model is powered by airlayer, Oxygen’s open-source semantic engine. airlayer reads your definitions and compiles them into deterministic, dialect-specific SQL — resolving joins automatically from your entity graph and neutralizing fan-out — so a measure means the same thing everywhere and no agent has to hand-write (or hallucinate) the query behind it.

​
Why a semantic model

Ask two people to compute “revenue” straight from the warehouse and you’ll often get two different queries — different joins, different filters, different grain. The semantic model removes that ambiguity:
  • Define once, reuse everywhere. A measure is written a single time and referenced by name from agents, data apps, automations, and the metric tree.
  • Deterministic SQL. Given the same request, airlayer always emits the same SQL. There’s no LLM in the compilation path, so results are reproducible.
  • Automatic joins. Entity declarations tell airlayer how views relate, so it builds the join path for you — and protects against fan-out double-counting.
  • Dialect-aware. The same definitions compile to BigQuery, Snowflake, Postgres, DuckDB, and more, so business logic isn’t pinned to one warehouse.

​
Views (.view.yml)

A view is the core building block. Each .view.yml file maps one table (or SQL query) into business concepts — entities, dimensions, and measures:
orders.view.yml
Query it and airlayer compiles deterministic SQL for your dialect — resolving the aggregation, applying filters, and joining any related views automatically. The three building blocks each have their own page:

Entities

Keys and relationships that drive automatic joins

Dimensions

Attributes to slice and filter by

Measures

Business metrics with aggregation rules

​
Measures reference measures

Measures can be defined in terms of other measures with the {{view.measure}} syntax. airlayer resolves the reference to the underlying aggregate at compile time, and the reference becomes an edge in the metric tree:

​
Topics (.topic.yml)

A topic groups related views and curates the measures and dimensions an agent should reach for when answering a class of questions. Topics are how you point an agent at a slice of the semantic model without exposing every view at once. See Topics.

​
How it fits together

1

Define views

Model each table as a .view.yml with entities, dimensions, and measures.
2

Relate them with entities

Declare primary/foreign keys so airlayer can resolve joins across views.
3

Group with topics

Bundle views into .topic.yml files that scope what an agent can query.
4

Compose the World Model

Reference measures from measures to build the metric tree, then put the model to work in agents.

​
Next steps

Build a view

The full .view.yml reference

Use in agents

Ground an agent in the semantic model

The Metric Tree

Compose measures into a driver graph

The World Model

Where the semantic model fits in the bigger picture