---
title: Aggregation functions
description: PromQL aggregation functions in Elasticsearch that aggregate instant vectors across series.
url: https://www.elastic.co/elastic/docs-builder/docs/4384/reference/query-languages/promql/functions/aggregation
products:
  - Elasticsearch
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.5, Preview in 9.4
---

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

## `avg`

<applies-to>Elastic Stack: Generally available since 9.5, Elastic Stack: Preview in 9.4</applies-to>
Calculates the average of the values across the input vector.
**Return type**
`instant_vector`
**Parameters**
<definitions>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
</definitions>

**Example**
```
avg(http_requests_total)
```


## `bottomk`

<applies-to>Elastic Stack: Planned</applies-to>
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**
<definitions>
  <definition term="k (scalar)">
    Number of series to keep.
  </definition>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
</definitions>

**Example**
```
bottomk(3, http_requests_total)
```

**Differences from Prometheus**
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 `without` grouping clause is not yet supported.

## `count`

<applies-to>Elastic Stack: Generally available since 9.5, Elastic Stack: Preview in 9.4</applies-to>
Counts the number of elements in the input vector.
**Return type**
`instant_vector`
**Parameters**
<definitions>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
</definitions>

**Example**
```
count(http_requests_total)
```

**Differences from Prometheus**
Returns a `long` integer count rather than a floating-point value.

## `limit_ratio`

<applies-to>Elastic Stack: Planned</applies-to>
Returns a ratio `r` of the series from the input vector, keeping their full label set.
**Return type**
`instant_vector`
**Parameters**
<definitions>
  <definition term="r (scalar)">
    Ratio of series to keep (-1 ≤ r ≤ 1); the absolute value selects the share, a negative r inverts the selection.
  </definition>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
</definitions>

**Example**
```
limit_ratio(0.5, http_requests_total)
```

**Differences from Prometheus**
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. A `without` grouping clause is not yet supported.

## `limitk`

<applies-to>Elastic Stack: Planned</applies-to>
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**
<definitions>
  <definition term="k (scalar)">
    Number of series to keep.
  </definition>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
</definitions>

**Example**
```
limitk(3, http_requests_total)
```

**Differences from Prometheus**
Elements are returned in storage order (first-k) rather than truly arbitrary order. 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 `without` grouping clause is not yet supported.

## `max`

<applies-to>Elastic Stack: Generally available since 9.5, Elastic Stack: Preview in 9.4</applies-to>
Returns the maximum value across the input vector.
**Return type**
`instant_vector`
**Parameters**
<definitions>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
</definitions>

**Example**
```
max(http_requests_total)
```


## `min`

<applies-to>Elastic Stack: Generally available since 9.5, Elastic Stack: Preview in 9.4</applies-to>
Returns the minimum value across the input vector.
**Return type**
`instant_vector`
**Parameters**
<definitions>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
</definitions>

**Example**
```
min(http_requests_total)
```


## `quantile`

<applies-to>Elastic Stack: Generally available since 9.5, Elastic Stack: Preview in 9.4</applies-to>
Returns the φ-quantile (0 ≤ φ ≤ 1) of the values across the input vector.
**Return type**
`instant_vector`
**Parameters**
<definitions>
  <definition term="φ (scalar)">
    Quantile value (0 ≤ φ ≤ 1).
  </definition>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
</definitions>

**Example**
```
quantile(0.9, http_request_duration_seconds)
```

**Differences from Prometheus**
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`

<applies-to>Elastic Stack: Generally available since 9.5, Elastic Stack: Preview in 9.4</applies-to>
Calculates the population standard deviation across the input vector.
**Return type**
`instant_vector`
**Parameters**
<definitions>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
</definitions>

**Example**
```
stddev(http_requests_total)
```


## `stdvar`

<applies-to>Elastic Stack: Generally available since 9.5, Elastic Stack: Preview in 9.4</applies-to>
Calculates the population variance across the input vector.
**Return type**
`instant_vector`
**Parameters**
<definitions>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
</definitions>

**Example**
```
stdvar(http_requests_total)
```


## `sum`

<applies-to>Elastic Stack: Generally available since 9.5, Elastic Stack: Preview in 9.4</applies-to>
Calculates the sum of the values across the input vector.
**Return type**
`instant_vector`
**Parameters**
<definitions>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
</definitions>

**Example**
```
sum(http_requests_total)
```


## `topk`

<applies-to>Elastic Stack: Generally available since 9.5</applies-to>
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**
<definitions>
  <definition term="k (scalar)">
    Number of series to keep.
  </definition>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
</definitions>

**Example**
```
topk(3, http_requests_total)
```

**Differences from Prometheus**
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 `without` grouping clause is not yet supported. 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.