Metrics Schema

Metrics are business-level calculations that compose one or more cube measures. They provide a business-friendly abstraction layer that standardizes how KPIs are calculated across your organization. This reference documents all fields available when defining metrics.

File Location

Metric definitions are stored in YAML files within the metrics/ directory:

my-project/
└── metrics/
    ├── revenue.yml
    ├── customers.yml
    └── operations/
        └── fulfillment.yml

Top-Level Structure

metrics:
  - name: metric_name
    # ... metric configuration

Metric Definition

Field	Type	Required	Default	Description
name	string	Yes	-	Unique identifier for the metric
type	string	No	derived	Metric type: simple, derived, cumulative
expression	string	Yes	-	Expression defining the metric calculation
description	string	No	null	Human-readable description
time_grain	string	No	null	Default time granularity
filters	list	No	[]	Default filters applied to the metric
format	string	No	null	Output format: currency, percent, number
meta	object	No	{}	Custom metadata key-value pairs

Metric Types

Simple Metrics

Simple metrics reference a single measure from a cube without additional transformation.

metrics:
  - name: total_revenue
    type: simple
    expression: orders.total_revenue
    description: Total revenue from all orders

Derived Metrics

Derived metrics combine multiple measures with mathematical operations.

metrics:
  - name: average_revenue_per_customer
    type: derived
    expression: orders.total_revenue / orders.unique_customers
    description: Average revenue generated per unique customer

Cumulative Metrics

Cumulative metrics calculate running totals over time.

metrics:
  - name: cumulative_revenue
    type: cumulative
    expression: orders.total_revenue
    time_grain: month
    description: Running total of revenue over time

Expression Syntax

Metric expressions use a simple syntax to reference cube measures:

<cube_name>.<measure_name>

Basic Expressions

# Reference a single measure
expression: orders.total_revenue

# Mathematical operations
expression: orders.total_revenue - orders.total_cost

# Division
expression: orders.total_revenue / orders.count

# Complex expressions
expression: (orders.total_revenue - orders.refunds) / orders.count

Advanced Expression Syntax

For more complex scenarios, you can use the full cube reference syntax:

expression: "cube('orders').measure('total_revenue') / cube('orders').measure('count')"

Filter Definition

Filters restrict the data used in metric calculations.

Field	Type	Required	Default	Description
field	string	Yes	-	Field to filter on (cube.dimension or cube.measure)
operator	string	No	equals	Comparison operator
value	any	Conditional	-	Value to compare against

Filter Operators

Operator	Description	Example
equals	Equal to value	status = 'completed'
not_equals	Not equal to value	status != 'cancelled'
gt	Greater than	total > 100
gte	Greater than or equal	total >= 100
lt	Less than	total < 100
lte	Less than or equal	total <= 100
contains	String contains value	name LIKE '%test%'
not_contains	String does not contain	name NOT LIKE '%test%'
in	Value in list	status IN ('a', 'b')
not_in	Value not in list	status NOT IN ('a', 'b')
is_null	Value is null	field IS NULL
is_not_null	Value is not null	field IS NOT NULL

Filter Examples

metrics:
  - name: completed_revenue
    type: simple
    expression: orders.total_revenue
    description: Revenue from completed orders only
    filters:
      - field: orders.status
        operator: equals
        value: completed

  - name: high_value_order_count
    type: simple
    expression: orders.count
    description: Number of orders over $1000
    filters:
      - field: orders.total_amount
        operator: gt
        value: 1000

  - name: active_customer_revenue
    type: simple
    expression: orders.total_revenue
    filters:
      - field: orders.status
        operator: in
        value: ['pending', 'completed', 'shipped']
      - field: orders.is_test
        operator: equals
        value: false

Time Grain

The time_grain field specifies the default time granularity for the metric.

