Dimensions and metrics

Dimensions describe what each row is about. Metrics describe what is calculated for that row.

Dimensions#

A dimension references a model field and may define an output alias.

Examples:

• country groups results by country;
• plan groups results by subscription plan;
• occurred_at with a day bucket groups results by calendar day;
• a second dimension can define a series within the first dimension.

Array dimensions can return native arrays or joined text. Joined output uses the configured separator. An object field may be addressed with an explicit dotted path such as device.id. Arrays of objects cannot currently be grouped.

Metrics#

Supported aggregations are:

Each metric needs an output alias. For example, counting records with alias request_count produces a request_count key in every result row.

Multiple dimensions and metrics#

Supported warehouses can execute multiple grouped dimensions and multiple metrics in one definition. This powers stacked, scatter, cohort, and combo visualizations.

Keep result shapes understandable. A very wide combination of high-cardinality dimensions can be expensive and difficult to visualize even when technically valid.

Example definition fragment#

{
  "dimensions": [
    { "field": "occurred_at", "bucket": "day", "alias": "day" },
    { "field": "plan", "alias": "plan" }
  ],
  "metrics": [
    { "aggregation": "count", "alias": "request_count" },
    { "field": "duration_ms", "aggregation": "avg", "alias": "average_duration_ms" }
  ]
}