Key Concepts

For Everyone

Understanding Olytix Core's core concepts will help you navigate the documentation and build effective analytics solutions. This page introduces the key terminology used throughout the platform.

The Olytix Core Hierarchy

Olytix Core organizes data into a clear hierarchy. Explore the interactive diagram below to understand how data flows through the platform:

Olytix Core Data Hierarchy

Interactive diagram showing how data flows through Olytix Core

Legend

Data Source

Transformation

Semantic Layer

Business Metrics

Sources

Sources represent raw data tables from your data warehouse or database.

# sources/raw.yml
sources:
  - name: raw
    database: analytics
    schema: raw_data
    tables:
      - name: orders
        description: Raw orders from the e-commerce system
        columns:
          - name: order_id
            description: Unique order identifier
          - name: customer_id
            description: Reference to the customer
          - name: total_amount
            description: Order total in USD

Key points:

Sources don't contain transformation logic
They document existing tables in your warehouse
Used as inputs to Models via {{ source() }}

Models

Models are SQL transformations that create new tables or views from Sources or other Models.

-- models/marts/fct_orders.sql
{{ config(materialized='table') }}

SELECT
    o.order_id,
    o.customer_id,
    o.total_amount,
    o.order_date,
    c.country
FROM {{ source('raw', 'orders') }} o
JOIN {{ ref('stg_customers') }} c
    ON o.customer_id = c.customer_id
WHERE o.status = 'completed'

Materialization types:

Type	Description	Use Case
`view`	Creates a database view	Simple transformations
`table`	Creates a physical table	Heavy aggregations
`incremental`	Appends new data	Large fact tables
`ephemeral`	Inline CTE	Intermediate steps

Cubes

Cubes are semantic entities that define how to analyze a dataset. They contain measures, dimensions, and joins.

# cubes/orders.yml
cubes:
  - name: orders
    sql: "SELECT * FROM {{ ref('fct_orders') }}"
    description: "Order analytics cube"

    measures:
      - name: count
        type: count
      - name: total_revenue
        type: sum
        sql: total_amount

    dimensions:
      - name: order_id
        type: number
        primary_key: true
      - name: order_date
        type: time
      - name: country
        type: string

Key points:

Cubes wrap Models or raw SQL
Define reusable analytical entities
Can join with other Cubes

Measures

Measures are aggregations performed on numeric columns.

Type	Description	Example
`count`	Count of rows	Number of orders
`count_distinct`	Count unique values	Unique customers
`sum`	Sum of values	Total revenue
`avg`	Average value	Average order value
`min`	Minimum value	First order date
`max`	Maximum value	Largest order
`number`	Custom expression	Complex calculations

measures:
  - name: total_revenue
    type: sum
    sql: total_amount
    format: currency
    description: "Sum of all order amounts in USD"

  - name: average_order_value
    type: number
    sql: "{total_revenue} / NULLIF({count}, 0)"
    format: currency

Dimensions

Dimensions are attributes used to filter, group, or slice data.

Type	Description	Example
`string`	Text/categorical	Country, Status
`number`	Numeric	Customer ID, Quantity
`time`	Date/timestamp	Order Date
`boolean`	True/False	Is Active
`geo`	Geographic	Location coordinates

dimensions:
  - name: order_date
    type: time
    sql: order_date
    granularities:
      - day
      - week
      - month
      - quarter
      - year

  - name: customer_segment
    type: string
    sql: |
      CASE
        WHEN lifetime_value > 1000 THEN 'Premium'
        WHEN lifetime_value > 100 THEN 'Regular'
        ELSE 'New'
      END

Joins

Joins define relationships between Cubes, enabling multi-cube queries.

cubes:
  - name: orders
    # ...
    joins:
      - name: customers
        relationship: many_to_one
        sql: "{orders}.customer_id = {customers}.customer_id"

Relationship types:

Type	Description
`one_to_one`	Each row matches exactly one row
`one_to_many`	One row can match multiple rows
`many_to_one`	Multiple rows match one row
`many_to_many`	Multiple rows match multiple rows

