`aggregate`

Description

The aggregate command performs calculations across the entire working set of documents, producing summary statistics such as totals, averages, minimums, maximums, or counts. Unlike groupby, which splits data into multiple groups, aggregate computes results over the full dataset as a single group.

Multiple aggregation functions can be combined in one command to produce a single document containing several computed values.

Note

Aggregations are limited to 1000 buckets in a single operation.

Syntax

aggregate <aggregation_expression> [as <result_keypath>] [, <aggregation_expression_2> [as <result_keypath_2>], ...]

Example 1

Use case: Compute several headline KPIs for a dashboard widget

Suppose you have a set of trace logs and you want a single-value summary of the whole dataset — the kind of numbers you'd pin to a dashboard tile: total requests, average and slowest request duration, and how many requests errored. aggregate computes all of them in one pass and returns a single record.

Example data

{ "service": "checkout", "status": 200, "duration": 102 },
{ "service": "checkout", "status": 500, "duration": 890 },
{ "service": "auth", "status": 500, "duration": 1567 },
{ "service": "auth", "status": 200, "duration": 241 }

Example query

aggregate
  count() as total_requests,
  avg(duration) as avg_duration,
  max(duration) as max_duration,
  count_if(status >= 500) as error_count

Example output

total_requests	avg_duration	max_duration	error_count
4	700	1567	2

The aggregate command computes metrics over the entire dataset rather than per group, collapsing all four traces into one summary record. Each aggregation function becomes a column: count() tallies the four requests, avg() and max() reduce the duration field to a mean of 700 and a peak of 1567, and count_if() counts only the two traces whose status is 500 or higher.

Example 2

Use case: Reduce a dataset to a single SLA number

When you only need one headline metric — for example, the share of requests that errored as a single error count — aggregate can run a single function over the same dataset.

Example query

aggregate count_if(status >= 500) as error_count

Example output

error_count
2

Two of the four traces carry a status of 500, so the single-column result reports an error_count of 2.

Last updated on July 6, 2026