PromQL limitations

PromQL reads metrics stored in time series data streams (TSDS). The following constraints apply to execution in Elasticsearch, including the Prometheus-compatible HTTP API and the ES|QL PROMQL source command, unless stated otherwise. They describe behavioral differences and unsupported areas compared with upstream Prometheus.

Routes that document POST accept parameters in an application/x-www-form-urlencoded body only when security is enabled, xpack.security.http.ssl.enabled is true on the Elasticsearch HTTP interface, and the request is authenticated. TLS that terminates before Elasticsearch (plain HTTP to the node) does not satisfy this check. Use GET with query-string parameters when POST is unavailable.

The PromQL HTTP API documents only the parameters each route accepts. Extra parameters from the Prometheus HTTP API are not supported yet. Elasticsearch does not ignore them: the request fails with 400 Bad Request. Configure clients and integrations to omit them (for example, there is no per-request timeout query parameter). Cancellation and runtime limits follow ES|QL and cluster settings.

For now, /api/v1/query is implemented as a five-minute range query ending at time, returning the last sample per series. Optional lookback_delta from the Prometheus API is not supported yet on this route. See Unsupported Prometheus query parameters and the query endpoint documentation.

When a scrape target disappears, Prometheus ingests staleness markers. Instant vector selectors then omit those series from instant-vector results, so metrics that stopped reporting do not appear as still current.

Elasticsearch does not apply Prometheus staleness markers yet. For now, a series stops appearing in results only once all its samples fall outside the evaluation window, rather than disappearing as soon as data stops arriving.

The majority of PromQL expressions run unchanged. The following constructs are not evaluated yet, so they return a client error (4xx):

• Binary set operators: and and unless. The or operator is supported only at the top level of an expression; nested or returns a client error (4xx).
• Group modifiers: on(...), group_left, group_right
• Functions: see Not yet supported for the full list of recognized but unimplemented functions.

Elasticsearch provides basic support for Prometheus native histograms (the exponential_histogram type in Elasticsearch). The following query patterns work today:

• histogram_quantile on native histograms, including after aggregation: histogram_quantile(0.9, sum by (job) (increase(metric[10m])))
• histogram_count, histogram_sum, and histogram_avg on native histograms
• increase on native histograms
• sum aggregation on native histograms to aggregate across series

In particular, the following features are not available yet for native histograms:

• rate: If possible, use increase instead. The rate function produces fractional bucket counts that native histograms do not support yet. Most queries that use rate can be rewritten with increase (for example, histogram_quantile(0.99, sum by (job) (increase(metric[5m]))) instead of using rate).
• Native histograms as direct result types**: Queries that return a raw native histogram (such as a bare selector my_histogram or increase(my_histogram[5m]) without wrapping in a histogram function) are not supported. Wrap selectors in histogram_quantile, histogram_count, histogram_sum, or histogram_avg to obtain scalar results.
• irate and delta
• Arithmetic operators on native histograms: +, -, *, /
• histogram_fraction and histogram_stddev

On /api/v1/metadata, each metric includes a help string shaped like Prometheus HELP lines. Metric definition help text is not surfaced yet, so the help field remains an empty string.

/api/v1/query_exemplars is not implemented yet, so exemplar queries are not supported. To avoid errors, turn off exemplar queries in your Prometheus-compatible client. In Grafana, go to Data sources → Elasticsearch → Exemplars and disable all configured exemplar links.