Value	Description
second	Per-second aggregation
minute	Per-minute aggregation
hour	Hourly aggregation
day	Daily aggregation
week	Weekly aggregation
month	Monthly aggregation
quarter	Quarterly aggregation
year	Yearly aggregation

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

  - name: daily_active_users
    type: simple
    expression: users.active_count
    time_grain: day
    description: Count of active users per day

Format Options

The format field controls how metric values are displayed.

Format	Description	Example
currency	Currency formatting	$1,234.56
percent	Percentage formatting	12.34%
number	Numeric formatting	1,234.56

metrics:
  - name: total_revenue
    type: simple
    expression: orders.total_revenue
    format: currency
    description: Total revenue in USD

  - name: conversion_rate
    type: derived
    expression: orders.count / visits.count
    format: percent
    description: Order conversion rate

Complete Examples

Revenue Metrics

metrics:
  - name: total_revenue
    type: simple
    expression: orders.total_revenue
    format: currency
    description: Total revenue from all orders
    meta:
      category: revenue
      owner: finance-team

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

  - name: net_revenue
    type: derived
    expression: orders.total_revenue - orders.refunds - orders.discounts
    format: currency
    description: Revenue after refunds and discounts

  - name: gross_margin
    type: derived
    expression: (orders.total_revenue - orders.cost_of_goods) / orders.total_revenue
    format: percent
    description: Gross profit margin percentage

  - name: revenue_per_order
    type: derived
    expression: orders.total_revenue / orders.count
    format: currency
    description: Average revenue per order

Customer Metrics

metrics:
  - name: total_customers
    type: simple
    expression: orders.unique_customers
    description: Total number of unique customers

  - name: new_customers
    type: simple
    expression: customers.new_count
    time_grain: month
    description: New customers acquired per month

  - name: customer_retention_rate
    type: derived
    expression: customers.returning_count / customers.previous_period_count
    format: percent
    description: Percentage of customers who returned

  - name: customer_lifetime_value
    type: derived
    expression: orders.total_revenue / orders.unique_customers
    format: currency
    description: Average revenue per customer
    filters:
      - field: orders.status
        operator: equals
        value: completed

Operational Metrics

metrics:
  - name: order_completion_rate
    type: derived
    expression: orders.completed_count / orders.count
    format: percent
    description: Percentage of orders that were completed
    meta:
      sla_target: 0.95

  - name: average_fulfillment_time
    type: simple
    expression: orders.avg_fulfillment_hours
    description: Average time to fulfill orders in hours
    filters:
      - field: orders.status
        operator: equals
        value: completed

  - name: cancellation_rate
    type: derived
    expression: orders.cancelled_count / orders.count
    format: percent
    description: Percentage of orders that were cancelled

Metric Dependencies

Metrics can reference measures from multiple cubes, creating cross-cube calculations:

metrics:
  - name: revenue_per_visit
    type: derived
    expression: orders.total_revenue / website.visits
    format: currency
    description: Revenue generated per website visit

  - name: conversion_rate
    type: derived
    expression: orders.unique_customers / website.unique_visitors
    format: percent
    description: Visitor to customer conversion rate

Using Metrics in Queries

Query metrics via the API:

curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["monthly_revenue", "conversion_rate"],
    "dimensions": ["orders.region"],
    "time_dimension": {
      "dimension": "orders.order_date",
      "granularity": "month"
    }
  }'

Best Practices

1. Use descriptive names: Choose names that clearly communicate the business meaning.

2. Document thoroughly: Provide descriptions explaining what the metric measures and how it is calculated.

3. Set appropriate formats: Use format to ensure consistent display across tools.

4. Define default time grains: Set time_grain for time-series metrics.

5. Use metadata for governance: Track ownership, categories, and certification status in meta.

6. Apply filters carefully: Document any filters that restrict the data included in the metric.

7. Group related metrics: Organize metrics into files by business domain (e.g., revenue.yml, customers.yml).

8. Version control descriptions: Keep descriptions updated as business definitions evolve.