ES|QL PROMQL command

The PROMQL source command queries time series indices using Prometheus Query Language (PromQL). Like TS, it enables time series aggregation functions, but accepts PromQL syntax instead of ES|QL.

The PROMQL command accepts zero or more space-separated <option>=<value> pairs, followed by a PromQL expression in parentheses that can be prefixed with a result name.

PROMQL [ <option>=<value> ... ] [ <result_name>= ](<PromQL Expression>)
		

The options are inspired by the Prometheus HTTP API with some additions specific to ES|QL.

index

A list of indices, data streams, or aliases. Supports wildcards and date math. Defaults to metrics-* querying matching indices with index.mode: time_series. Example: PROMQL index=metrics-*.otel-* http_rate=(sum(rate(http_requests_total)))

step

Query resolution step width (optional). Automatically determined given the number of target buckets and the selected time range. Example: PROMQL step=1m http_rate=(sum(rate(http_requests_total)))

buckets

Target number of buckets for auto-step derivation. Defaults to 100. Mutually exclusive with step. Requires a known time range, either by setting start and end explicitly or implicitly through Kibana's time range filter. Example: PROMQL buckets=50 start="2026-04-01T00:00:00Z" end="2026-04-01T01:00:00Z" http_rate=(sum(rate(http_requests_total)))

start

Start time of the query, inclusive (optional). Uses the start based on Kibana's date picker if missing. Set together with end. Refer to Time range for queries without a time range. Example: PROMQL start="2026-04-01T00:00:00Z" end="2026-04-01T01:00:00Z" http_rate=(sum(rate(http_requests_total)))

end

End time of the query, inclusive (optional). Uses the end based on Kibana's date picker if missing. Set together with start, and not before it. Refer to Time range for queries without a time range. Example: PROMQL start="2026-04-01T00:00:00Z" end="2026-04-01T02:00:00Z" http_rate=(sum(rate(http_requests_total)))

time

Evaluation time of an instant query (optional). Evaluates the expression once, at this time, instead of at each step of a range query. Mutually exclusive with start, end, step, and buckets. Example: PROMQL time="2026-04-01T01:00:00Z" http_rate=(sum(rate(http_requests_total)))

scrape_interval

The expected metric collection interval. Defaults to 1m. Used to determine implicit range selector windows as max(step, scrape_interval). Example: PROMQL scrape_interval=15s http_rate=(sum(rate(http_requests_total)))

<result_name>=(<PromQL Expression>)

Name of the output column with the query result timeseries (optional). By default, the name of the output column is the PromQL expression itself. Example: PROMQL http_rate=(sum by (instance) (rate(http_requests_total))) | SORT http_rate DESC

start, end, and time accept an RFC 3339 timestamp with a UTC offset, such as "2026-04-01T00:00:00Z", or a Unix timestamp in seconds, which can be fractional, such as 1775001600. Date math, such as now-1h, isn't supported. In Kibana, the ?_tstart and ?_tend parameters reference the time range of the date picker, such as time=?_tend. step and scrape_interval accept a PromQL duration, such as 30s or 5m, or a number of seconds.

The PROMQL command takes standard PromQL parameters and a PromQL expression, runs the query, and returns the results as regular ES|QL columns. You can continue to process the columns with other ES|QL commands.

A range query needs either step, or both start and end, from which the step is derived using buckets. In Kibana, the date picker provides start and end. Without a time range and without step, the query fails. With step but no time range, the query covers all data in the index.

The result contains the following columns:

The label columns depend on the outermost aggregation of the PromQL expression:

• With a by grouping, such as sum by (instance) (...), each grouping label gets its own output column.
• With an aggregation without grouping, such as sum(...), there are no label columns, and the result is a single series.
• Without a cross-series aggregation, such as rate(http_requests_total), or with a without grouping, such as sum without (pod) (...), the remaining labels of each series are returned in a single _timeseries column as a JSON string.

A range query returns one row per series and evaluation step. An instant query returns one row per series.

