Entities

Overview

Entities represent distinct objects or concepts in your data model (like customers, orders, or products). They enable automatic relationship discovery and intelligent joins between views. When you define entities consistently across views, the semantic model automatically understands relationships and can join data seamlessly.

Entity Types

Primary Entity

Each view should have exactly one primary entity representing the main subject:

entities:
  - name: order
    type: primary
    description: "Individual order transaction"
    key: order_id

Foreign Entity

Foreign entities reference objects primarily defined in other views:

entities:
  - name: customer
    type: foreign
    description: "Customer who placed the order"
    key: customer_id

  - name: product
    type: foreign
    description: "Product in the order"
    key: product_id

Entity Properties

Property	Type	Required	Description
`name`	string	Yes	Unique identifier for the entity
`type`	string	Yes	Entity type: `primary` or `foreign`
`description`	string	Yes	Human-readable description
`key`	string	No*	The dimension that serves as the entity key (single key)
`keys`	array[string]	No*	The dimensions that serve as the entity keys (composite keys)

*Note: Either key or keys must be provided, but not both.

Important: Entity Keys Reference Dimension NamesThe key and keys fields must reference dimension names, not database column names.For example, if your dimension is defined as:

dimensions:
  - name: customer_id # lowercase with underscores
    expr: CUSTOMER_ID # database column (uppercase)
    type: string

Your entity key should reference the dimension name:

entities:
  - name: customer
    type: primary
    key: customer_id # ✅ Matches dimension name
    # key: CUSTOMER_ID        # ❌ Wrong - this is the column name

This naming convention is critical because Oxygen uses entity keys to:

Mark dimensions as primary keys in the semantic schema
Automatically generate join relationships between views

Simple Entity Keys

Use the key property for entities with a single identifier:

# views/orders.view.yml
entities:
  - name: order
    type: primary
    key: order_id

  - name: customer
    type: foreign
    key: customer_id

# views/customers.view.yml
entities:
  - name: customer
    type: primary
    key: customer_id

Now queries can seamlessly join these views:

“Show total revenue by customer acquisition channel”
“What’s the average order value for customers from email campaigns?”

Composite Keys

For entities with composite keys, use the keys field:

# views/order_items.view.yml
entities:
  - name: order_item
    type: primary
    description: "Individual line item within an order"
    keys:
      - order_id
      - line_item_id

# views/order_shipments.view.yml
entities:
  - name: order_item
    type: foreign
    description: "Line item being shipped"
    keys:
      - order_id
      - line_item_id

The semantic model will automatically join these views on both order_id and line_item_id.

How Entities Enable Joins

When you define entities consistently across views, Oxygen automatically:

Identifies relationships between views based on matching entity names
Generates JOIN clauses using the entity keys
Enables cross-view queries without manual join logic

Example: Multi-View Query

Given these view definitions:

# views/orders.view.yml
entities:
  - name: order
    type: primary
    key: order_id
  - name: customer
    type: foreign
    key: customer_id

# views/customers.view.yml
entities:
  - name: customer
    type: primary
    key: customer_id

# views/order_items.view.yml
entities:
  - name: order_item
    type: primary
    key: item_id
  - name: order
    type: foreign
    key: order_id
  - name: product
    type: foreign
    key: product_id

# views/products.view.yml
entities:
  - name: product
    type: primary
    key: product_id

Users can ask questions that span all these views:

“What’s the total revenue by product category?” (joins orders, order_items, products)
“Show me customer lifetime value by acquisition channel” (joins customers, orders)
“Which products have the highest return rates?” (joins products, order_items, orders)

Best Practices

Naming

Use singular nouns (e.g., customer, order, product)
Use consistent names across all views
Match the business terminology your organization uses

Design

Each view should have exactly one primary entity
Add foreign entities for all relationships to other views
Ensure entity keys reference valid dimensions in the view

Performance

Index the columns used as entity keys in your database
For composite keys, create composite indexes on those columns
Consider the cardinality of joins when designing entities

Common Patterns

One-to-Many Relationships

# Customer (one) to Orders (many)
# views/customers.view.yml
entities:
  - name: customer
    type: primary
    key: customer_id

# views/orders.view.yml
entities:
  - name: order
    type: primary
    key: order_id
  - name: customer
    type: foreign
    key: customer_id

Many-to-Many Relationships

# Products (many) to Orders (many) through OrderItems
# views/products.view.yml
entities:
  - name: product
    type: primary
    key: product_id

# views/order_items.view.yml (junction table)
entities:
  - name: order_item
    type: primary
    key: item_id
  - name: product
    type: foreign
    key: product_id
  - name: order
    type: foreign
    key: order_id

# views/orders.view.yml
entities:
  - name: order
    type: primary
    key: order_id

Hierarchical Relationships

# Employee hierarchy (self-referential)
# views/employees.view.yml
entities:
  - name: employee
    type: primary
    key: employee_id
  - name: manager
    type: foreign
    key: manager_id

Views

Learn about creating views

Dimensions

Define dimensions for your entities

Overview

Back to semantic model overview

Get started

Data Infrastructure

World Model

Agentic Intelligence

SDK

Automations

Data Apps

Integrations

Edge fleet

Manage

Workspaces

Authentication

Observability

Enterprise

Reference

REST API

Resources

Troubleshooting

Overview

Entity Types

Primary Entity

Foreign Entity

Entity Properties

Simple Entity Keys

Composite Keys

How Entities Enable Joins

Example: Multi-View Query

Best Practices

Naming

Design

Performance

Common Patterns

One-to-Many Relationships

Many-to-Many Relationships

Hierarchical Relationships

Views

Dimensions

Overview

​Overview

​Entity Types

​Primary Entity

​Foreign Entity

​Entity Properties

​Simple Entity Keys

​Composite Keys

​How Entities Enable Joins

​Example: Multi-View Query

​Best Practices

​Naming

​Design

​Performance

​Common Patterns

​One-to-Many Relationships

​Many-to-Many Relationships

​Hierarchical Relationships

​Related Documentation

Views

Dimensions

Overview

Overview

Entity Types

Primary Entity

Foreign Entity

Entity Properties

Simple Entity Keys

Composite Keys

How Entities Enable Joins

Example: Multi-View Query

Best Practices

Naming

Design

Performance

Common Patterns

One-to-Many Relationships

Many-to-Many Relationships

Hierarchical Relationships

Related Documentation