Querying basics | Prometheus

Prometheus provides a functional query language called PromQL (Prometheus Query Language) that lets the user select and aggregate time series data in real time.
When you send a query request to Prometheus, it can be an instant query, evaluated at one point in time, or a range query at equally-spaced steps between a start and an end time. PromQL works exactly the same in each case; the range query is just like an instant query run multiple times at different timestamps.
In the Prometheus UI, the "Table" tab is for instant queries and the "Graph" tab is for range queries.
Other programs can fetch the result of a PromQL expression via the HTTP API.
This document is a Prometheus basic language reference. For learning, it may be easier to start with a couple of examples.
The value of a sample at a given timestamp returned by PromQL may be a float or a native histogram. A float sample is a simple floating point number, whereas a native histograms sample contains a full histogram including count, sum, and buckets.
Note that the term “histogram sample” in the PromQL documentation always refers to a native histogram. The term "classic histogram" refers to a set of time series containing float samples with the _bucket, _count, and _sum suffixes that together describe a histogram. From the perspective of PromQL, these contain just float samples, there are no “classic histogram samples”.
Both float samples and histogram samples can have a counter or a gauge “flavor”. Float samples with a counter or gauge flavor are generally simply called “counters” or “gauges”, respectively, while their histogram counterparts are called “counter histograms” or “gauge histograms”. Float samples do not store their flavor, leaving it to the user to take their flavor into account when writing PromQL queries. (By convention, time series containing float counters have a name ending on _total to help with the distinction.)
Since histogram samples “know” their counter or gauge flavor, this allows reliable warnings about mismatched operations. For example, applying the rate function to gauge floats will most likely produce a nonsensical result, but the query will be processed without complains. However, if applied to gauge histograms, the result of the query will be annotated with a warning.
In Prometheus's expression language, an expression or sub-expression can evaluate to one of four types:
Depending on the use case (e.g. when graphing vs. displaying the output of an expression), only some of these types are legal as the result of a user-specified expression. For instant queries, any of the above data types are allowed as the root of the expression. Range queries only support scalar-typed and instant-vector-typed expressions.
Both vectors and time series may contain a mix of float samples and histogram samples.
Native histograms can have different bucket layouts, but they are generally convertible to compatible versions to apply binary and aggregation operations to them. Functions acting on range vectors that are applicable to native histograms also perform such reconciliation. In binary operations this reconciliation is performed pairwise, in aggregation operations and functions all histogram samples are reconciled to one compatible bucket layout.
Not all bucket layouts can be reconciled, if incompatible histograms are encountered in an operation, the corresponding output vector element is removed from the result, flagged with a warn-level annotation. More details can be found in the native histogram specification.
The following section describes literal values of various kinds. Note that there is no “histogram literal”.
String literals are designated by single quotes, double quotes or backticks.
PromQL follows the same escaping rules as Go . For string literals in single or double quotes, a backslash begins an escape sequence, which may be followed by a, b, f, n, r, t, v or \. Specific characters can be provided using octal (\nnn) or hexadecimal (\xnn, \unnnn and \Unnnnnnnn) notations.
Conversely, escape characters are not parsed in string literals designated by backticks. It is important to note that, unlike Go, Prometheus does not discard newlines inside backticks.
Scalar float values can be written as literal integer or floating-point numbers in the format (whitespace only included for better readability):
Additionally, underscores (_) can be used in between decimal or hexadecimal digits to improve readability.
Float literals are also used to specify durations in seconds. For convenience, decimal integer numbers may be combined with the following time units:
Suffixing a decimal integer number with one of the units above is a different representation of the equivalent number of seconds as a bare float literal.
The following examples do not work:
Multiple units can be combined by concatenation of suffixed integers. Units must be ordered from the longest to the shortest. A given unit must only appear once per float literal.
Arithmetic expressions can be used wherever a time duration is expected, that is in range vector selectors and in offset durations.
In offset durations:
When using offset with a duration expression, you must wrap the expression in parentheses. Without parentheses, only the first duration value is used in the offset calculation.
The following operators are supported, following the usual precedence rules:
The following functions can be used inside duration expressions:
For example, max_of(step(), 5s) ensures the duration is never shorter than 5s, while min_of(range(), 1h) caps the duration at 1h.
Note: Duration expressions are not supported in the @ modifier.
Examples of equivalent durations:
These are the basic building-blocks that instruct PromQL what data to fetch.
Instant vector selectors allow the selection of a set of time series and a single sample value for each at a given timestamp (point in time). In the simplest form, only a metric name is specified, which results in an instant vector conta