From 2cfd402b3a0c092a22fedd92cbf942dd0c51ea48 Mon Sep 17 00:00:00 2001 From: Charles Korn Date: Tue, 11 Feb 2025 14:55:39 +1100 Subject: [PATCH] Clarify sorting behaviour of `topk` and `bottomk`. Signed-off-by: Charles Korn --- docs/querying/operators.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/querying/operators.md b/docs/querying/operators.md index df65a4335f..7242049784 100644 --- a/docs/querying/operators.md +++ b/docs/querying/operators.md @@ -319,7 +319,14 @@ the input samples, including the original labels, are returned in the result vector. `by` and `without` are only used to bucket the input vector. Similar to `min` and `max`, they only operate on float samples, considering `NaN` values to be farthest from the top or bottom, respectively. Histogram samples in the -input vector are ignored, flagged by an info-level annotation. +input vector are ignored, flagged by an info-level annotation. + +If used in an instant query, `topk` and `bottomk` return series ordered by +value in descending or ascending order, respectively. If used with `by` or +`without`, then series within each bucket are sorted by value, and series in +the same bucket are returned consecutively, but there is no guarantee that +buckets of series will be returned in any particular order. No sorting applies +to range queries. `limitk` and `limit_ratio` also return a subset of the input samples, including the original labels in the result vector. The subset is selected in a