---
title: PromQL functions
description: PromQL function reference for Elasticsearch, grouped by category, with Elasticsearch-specific differences from Prometheus.
url: https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions
products:
  - Elasticsearch
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Preview in 9.4
---

# PromQL functions
These functions are based on the [Prometheus query functions](https://prometheus.io/docs/prometheus/latest/querying/functions/). Refer to the Prometheus documentation for the full semantics, and note any Elasticsearch-specific differences called out per function.

## Functions overview


### Range vector functions

Functions that take a range vector and return an instant vector.
<dropdown title="Range vector function list">
  - [`absent_over_time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-absent_over_time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns `1` if the range vector has no elements, and `0` otherwise.
  - [`avg_over_time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-avg_over_time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the average value of all points in the specified time range.
  - [`count_over_time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-count_over_time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the count of all values in the specified time range.
  - [`delta`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-delta) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the difference between the first and last value of each time series in a range vector.
  - [`deriv`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-deriv) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the per-second derivative of the time series using simple linear regression.
  - [`first_over_time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-first_over_time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the first value of each time series in the specified time range.
  - [`idelta`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-idelta) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the difference between the last two samples of each time series in a range vector.
  - [`increase`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-increase) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the increase in the time series in the range vector, adjusting for counter resets.
  - [`irate`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-irate) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the per-second instant rate of increase based on the last two data points.
  - [`last_over_time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-last_over_time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the most recent value of each time series in the specified time range.
  - [`max_over_time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-max_over_time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the maximum value of all points in the specified time range.
  - [`min_over_time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-min_over_time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the minimum value of all points in the specified time range.
  - [`present_over_time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-present_over_time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns `1` if the range vector has at least one element, and `0` otherwise.
  - [`quantile_over_time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-quantile_over_time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the φ-quantile (0 ≤ φ ≤ 1) of the values in the specified time range.
  - [`rate`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-rate) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the per-second average rate of increase of the time series in the range vector.
  - [`stddev_over_time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-stddev_over_time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the population standard deviation of the values in the specified time range.
  - [`stdvar_over_time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-stdvar_over_time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the population variance of the values in the specified time range.
  - [`sum_over_time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/range-vector#promql-fn-sum_over_time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the sum of all values in the specified time range.
</dropdown>


### Aggregation functions

Functions that aggregate an instant vector across series.
<dropdown title="Aggregation function list">
  - [`avg`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/aggregation#promql-fn-avg) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the average of the values across the input vector.
  - [`count`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/aggregation#promql-fn-count) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Counts the number of elements in the input vector.
  - [`max`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/aggregation#promql-fn-max) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the maximum value across the input vector.
  - [`min`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/aggregation#promql-fn-min) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the minimum value across the input vector.
  - [`quantile`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/aggregation#promql-fn-quantile) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the φ-quantile (0 ≤ φ ≤ 1) of the values across the input vector.
  - [`stddev`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/aggregation#promql-fn-stddev) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the population standard deviation across the input vector.
  - [`stdvar`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/aggregation#promql-fn-stdvar) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the population variance across the input vector.
  - [`sum`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/aggregation#promql-fn-sum) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the sum of the values across the input vector.
  - [`topk`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/aggregation#promql-fn-topk) <applies-to>Elastic Stack: Planned</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.
</dropdown>


### Histogram functions

Functions that operate on histogram metrics.
<dropdown title="Histogram function list">
  - [`histogram_avg`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/histogram#promql-fn-histogram_avg) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the arithmetic average of observations stored in a native histogram.
  - [`histogram_count`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/histogram#promql-fn-histogram_count) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the count of observations stored in a native histogram.
  - [`histogram_quantile`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/histogram#promql-fn-histogram_quantile) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the φ-quantile of a classic histogram represented by cumulative `le` buckets or a native (exponential) histogram.
  - [`histogram_sum`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/histogram#promql-fn-histogram_sum) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the sum of observations stored in a native histogram.
</dropdown>


### Math functions

Mathematical, trigonometric, and rounding functions.
<dropdown title="Math function list">
  - [`abs`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-abs) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the input vector with all sample values converted to their absolute value.
  - [`acos`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-acos) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the arccosine of all elements in the input vector.
  - [`acosh`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-acosh) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the inverse hyperbolic cosine of all elements in the input vector.
  - [`asin`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-asin) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the arcsine of all elements in the input vector.
  - [`asinh`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-asinh) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the inverse hyperbolic sine of all elements in the input vector.
  - [`atan`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-atan) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the arctangent of all elements in the input vector.
  - [`atanh`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-atanh) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the inverse hyperbolic tangent of all elements in the input vector.
  - [`ceil`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-ceil) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Rounds the sample values of all elements up to the nearest integer.
  - [`clamp`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-clamp) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Clamps the sample values of all elements to be within [min, max].
  - [`clamp_max`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-clamp_max) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Clamps the sample values of all elements to have an upper limit of max.
  - [`clamp_min`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-clamp_min) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Clamps the sample values of all elements to have a lower limit of min.
  - [`cos`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-cos) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the cosine of all elements in the input vector.
  - [`cosh`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-cosh) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the hyperbolic cosine of all elements in the input vector.
  - [`deg`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-deg) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Converts input values from radians to degrees for all elements in the input vector.
  - [`exp`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-exp) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the exponential function for all elements in the input vector.
  - [`floor`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-floor) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Rounds the sample values of all elements down to the nearest integer.
  - [`ln`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-ln) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the natural logarithm for all elements in the input vector.
  - [`log10`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-log10) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the decimal logarithm for all elements in the input vector.
  - [`log2`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-log2) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the binary logarithm for all elements in the input vector.
  - [`pi`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-pi) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the value of pi.
  - [`rad`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-rad) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Converts input values from degrees to radians for all elements in the input vector.
  - [`round`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-round) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Rounds the sample values to the nearest integer, or to the nearest multiple of the optional argument.
  - [`sgn`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-sgn) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the sign of the sample values: -1 for negative, 0 for zero, and 1 for positive values.
  - [`sin`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-sin) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the sine of all elements in the input vector.
  - [`sinh`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-sinh) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the hyperbolic sine of all elements in the input vector.
  - [`sqrt`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-sqrt) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the square root of all elements in the input vector.
  - [`tan`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-tan) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the tangent of all elements in the input vector.
  - [`tanh`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/math#promql-fn-tanh) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Calculates the hyperbolic tangent of all elements in the input vector.
</dropdown>


### Date and time functions

Functions that extract date and time components from timestamps.
<dropdown title="Date and time function list">
  - [`day_of_month`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/date-time#promql-fn-day_of_month) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the day of the month for each of the input timestamps (in UTC). Returned values are from 1 to 31.
  - [`day_of_week`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/date-time#promql-fn-day_of_week) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the day of the week for each of the input timestamps (in UTC). Returned values are from 0 to 6, where 0 means Sunday.
  - [`day_of_year`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/date-time#promql-fn-day_of_year) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the day of the year for each of the input timestamps (in UTC). Returned values are from 1 to 366.
  - [`days_in_month`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/date-time#promql-fn-days_in_month) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the number of days in the month for each of the input timestamps (in UTC). Returned values are from 28 to 31.
  - [`hour`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/date-time#promql-fn-hour) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the hour of the day for each of the input timestamps (in UTC). Returned values are from 0 to 23.
  - [`minute`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/date-time#promql-fn-minute) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the minute of the hour for each of the input timestamps (in UTC). Returned values are from 0 to 59.
  - [`month`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/date-time#promql-fn-month) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the month of the year for each of the input timestamps (in UTC). Returned values are from 1 to 12.
  - [`time`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/date-time#promql-fn-time) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the number of seconds since January 1, 1970 UTC. Note that this does not actually return the current time, but the time at which the expression is being evaluated.
  - [`timestamp`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/date-time#promql-fn-timestamp) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the timestamp of each sample of the given vector as the number of seconds since January 1, 1970 UTC. It acts on float and histogram samples in the same way.
  - [`year`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/date-time#promql-fn-year) <applies-to>Elastic Stack: Planned</applies-to>
    Returns the year for each of the input timestamps (in UTC).
</dropdown>


### Conversion functions

Functions that convert between scalars and instant vectors.
<dropdown title="Conversion function list">
  - [`scalar`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/conversion#promql-fn-scalar) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the sample value of a single-element instant vector as a scalar. If the input vector does not have exactly one element, scalar returns NaN.
  - [`vector`](/elastic/elasticsearch/pull/154972/reference/query-languages/promql/functions/conversion#promql-fn-vector) <applies-to>Elastic Stack: Preview in 9.4</applies-to>
    Returns the scalar as a vector with no labels.
</dropdown>


## Not yet supported

The following PromQL functions are recognized but not yet supported in Elasticsearch. Using them returns a client error (4xx):
- `absent`
- `bottomk`
- `changes`
- `count_values`
- `group`
- `histogram_fraction`
- `histogram_stddev`
- `histogram_stdvar`
- `holt_winters`
- `label_join`
- `label_replace`
- `mad_over_time`
- `predict_linear`
- `resets`
- `sort`
- `sort_desc`