In PromQL, what does an instant vector selector return versus a range vector selector, and which functions require each?

## Two types, one language Every PromQL expression is evaluated at a single instant in time, called the evaluation timestamp. A **range query** simply repeats that evaluation at fixed steps across a window and stitches the results into a graph, but each individual evaluation still happens at one timestamp. The two vector types describe what a selector hands the rest of the expression at that moment. An **instant vector selector** is a metric name plus optional label matchers, such as `hearings_booked_total{courtroom="4"}`. It returns *one* sample per matching series: the most recent sample at or before the evaluation timestamp. Prometheus looks back a bounded distance for that sample, five minutes by default. If the newest sample of a series is older than that window, the series is not returned at all. It does not read as zero, and it does not carry a stale value forward forever. A **range vector selector** appends a duration in square brackets: `hearings_booked_total{courtroom="4"}[5m]`. It returns *every* sample recorded in the window ending at the evaluation timestamp, for each matching series. One series scraped every 15 seconds yields roughly twenty samples per evaluation instead of one. ## Which functions demand which | Expression | Type | Note | |---|---|---| | `up` | instant vector | one sample per series | | `up[10m]` | range vector | many samples per series | | `rate(up[10m])` | instant vector | consumes a range, emits one value per series | | `sum(rate(up[10m]))` | instant vector | aggregators consume instant vectors | | `time()` | scalar | not a vector at all | - **Range-vector functions** — `rate`, `irate`, `increase`, `delta`, `deriv`, `resets`, `changes` and the whole `_over_time` family such as `avg_over_time`, `max_over_time` and `quantile_over_time` — require the bracketed form. They exist precisely to reduce many samples per series to one. - **Instant-vector functions and operators** — the aggregation operators `sum`, `avg`, `count`, `topk` and `quantile`, arithmetic, comparison, `label_replace`, `absent` and `histogram_quantile` — require a single sample per series. - A **subquery**, written `expr[30m:1m]`, is the one way to build a range vector from an *expression* rather than from a selector. That is why something like `rate(sum(x)[5m:1m])` parses at all, and it is nearly always the wrong query. ## The mistake candidates actually make The single most common error is treating the brackets as "how much history to show" rather than as a change of type. It appears in two symmetrical forms. 1. **A range vector where an instant vector belongs.** `sum(hearings_booked_total[5m])` reads like "sum the last five minutes" and is a type error, because an aggregation operator cannot consume a range vector. The intent "total across series right now" is `sum(hearings_booked_total)`; the intent "sum of the values over time, per series" is `sum_over_time(hearings_booked_total[5m])`. Those are different questions with different answers, and the brackets are what distinguishes them. 2. **An instant vector where a range vector belongs.** `rate(hearings_booked_total)` is a type error too, and the reason is the instructive half: a rate needs at least two samples to subtract, and one sample is all an instant selector ever supplies. The bracketed duration is what provides the second point. A related trap is trying to graph a range vector directly. `hearings_booked_total[5m]` is a legal expression but cannot be rendered as a time series, because at every step it holds many points per series rather than one. Something has to reduce it: a range function, or `last_over_time` when you genuinely want the raw value. ## Why the lookback rule matters in practice Consider a courtroom-scheduling platform whose hearing-booking service runs 41 replicas on a 7-node cluster, scraped every 15 seconds. - An instant query for `up{job="hearing-booking"}` at 09:41:07 does not read values recorded at exactly 09:41:07. It reads each series' most recent sample, which may be up to fifteen seconds old, and it returns nothing at all for a replica that stopped being scraped six minutes ago. - A range vector `[1m]` over the same series returns about four samples each. That is enough for `rate` to work, but only just: two missed scrapes leave a window `rate` cannot use, and those series silently disappear from the result rather than producing an error. - Widening to `[5m]` gives around twenty samples per series and survives several missed scrapes, at the cost of smoothing short spikes. That trade — enough samples to be robust, few enough to stay responsive — is the practical reason the type distinction is worth understanding rather than memorising. The bracket is not decoration. It decides how much data the engine loads per series per evaluation, and therefore both what the answer means and what the query costs.