Instant and Range Selectors

Instant Vector Selectors

An instant vector selector returns the latest sample for each time series matching the given metric name and label selectors. This is the most basic PromQL building block.

# All series for http_requests_total
http_requests_total

# Only GET requests returning 200
http_requests_total{method="GET", status="200"}

# Series where endpoint starts with /api
http_requests_total{endpoint=~"/api.*"}

Label Matchers

Label matchers filter time series by label values. Prometheus supports exact match, not-equal, regex match, and negative regex match. Combining matchers narrows the selection precisely.

Range Vector Selectors

A range vector selects a range of samples over time. You append a time duration in brackets to an instant vector selector. Range vectors are used as the input to functions like rate, increase, and histogram_quantile.

# Last 5 minutes of samples
http_requests_total[5m]

# Last 1 hour
http_requests_total[1h]

# Combined with rate
rate(http_requests_total{method="GET"}[5m])

Offset Modifier

The offset modifier shifts the time reference backward. It lets you compare current values against historical baselines. The offset is applied to the entire selector, including range vectors.

# Current QPS vs QPS 1 week ago
rate(http_requests_total[5m]) / rate(http_requests_total[5m] offset 7d)

# Memory usage 1 hour ago
node_memory_MemAvailable_bytes offset 1h

Subqueries

Subqueries evaluate an inner query at every step of an outer range. They let you apply functions like max_over_time or avg_over_time to derived metrics. The syntax uses double brackets after an instant vector.

# Max QPS over the last hour, evaluated every minute
max_over_time(
  rate(http_requests_total[5m])[1h:1m]
)

# 95th percentile latency over 6 hours
histogram_quantile(0.95,
  rate(http_request_duration_seconds_bucket[5m])[6h:5m]
)

@ Modifier

The @ modifier fixes the evaluation time of a selector to a specific Unix timestamp. This is useful for dashboards that need to compare values at fixed points in time or for testing specific historical states.

# Value at exactly midnight UTC
http_requests_total @ 1700000000

# Range starting from a fixed time
rate(http_requests_total[5m] @ 1700000000)