Metric Types

For Data Analysts

Olytix Core supports three metric types that cover different analytical use cases. Each type serves a specific purpose in building business-level KPIs on top of cube measures.

Overview

Type	Purpose	Use Case
Simple	Direct measure reference	Single aggregation with optional time grain
Derived	Calculated from other metrics	Complex formulas, period comparisons
Ratio	Division of two measures	Rates, percentages, averages

Simple Metrics

Simple metrics expose a single cube measure as a business KPI. They provide a direct reference to an underlying aggregation.

Basic Definition

# metrics/revenue.yml
metrics:
  - name: total_revenue
    type: simple
    expression: orders.total_revenue
    description: Total revenue from all completed orders

With Time Grain

metrics:
  - name: monthly_revenue
    type: simple
    expression: orders.total_revenue
    time_grain: month
    description: Total revenue aggregated by month

With Formatting

metrics:
  - name: revenue_usd
    type: simple
    expression: orders.total_revenue
    format: "$,.2f"
    description: Total revenue formatted as USD currency
    meta:
      owner: finance-team
      certified: true

Complete Example

metrics:
  - name: active_customers
    type: simple
    expression: customers.active_count
    description: |
      Count of customers with at least one order in the period.
      Excludes trial accounts and internal test users.
    meta:
      owner: growth-team
      data_classification: internal

Derived Metrics

Derived metrics calculate values from other metrics or cube measures using expressions. They enable complex formulas, period comparisons, and composite calculations.

Basic Calculation

metrics:
  - name: average_order_value
    type: derived
    expression: orders.total_revenue / orders.order_count
    description: Average revenue per order

Period Comparison

metrics:
  - name: revenue_growth
    type: derived
    expression: |
      (current.monthly_revenue - prior.monthly_revenue)
      / prior.monthly_revenue
    time_grain: month
    format: ".1%"
    description: Month-over-month revenue growth rate

Multi-Measure Calculation

metrics:
  - name: gross_margin
    type: derived
    expression: |
      (orders.total_revenue - orders.total_cost)
      / orders.total_revenue
    format: ".2%"
    description: Gross margin as percentage of revenue

Using Cube Function Syntax

For complex expressions, use the explicit cube function syntax:

metrics:
  - name: customer_lifetime_value
    type: derived
    expression: |
      cube('orders').measure('total_revenue')
      / cube('customers').measure('customer_count')
    description: Average revenue per customer

Conditional Logic

metrics:
  - name: adjusted_revenue
    type: derived
    expression: |
      CASE
        WHEN orders.total_refunds > 0
        THEN orders.total_revenue - orders.total_refunds
        ELSE orders.total_revenue
      END
    description: Net revenue after refunds

Ratio Metrics

Ratio metrics divide one measure by another. They are optimized for calculating rates, percentages, and per-unit metrics.

Basic Ratio

metrics:
  - name: conversion_rate
    type: ratio
    expression: orders.order_count / sessions.session_count
    format: ".2%"
    description: Percentage of sessions resulting in an order

With Denominator Guard

metrics:
  - name: revenue_per_employee
    type: ratio
    expression: orders.total_revenue / company.employee_count
    format: "$,.0f"
    description: Revenue generated per employee
    meta:
      null_handling: zero_if_null_denominator

Percentage of Total

metrics:
  - name: category_revenue_share
    type: ratio
    expression: orders.category_revenue / orders.total_revenue
    format: ".1%"
    description: Revenue share by product category

Complete Ratio Example

metrics:
  - name: customer_acquisition_cost
    type: ratio
    expression: marketing.total_spend / customers.new_customer_count
    format: "$,.2f"
    time_grain: month
    description: |
      Cost to acquire one new customer.
      Calculated as total marketing spend divided by new customers.
    filters:
      - field: marketing.channel
        operator: not_equals
        value: organic
    meta:
      owner: marketing-ops
      certified: true

Choosing the Right Type

Use Simple When

• Exposing a single measure as a KPI
• Adding time grain to an existing measure
• Applying consistent filters across queries
• Creating a documented, certified metric

Use Derived When

• Calculating values from multiple measures
• Performing period-over-period comparisons
• Applying complex business logic
• Combining metrics from different cubes

Use Ratio When

• Calculating rates or percentages
• Computing per-unit metrics
• Dividing one measure by another
• Ensuring proper null handling for division

Expression Syntax Reference

Measure References

# Short form (cube.measure)
expression: orders.total_revenue

# Explicit form
expression: cube('orders').measure('total_revenue')

Arithmetic Operators

Operator	Description	Example
+	Addition	orders.revenue + orders.fees
-	Subtraction	orders.revenue - orders.refunds
*	Multiplication	orders.quantity * products.price
/	Division	orders.revenue / orders.count

Built-in Functions

# Absolute value
expression: ABS(orders.profit_loss)

# Rounding
expression: ROUND(orders.avg_price, 2)

# Coalesce null values
expression: COALESCE(orders.revenue, 0)

Best Practices

Naming Conventions

# Good: Descriptive, includes unit or context
- name: monthly_active_users
- name: revenue_per_order
- name: customer_churn_rate

# Avoid: Vague or technical names
- name: metric_1
- name: calc_value
- name: tmp_revenue

Documentation

Always include descriptions explaining:

• What the metric measures
• How it is calculated
• Any exclusions or special handling
• Who owns the metric

metrics:
  - name: net_promoter_score
    type: derived
    expression: |
      (surveys.promoter_count - surveys.detractor_count)
      / surveys.response_count * 100
    description: |
      ## Definition
      Net Promoter Score (NPS) measures customer loyalty.

      ## Calculation
      (Promoters - Detractors) / Total Responses * 100

      ## Classification
      - Promoters: Score 9-10
      - Passives: Score 7-8
      - Detractors: Score 0-6

      ## Owner
      Customer Success Team

Next Steps

• Metric Filters - Add filters and constraints to metrics
• Time Grains - Configure time-based aggregations