oxy-semantic-modeling

Oxy semantic modeling

The reference is upstream and maintained — read it rather than guessing: https://www.oxygen-hq.com/docs/guide/build/semantic-model/simple-model (the section entry point; views, entities, dimensions, measures, topics, modeling, and use-in-agents sit beside it).

That page owns the field lists. This skill deliberately does not restate them — a copied schema stays confidently wrong long after the real one moves. What follows is the craft and the traps it does not carry, with examples taken from one production workspace's 39 views and 23 topics.

Read next:

• templates/view-template.yml and templates/topic-template.yml — annotated starting points for a new view or topic.
• references/warehouse-casts.md — the per-warehouse cast for a date column that is not stored as a date.

View anatomy

A view is one physical table plus the vocabulary an agent is allowed to use against it.

name: sales_daily
datasource: "clickhouse"
table: "restaurant_analytics.sales_daily_metrics"

entities are the join graph, not decoration. The primary entity names the grain of the row; foreign entities are the edges to other views; parent: states hierarchy (a sales day belongs to a restaurant).

entities:
  - name: sales_day
    type: primary
    key: sales_day_key
    parent: restaurant
  - name: restaurant
    type: foreign
    key: restaurant_id

key names a dimension, not a column. In a restaurants view the entity restaurant has key: restaurant_id, and the restaurant_id dimension is expr: guid — the physical column is guid. So resolve a key against the view's dimensions: list, never against the table's columns; the reference's entities page carries the same warning.

Declare a foreign entity for every foreign-key column. When a fact view holds an ID pointing at another view's primary key (orders.restaurant_id → restaurants.guid), give the fact view a type: foreign entity with the same name: as the lookup view's primary entity and key: set to the FK dimension. That edge is what lets a query group orders by restaurants.location_name instead of by the raw ID; without it, every chart and table built on the view renders opaque UUIDs. A foreign entity with no matching primary anywhere is only a warning — the join silently does not exist.