Skip to main content
In this lesson we’ll cover PromQL — the Prometheus Query Language used to read and transform time series metrics stored in Prometheus. PromQL expressions are sent to the Prometheus server, which evaluates them and returns results that you can:
  • Visualize in dashboards like Grafana
  • Use in alerting rules that notify you when conditions are met
A dark-themed slide titled "What is PromQL" showing icons for a user, Prometheus, and Grafana connected by arrows. It lists three points: PromQL is short for Prometheus Query Language, is the main way to query Prometheus metrics, and its results can be visualized in dashboards.
This section is one of the larger ones. We’ll walk through:
  • Expression data types and what they return
  • Selectors and modifiers
  • Operators and functions
  • Vector matching
  • Built-in aggregators
  • Subqueries
  • Histogram and summary handling
A presentation slide titled "Section Outline" on a dark background. It lists bullet points for topics like Expression Data Structure, Selectors & modifiers, Operators & Functions, Vector Matching, Aggregators, Subqueries, and Histogram/Summary.
When Prometheus evaluates a PromQL expression, the result will be one of four types:
  • string — a plain string (rarely used)
  • scalar — a single numeric (floating-point) value
  • instant vector — a set of time series with one sample per series at a single timestamp
  • range vector — a set of time series with multiple samples per series across a duration
The string result type exists in PromQL but is rarely used in practice. Most queries return scalars, instant vectors, or range vectors.
Below we explain each type with examples and recommendations for when to use them.

​
Scalar

A scalar is a single numeric value (floating point). Scalars are returned by expressions that collapse a set of series into one numeric result — for example, mathematical computations, function results that reduce to a number, or comparisons producing a numeric outcome. Example scalars:
  • 54.743
  • 127.43
Scalars are typically used in alert thresholds or when calculating single-value metrics derived from one or more series.

​
Instant vector

An instant vector is a set of time series where each series provides exactly one sample, all at the same timestamp. In practice, instant vectors are the most common result type for dashboard queries because they represent the current value of each matching series. Example: Querying a metric name directly returns an instant vector containing the latest sample for each matching time series.
Example result (instant vector — one sample per time series at the same timestamp):
Key point: instant vectors show the value at a single point in time for each series — useful for current-state dashboards and immediate comparisons.

​
Range vector

A range vector returns, for each matching time series, a sequence of samples over a specified time window. Use brackets with a duration to select a window (for example, [3m] for the last 3 minutes). Example query for a three-minute range:
Example result (range vector — multiple samples per time series covering the 3m window):
A range vector contains all collected samples for each matching time series within the duration. The number of samples depends on the scrape interval and how many scrapes occurred during that window. Range vectors are required by functions that compute rates, averages over time, or other time-windowed calculations (e.g., rate(), increase(), avg_over_time()).

​
Quick reference table

​
Summary

  • Strings: exist but seldom used
  • Scalars: single floating-point values — used for numeric results and alerts
  • Instant vectors: latest sample per matching time series — used for current-state views
  • Range vectors: sequences of samples across a duration — used for rate and windowed functions
Next in this lesson we’ll dive into selectors and modifiers, which let you precisely choose which time series are included in instant and range vectors.

​
References

Watch Video