PromQL Syntax Guide
Prerequisites
- If you are unfamiliar with the PromQL query language, please refer to the official documentation: https://prometheus.io/docs/prometheus/latest/querying/basics/
- Understand Bonree's metric type classifications and the aggregation methods supported by its metrics.
Important Notes
Due to differences in how metrics are stored in Prometheus versus Bonree, the following modifications have been made to PromQL syntax support:
-
For instant queries, Bonree
frmand custom metric types, as well as metrics lacking alastaggregation method, are not supported.- Explanation: The semantics of an instant vector require the most recent value from the last 5 minutes for each time series. Bonree metrics are stored pre-aggregated by time granularity. Only metrics that support the
last(latest value) aggregation method can be used for this type of query.
- Explanation: The semantics of an instant vector require the most recent value from the last 5 minutes for each time series. Bonree metrics are stored pre-aggregated by time granularity. Only metrics that support the
-
Range vectors do not support querying detailed raw data. Instead, calculations are based on the current time range granularity using the metric's default aggregation method.
- Explanation: The semantics of a range vector require the detailed raw data points reported over a time range. Bonree uses pre-aggregation, summarizing data by time granularity beforehand. For performance reasons, when the time range is long, the range vector query will use the granularity of the target table and the metric's default aggregation method, making it impossible to retrieve fine-grained raw data.
-
The
<aggregation>_over_time()functions perform calculations on range vector data. Whether a function can be used depends on whether the metric supports the corresponding aggregation method.- Explanation: The
agg_over_timefunctions (exceptstddev_over_timeandstdvar_over_time) are used to aggregate detailed data within a range_vector. If the metric does not support the required aggregation method, the query will fail.
- Explanation: The
-
It is recommended to use PromQL primarily for querying metrics data ingested from Prometheus.
Query Types
- Similar to Prometheus, both instant and range query types are supported.
- Range queries do not support custom
stepvalues; internal default rules apply (see Granularity section below).
Granularity
When querying metric data, point aggregation is performed at different time granularities depending on the selected time range.
- Range Query Granularity:
| Time Range | Granularity |
|---|---|
| ≤30 minutes | 15 seconds |
| ≤3 hours | 1 minute |
| ≤24 hours | 10 minutes |
| ≤7 days | 1 hour |
| ≤14 days | 6 hours |
| ≥14 days | 1 day |
PromQL Syntax Support List
(Based on Prometheus 2.53, https://prometheus.io/docs/prometheus/latest/querying/basics/)
Items marked in yellow in the table represent unsupported syntax.
| Category | Name & Details | Supported |
|---|---|---|
| Basic Data Types | instant vector | ✓ |
| range vector | Modified | |
| literals (numeric and string constants) | ✓ | |
| Selectors | = (match string) | ✓ |
!= (not match string) | ✓ | |
=~ (regex match) | ✓ | |
!~ (regex not match) | ✓ | |
| Time Selection | @ (evaluation time, e.g., http_requests_total @ 1609746000) | ✓ |
offset (time offset, e.g., http_requests_total offset 1m. Note: For range queries, original timestamps are not preserved) | Modified | |
[duration] (range time, e.g., http_requests_total[1m]) | ✓ | |
| Subquery | e.g., <instant_query>[<range>:<resolution>] | ❌ |
| Arithmetic Binary Ops | + (addition), - (subtraction), * (multiplication), / (division), % (modulo), ^ (exponentiation) | ✓ |
| Comparison Binary Ops | == (equal), != (not equal), > (greater than), < (less than), ≥ (greater/equal), ≤ (less/equal) | ✓ |
| Operation between two scalars | ❌ | |
bool keyword | ❌ | |
| Set Binary Ops | and, or, unless | ❌ |
| Vector Matching | group_left, group_right, on, ignoring | ❌ |
| Aggregation Operators | sum (calculate sum over dimensions) | ✓ |
min (select minimum over dimensions) | ✓ | |
max (select maximum over dimensions) | ✓ | |
avg (calculate average over dimensions) | ✓ | |
group (all values in the resulting vector are 1) | ✓ | |
stddev (calculate population standard deviation over dimensions) | ✓ | |
stdvar (calculate population standard variance over dimensions) | ✓ | |
count (count number of elements in the vector) | ✓ | |
count_values (count number of elements with the same value) | ✓ | |
bottomk (smallest k elements by sample value) | Modified | |
topk (largest k elements by sample value) | Modified | |
| Over Time Functions | avg_over_time(range-vector) | ✓ |
min_over_time(range-vector) | ✓ | |
max_over_time(range-vector) | ✓ | |
sum_over_time(range-vector) | ✓ | |
count_over_time(range-vector) | ✓ | |
quantile_over_time(scalar, range-vector) | ✓ | |
stddev_over_time(range-vector) | ✓ | |
stdvar_over_time(range-vector) | ✓ | |
last_over_time(range-vector) | ✓ | |
| Trigonometric Functions | acos(v instant-vector), acosh(v instant-vector), asin(v instant-vector), asinh(v instant-vector), | ✓ |
atan(v instant-vector), atanh(v instant-vector), cos(v instant-vector), cosh(v instant-vector), | ✓ | |
sin(v instant-vector), sinh(v instant-vector), tan(v instant-vector), tanh(v instant-vector) | ✓ | |
| Functions | abs(v instant-vector) | ✓ |
ceil(v instant-vector) | ✓ | |
changes(v range-vector) | ✓ | |
delta(v range-vector) | ✓ | |
deriv(v range-vector) | ✓ | |
exp(v instant-vector) | ✓ | |
floor(v instant-vector) | ✓ | |
holt_winters(v range-vector, sf scalar, tf scalar) | ✓ | |
idelta(v range-vector) | ✓ | |
increase(v range-vector) | ✓ | |
irate(v range-vector) | ✓ | |
ln(v instant-vector) | ✓ | |
log2(v instant-vector) | ✓ | |
log10(v instant-vector) | ✓ | |
predict_linear(v range-vector, t scalar) | ✓ | |
rate(v range-vector) | ✓ | |
resets(v range-vector) | ✓ | |
round(v instant-vector, to_nearest=1 scalar) | ✓ | |
scalar(v instant-vector) | ✓ | |
sgn(v instant-vector) | ✓ | |
sort(v instant-vector) | ✓ | |
sort_desc(v instant-vector) | ✓ | |
sqrt(v instant-vector) | ✓ | |
| Special Notes | 1. {job="localhosts"} (querying all metrics with job label) is not supported. A specific metric name must be specified in PromQL queries. | ❌ |
2. The @ modifier must be placed after the selector. | ✓ |
Known Issues & Explanations
-
Using the
@modifier in Range Queries- Issue: Using
@modifies the overall evaluation time (endTime). In Prometheus, the PromQL is executed at each step based on that@time. - Status: Behavior differs from native Prometheus.
- Issue: Using
-
Using the
offsetmodifier in Range Queries- Issue: Using
offsetshifts the overall evaluation time (endTime), which also causes the timestamps in the actual result values to be offset. In Prometheus, the PromQL is executed at each step based on the shifted time. - Status: Behavior differs from native Prometheus.
- Issue: Using
-
Range Vector Duration Exceeding Step in Range Queries
- Issue: In a range query involving a range vector (e.g.,
metric_name[1m]), the range duration ([1m]) must be less than or equal to the query step. If it is larger, the effective range duration is set equal to the step. - Status: Implemented limitation.
- Issue: In a range query involving a range vector (e.g.,
-
Subqueries and
@/offset- Issue: Using
offsetor@inside the instant query part of a subquery is not supported, as it can affect the overall evaluation time and lead to incorrect query time ranges. - Status: Not supported.
- Issue: Using
-
topkandbottomkFunctions- Issue: When these sorting functions are used with grouping (
by/without), the results may be inaccurate. The current implementation performs sorting on the entire result set after grouping, rather than sorting within each group. - Status: Implemented with limitation.
- Issue: When these sorting functions are used with grouping (