Unlocking PromQL: How Nested Functional Queries Are Structured and Evaluated

Let's explore how PromQL queries are structured and typed, and how they are evaluated over time.

1. PromQL is a nested functional language

Unlike SQL, PromQL describes the data you seek as a set of nested expressions, each producing an intermediate value without side effects. The outermost expression yields the final result you see in tables or graphs.

Example query:

# Root of the query, final result, approximates a quantile.
histogram_quantile(
  # 1st argument to histogram_quantile(), the target quantile.
  0.9,
  # 2nd argument to histogram_quantile(), an aggregated histogram.
  sum by(le, method, path) (
    # Argument to sum(), the per-second increase of a histogram over 5m.
    rate(
      # Argument to rate(), the raw histogram series over the last 5m.
      demo_api_request_duration_seconds_bucket{job="demo"}[5m]
    )
  )
)

Each sub‑expression (e.g., rate(...)) can be evaluated independently.

2. Expression input may not be what you expect

Prometheus distinguishes two kinds of types:

Metric types reported by scrape targets : counter, gauge, histogram, summary, or untyped.

PromQL expression types : string, scalar, instant vector, or range vector.

PromQL ignores metric types and focuses on expression types. Functions require specific expression types (e.g., rate() needs a range vector and returns an instant vector).

Possible expression types:

String : used rarely as function arguments.

Scalar : a single numeric value without dimensions.

Instant vector : a set of time‑series samples sharing the same timestamp.

Range vector : a set of time‑series samples over a time range, produced by range selectors or sub‑queries.

Example of instant vector data:

node_cpu_seconds_total{cpu="0", mode="idle"}   → 19165078.75 @ timestamp_1
node_cpu_seconds_total{cpu="0", mode="system"} →   381598.72 @ timestamp_1
node_cpu_seconds_total{cpu="0", mode="user"}   → 23211630.97 @ timestamp_1

Example of range vector data:

node_cpu_seconds_total{cpu="0", mode="idle"}   → 19165078.75 @ t1, 19165136.3 @ t2, 19165167.72 @ t3
node_cpu_seconds_total{cpu="0", mode="system"} → 381598.72   @ t1, 381599.98 @ t2, 381600.58 @ t3
node_cpu_seconds_total{cpu="0", mode="user"}   → 23211630.97 @ t1, 23211711.34 @ t2, 23211748.64 @ t3

Metric type matters for function compatibility (e.g., histogram_quantile() works only with histograms, rate() with counters), but PromQL itself does not enforce it.

3. How time enters: instant vs. range queries

PromQL references time only relatively (e.g., [5m]). Absolute time ranges and timestamps are supplied via the Prometheus query API.

3.1 Instant queries

Used for table‑like views showing results at a single evaluation timestamp. Parameters: the PromQL expression and the evaluation timestamp. The expression is evaluated at that timestamp, and any selector can look back within the specified range.

Instant queries return any valid expression type (string, scalar, instant vector, or range vector).

3.2 Range queries

Used for graphs to display results over a time interval. Parameters: expression, start time, end time, and step interval. Each step evaluates the expression as an instant query, and the results are concatenated into a range vector.

Range queries always return a range vector, even if the underlying expression is a scalar or instant vector.

Understanding these concepts gives a clearer picture of PromQL’s overall structure, type checking (or lack thereof), and how queries are parsed and evaluated.