Everything you need to write PromQL, on one page.

A set of time series, each with a single sample at the evaluation timestamp. The most common return type.

http_requests_total
# → one value per matching series, "now"

Each series carries a window of samples. You can't graph one directly — feed it to rate(), avg_over_time(), etc.

http_requests_total[5m]
# → all samples in the last 5 minutes

A single floating-point number. Returned by literals and the scalar() function.

3.14
scalar(sum(up))

Currently used only as function arguments. You can't query a string.

"five minutes"

The bare name selects every series that shares it.

node_cpu_seconds_total

Exact string match. Most common matcher in everyday queries.

http_requests_total{job="api", method="GET"}

Exclude a label value. Useful for filtering out a noisy instance or status.

http_requests_total{status!="200"}

RE2 regex, fully anchored automatically. Great for OR-ing several values.

http_requests_total{status=~"5.."}
up{job=~"api|web|worker"}

Series whose label does not match the pattern.

requests_total{path!~"/health.*"}

An empty string matches series where the label is unset. Pair with = or !=.

# series WITHOUT an env label
up{env=""}

# series that DO have one
up{env!=""}

The metric name lives in the special __name__ label, so you can regex-match it too.

{__name__=~"node_cpu_.*", cpu="0"}

Shifts the evaluation time backward. @ pins it to a Unix timestamp.

http_requests_total offset 5m

# pin to a specific moment
http_requests_total @ 1672531200

Combine integer + unit. Units can be chained, biggest first, no spaces.

5m      # 5 minutes
1h30m   # 1.5 hours
7d      # 7 days
1y2w    # 1 year 2 weeks
# units: ms s m h d w y

Square brackets after a selector capture all samples in that window.

node_network_receive_bytes_total[5m]

[range:resolution] — evaluates an instant-vector expression over a range, like a recording rule on the fly. Resolution is optional.

max_over_time(
  rate(http_requests_total[5m])[1h:1m]
)

Cost: subqueries re-evaluate the inner expression at each step. Prefer recording rules for hot paths.

Pins evaluation to the start or end of the surrounding range query — handy for rendering "value at the moment of an alert".

http_requests_total @ start()

Add values across series. Almost always combined with by or without.

sum by (job) (http_requests_total)

avg by (instance) (node_load1)

max by (job) (up)

Number of series in each group. Use count_values for value buckets.

count by (job) (up == 1)

by keeps only listed labels; without drops them and keeps the rest. Pick whichever is shorter to type.

sum by (code) (requests)
sum without (instance, pod) (requests)

K highest/lowest series per group — keeps labels, unlike sum.

topk(5, rate(http_requests_total[5m]))

φ-quantile (0–1) across series. For histogram quantiles, see histogram_quantile.

quantile by (job) (0.95, go_goroutines)

Population standard deviation / variance across series in each group.

stddev by (cluster) (node_load1)

Returns a constant 1 per group — useful as a left side in many-to-one joins.

group by (cluster, namespace) (kube_pod_info)