Metrics

Metrics are high-level business definitions built on top of Cube measures.

# metrics/revenue.yml
metrics:
  - name: monthly_revenue
    type: simple
    expression: Orders.total_revenue
    time_grain: month
    description: "Total revenue aggregated by month"

  - name: revenue_per_customer
    type: derived
    expression: "{Orders.total_revenue} / {Orders.unique_customers}"
    description: "Average revenue per unique customer"

  - name: gross_margin_pct
    type: ratio
    numerator: Financials.gross_profit
    denominator: Orders.total_revenue
    description: "Gross margin as percentage of revenue"

Metric types:

Type	Description	Use Case
`simple`	Single measure	Basic KPIs
`derived`	Calculated from measures	Compound metrics
`ratio`	Division of two measures	Percentages, rates

Segments

Segments are reusable filter conditions.

segments:
  - name: premium_customers
    sql: "{customers}.lifetime_value > 1000"

  - name: completed_orders
    sql: "{orders}.status = 'completed'"

Used in queries:

{
  "metrics": ["total_revenue"],
  "segments": ["completed_orders", "premium_customers"]
}

Pre-Aggregations

Pre-aggregations are materialized rollups that speed up queries.

pre_aggregations:
  - name: monthly_revenue_by_country
    measures:
      - total_revenue
      - count
    dimensions:
      - country
    time_dimension: order_date
    granularity: month
    refresh:
      cron: "0 2 * * *"  # Daily at 2 AM

Benefits:

10-100x query performance improvement
Automatic query routing
Background refresh

Column-Level Lineage

Olytix Core tracks how data flows from source to metric:

Source Column     →  Model Column      →  Measure        →  Metric
─────────────────────────────────────────────────────────────────────
raw.orders.amount →  fct_orders.total  →  Orders.revenue →  monthly_revenue
     │                    │                    │                │
     └──── DIRECT ────────┘                   │                │
                          └──── DIRECT ───────┘                │
                                              └──── SOURCE ────┘

Edge types:

DIRECT: Direct column reference
RENAMED: Column name changed
DERIVED: Expression transformation
AGGREGATED: Aggregation applied
JOINED: Result of join

Project Structure

A typical Olytix Core project:

my_project/
├── olytix-core_project.yml        # Project configuration
├── sources/
│   └── raw.yml            # Source definitions
├── models/
│   ├── staging/           # Staging models
│   │   └── stg_orders.sql
│   └── marts/             # Mart models
│       └── fct_orders.sql
├── cubes/
│   └── orders.yml         # Cube definitions
├── metrics/
│   └── revenue.yml        # Metric definitions
└── target/
    └── manifest.json      # Compiled output

Semantic Query

A semantic query requests metrics and dimensions without writing SQL:

{
  "metrics": ["total_revenue", "order_count"],
  "dimensions": ["order_date.month", "customer.country"],
  "filters": [
    {
      "dimension": "order_date.year",
      "operator": "equals",
      "value": 2024
    }
  ],
  "order_by": [
    {"field": "total_revenue", "direction": "desc"}
  ],
  "limit": 100
}

Olytix Core translates this into optimized SQL automatically.

Quick Reference

Concept	Definition
Source	Raw data table in the warehouse
Model	SQL transformation creating new tables
Cube	Semantic entity with measures and dimensions
Measure	Aggregation (SUM, COUNT, AVG, etc.)
Dimension	Attribute for filtering/grouping
Metric	Business-level calculation
Segment	Reusable filter condition
Pre-aggregation	Materialized performance optimization
Lineage	Data flow tracking

Next Steps

Quick Start - Build your first project
Cube Fundamentals - Deep dive into cubes
Semantic Queries - Learn to query

The Olytix Core Hierarchy​

Olytix Core Data Hierarchy

Sources​

Models​

Cubes​

Measures​

Dimensions​

Joins​

Metrics​

Segments​

Pre-Aggregations​

Column-Level Lineage​

Project Structure​

Semantic Query​

Quick Reference​

Next Steps​