The index parameter accepts the same patterns as FROM and TS, including wildcards and comma-separated lists. If omitted, it defaults to metrics-*, which queries matching indices configured with index.mode: time_series. The Prometheus-compatible query and query_range endpoints use the same default when the {index} path parameter is omitted.

In standard PromQL, functions like rate require a range selector: rate(http_requests_total[5m]). The PROMQL command allows omitting the range selector entirely. When the range selector is absent, the window is determined automatically as max(step, scrape_interval). For example: PROMQL scrape_interval=15s http_rate=(sum(rate(http_requests_total))).

An implicit window adapts to the time range and step. A fixed window doesn't: when it's shorter than the step, such as [5m] with a step of 1h, each step only reflects the last 5 minutes and ignores the samples in between. A fixed window is only useful when you need exactly that window, such as the rate over the last 5 minutes.

A duration, such as in a range selector, can be the difference of two RFC 3339 timestamp parameters. For example, [?_tend - ?_tstart] spans the time range of the date picker in Kibana.

• Set index explicitly instead of relying on the metrics-* default, to narrow the data scanned.
• Omit range selectors, also when porting a Prometheus query: write rate(http_requests_total) instead of rate(http_requests_total[5m]), so the window adapts to the time range and step. Refer to Implicit range selectors. The exception is a value over the whole time range. Refer to Single-value results.
• Name the result, such as http_rate=(...). Otherwise, the value column is named after the expression text, which changes whenever the expression is reformatted, so later commands can't reliably reference it.
• Match the function to the metric type: use rate, irate, or increase for counters, and functions such as avg_over_time or max_over_time, or the raw metric, for gauges. For native histograms, use increase instead of rate, and wrap the result in a histogram function, such as histogram_quantile(0.99, sum by (job) (increase(http_request_duration_seconds))).
• In Kibana, omit start and end so the query follows the date picker. Elsewhere, set start and end explicitly, rather than only step, which covers all data in the index.
• Filter by labels in the PromQL selector, such as network.cost{cluster!="prod"}, rather than with WHERE after PROMQL. Selector filters reduce the data read, and a later WHERE doesn't.

A range query returns a value for every step. To get a single value per series, such as for a metric or gauge chart or a ranking, use an instant query. In Kibana, set time=?_tend to evaluate the expression at the end of the time range of the date picker (refer to time range parameters).

• For the current value, such as the current request rate, omit the range selector:

  PROMQL index=metrics-generic.prometheus-* time=?_tend http_rate=(sum(rate(http_requests_total)))
  		

• For a value over the whole time range, such as the total number of requests, use a range selector that spans the time range, [?_tend - ?_tstart] :

  PROMQL index=metrics-generic.prometheus-* time=?_tend
    total_requests=(sum(increase(http_requests_total[?_tend - ?_tstart])))
  		

  This is also how to port a Grafana query that uses the $__range variable, or its $__range_s and $__range_ms variants: replace the range selector, such as [$__range] or [${__range_s}s], with [?_tend - ?_tstart], and set time=?_tend. Refer to Time range durations.

Rely on Kibana's date picker for the time range, and let step and range selectors be inferred automatically:

PROMQL index=metrics-generic.prometheus-* http_rate=(sum(rate(http_requests_total)))
		

This is the recommended pattern for Kibana dashboards. The query responds to the date picker, adjusts the step size to the selected time range, and sizes the range selector window accordingly.

Evaluate the expression once, for example to get the current value of a metric:

PROMQL index=metrics-generic.prometheus-*
  time="2026-04-01T01:00:00Z"
  http_rate=(sum(rate(http_requests_total)))
		

PROMQL index=k8s step=1h result=(sum by (cluster) (network.cost))
| SORT result
		

PROMQL index=k8s step=1h cost=(max by (cluster) (network.total_bytes_in{cluster!="prod"}))
| SORT cluster
		

Pipe PromQL results into ES|QL commands for further aggregation:

PROMQL index=k8s step=1h bytes=(max by (cluster) (network.bytes_in))
| STATS max_bytes=MAX(bytes) BY cluster
| SORT cluster
		

For queries outside Kibana, set start and end explicitly. The step and range selector are still inferred automatically from the time range and the default buckets count:

PROMQL index=metrics-generic.prometheus-*
  start="2026-04-01T00:00:00Z"
  end="2026-04-01T01:00:00Z"
  http_rate=(sum(rate(http_requests_total)))
		

Join PromQL results with external data using ES|QL commands:

PROMQL index=metrics-generic.prometheus-*
  http_rate=(sum by (instance) (rate(http_requests_total)))
| LOOKUP JOIN instance_metadata ON instance
		

This section lists the differences from Prometheus 3.x.

Sections follow Querying basics in the Prometheus documentation.

In the examples on this page, h is a native histogram metric.

Supported

Native histograms, stored as exponential_histogram fields. histogram_quantile, histogram_count, histogram_sum, histogram_avg, increase, and sum support them, such as histogram_quantile(0.9, sum by (job) (increase(h[5m]))).

histogram_fraction and changes support them too.

Classic histograms, stored as _bucket series with an le label, such as histogram_quantile(0.9, sum by (le) (rate(x_bucket[5m]))).

Not supported yet

Supported

Range vectors as function arguments, such as rate(x[5m]). In the PROMQL command, the range can be left out, such as rate(x). Refer to Implicit range selectors.

Not supported yet

Supported

String literals in single quotes, double quotes, or backticks. Float literals, including scientific notation, hexadecimal, Inf, and NaN, such as 1e3 and 0x1f. Time durations, such as 1h30m, and duration arithmetic, such as x[5m + 1m].

Not supported yet

Supported

A metric name with the label matchers =, !=, =~, and !~, such as http_requests_total{job="api", code=~"5.."}.

Not supported yet

Behaves differently

Supported

A range selector with a duration, such as x[5m] or x[1h30m].

Not supported yet

Supported

offset on instant and range selectors, such as x offset 5m and rate(x[5m] offset 1h).

Behaves differently

Not supported yet

Not supported yet

Supported

A selector without a range, such as http_requests_total, returns the latest sample of each series within the lookback window at each evaluation time.

Behaves differently

Sections follow Operators in the Prometheus documentation. Each operator reference entry lists further differences.

Supported

+, -, *, /, %, and ^ between scalars, between an instant vector and a scalar, such as rate(x[5m]) * 60, and between two instant vectors. Vector matching lists which pairs of instant vectors match.

Not supported yet

Not supported yet

Supported

==, !=, >, <, >=, and <= between an instant vector and a number, such as rate(x[5m]) > 100, with or without bool, such as x > bool 100.

Not supported yet

Supported

or between instant vectors, such as rate(a[5m]) or rate(b[5m]). An or chain takes at most 8 operands by default.

Change the limit with the esql.query.max_branch_count_per_merge cluster setting.

Not supported yet

Supported

Arithmetic between unaggregated metrics stored together in the same time series, such as network.bytes_in / network.connections, without explicit vector matching modifiers.

Arithmetic between operands aggregated without grouping, such as sum(a) / sum(b).

One-to-one, many-to-one, and one-to-many matching between operands aggregated with by(...), including on, ignoring, group_left, and group_right. For example: sum by (instance) (a) / on(instance) sum by (instance) (b).

Not supported yet

Behaves differently

Supported

• sum, avg, min, max, count, quantile, stddev, and stdvar, with by(...), without(...), or no grouping.
• topk, bottomk, limitk, and limit_ratio.

Not supported yet

Behaves differently

Rows follow Functions in the Prometheus documentation and are sorted by function name. Each function reference entry lists further differences.

Supported

The functions in the PromQL functions reference, such as rate, increase, histogram_quantile, label_replace, and the <aggregation>_over_time functions.

Not supported yet

Behaves differently