Aggregation functions

These functions aggregate the values of an instant vector across series, optionally grouped with by or without.

`avg`

The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.5 This functionality is generally available and ready for production usage. Preview in 9.4 This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

Calculates the average of the values across the input vector.

Return type

instant_vector

Parameters

v (instant_vector): Instant vector input.

Example

avg(http_requests_total)

`bottomk`

The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

Returns k time series with the lowest values, keeping their full label set. When used with by, bottomk ranks independently within each group.

Return type

instant_vector

Parameters

k (scalar): Number of series to keep.
v (instant_vector): Instant vector input.

Example

bottomk(3, http_requests_total)

Note

Differences from Prometheus

without(...), such as bottomk without (instance) (1, x), isn't supported yet. A k close to Integer.MAX_VALUE can trip Elasticsearch's circuit breaker (the execution engine allocates a buffer sized to k, not to the number of matching series), whereas Prometheus has no equivalent limit.

`count`

Counts the number of elements in the input vector.

Return type

instant_vector

Parameters

v (instant_vector): Instant vector input.

Example

count(http_requests_total)

Note

Differences from Prometheus

Returns a long integer count rather than a floating-point value.

`limit_ratio`

Returns a ratio r of the series from the input vector, keeping their full label set.

Return type

instant_vector

Parameters

r (scalar): Ratio of series to keep (-1 ≤ r ≤ 1); the absolute value selects the share, a negative r inverts the selection.
v (instant_vector): Instant vector input.

Example

limit_ratio(0.5, http_requests_total)

Note

Differences from Prometheus

without(...), such as limit_ratio without (instance) (0.5, x), isn't supported yet. Series are kept by hashing the series identity rather than the Prometheus label serialization, so the kept subset has the same statistical properties but is generally a different subset than the one Prometheus keeps. by is a membership no-op as in Prometheus.

`limitk`

Returns k arbitrary elements from the input vector, keeping their full label set. Unlike topk and bottomk, selection is not sort-based and histogram samples are included.

Return type

instant_vector

Parameters

k (scalar): Number of series to keep.
v (instant_vector): Instant vector input.

Example

limitk(3, http_requests_total)

Note

Differences from Prometheus

without(...), such as limitk without (instance) (1, x), isn't supported yet. Within a shard, elements follow storage order (first-k) rather than truly arbitrary order. Across shards the merge keeps k of those partials with no global tsid sort, so the subset is not stable. A k close to Integer.MAX_VALUE can trip Elasticsearch's circuit breaker (the execution engine allocates a buffer sized to k, not to the number of matching series), whereas Prometheus has no equivalent limit.

`max`

Returns the maximum value across the input vector.

Return type

instant_vector

Parameters

v (instant_vector): Instant vector input.

Example

max(http_requests_total)

`min`

Returns the minimum value across the input vector.

Return type

instant_vector

Parameters

v (instant_vector): Instant vector input.

Example

min(http_requests_total)

`quantile`

Returns the φ-quantile (0 ≤ φ ≤ 1) of the values across the input vector.

Return type

instant_vector

Parameters

φ (scalar): Quantile value (0 ≤ φ ≤ 1).
v (instant_vector): Instant vector input.

Example

quantile(0.9, http_request_duration_seconds)

Note

Differences from Prometheus

A quantile that isn't a number literal, such as quantile(scalar(a), b), isn't supported yet. Computed using the Elasticsearch t-digest percentile aggregation, so results are approximate and may differ slightly from Prometheus's exact linear interpolation, particularly for small sample sets. Non-finite values are ranked as NaN < -Inf < finite < +Inf, the same order Prometheus sorts by. A rank landing exactly on a sample returns that sample, whereas Prometheus still averages in the neighbouring sample weighted by zero, so it returns NaN wherever that neighbour is an infinity.

`stddev`

Calculates the population standard deviation across the input vector.

Return type

instant_vector

Parameters

v (instant_vector): Instant vector input.

Example

stddev(http_requests_total)

`stdvar`

Calculates the population variance across the input vector.

Return type

instant_vector

Parameters

v (instant_vector): Instant vector input.

Example

stdvar(http_requests_total)

`sum`

Calculates the sum of the values across the input vector.

Return type

instant_vector

Parameters

v (instant_vector): Instant vector input.

Example

sum(http_requests_total)

`topk`

Returns k time series with the highest values, keeping their full label set. When used with by, topk ranks independently within each group.

Return type

instant_vector

Parameters

k (scalar): Number of series to keep.
v (instant_vector): Instant vector input.

Example

topk(3, http_requests_total)

Note

Differences from Prometheus

without(...), such as topk without (instance) (1, x), and a k that isn't a number literal, such as topk(scalar(a), b), aren't supported yet. A k close to Integer.MAX_VALUE can trip Elasticsearch's circuit breaker (the execution engine allocates a buffer sized to k, not to the number of matching series), whereas Prometheus has no equivalent limit. A NaN value ranks above +Inf rather than last, so a series whose value is NaN wins a slot ahead of a series with a comparable value. Prometheus ranks NaN farthest from the top and returns the comparable series instead. bottomk is unaffected, because its ascending ranking already places NaN last.