From 76b123721555e7d57ec374ba3980a34ce4ce821f Mon Sep 17 00:00:00 2001 From: Charles Korn Date: Fri, 17 May 2024 13:54:08 +1000 Subject: [PATCH] Document sorting behaviour Signed-off-by: Charles Korn --- docs/querying/api.md | 7 +++++++ docs/querying/functions.md | 4 ++++ 2 files changed, 11 insertions(+) diff --git a/docs/querying/api.md b/docs/querying/api.md index 46e79181e..71e01b3b9 100644 --- a/docs/querying/api.md +++ b/docs/querying/api.md @@ -473,6 +473,9 @@ Range vectors are returned as result type `matrix`. The corresponding Each series could have the `"values"` key, or the `"histograms"` key, or both. For a given timestamp, there will only be one sample of either float or histogram type. +Series are returned sorted by `metric`. Functions such as [`sort`](functions.md#sort) +and [`sort_by_label`](functions.md#sort_by_label) have no effect for range vectors. + ### Instant vectors Instant vectors are returned as result type `vector`. The corresponding @@ -491,6 +494,10 @@ Instant vectors are returned as result type `vector`. The corresponding Each series could have the `"value"` key, or the `"histogram"` key, but not both. +Series are not guaranteed to be returned in any particular order unless a function +such as [`sort`](functions.md#sort) or [`sort_by_label`](functions.md#sort_by_label)` +is used. + ### Scalars Scalar results are returned as result type `scalar`. The corresponding diff --git a/docs/querying/functions.md b/docs/querying/functions.md index c9e65fe6c..c8fda2865 100644 --- a/docs/querying/functions.md +++ b/docs/querying/functions.md @@ -596,10 +596,14 @@ have exactly one element, `scalar` will return `NaN`. `sort(v instant-vector)` returns vector elements sorted by their sample values, in ascending order. Native histograms are sorted by their sum of observations. +Please note that `sort` only affects the results of instant queries, as range query results always have a fixed output ordering. + ## `sort_desc()` Same as `sort`, but sorts in descending order. +Like `sort`, `sort_desc` only affects the results of instant queries, as range query results always have a fixed output ordering. + ## `sort_by_label()` **This function has to be enabled via the [feature flag](../feature_flags/) `--enable-feature=promql-experimental-functions`.**