From 73323478337d74cd6ead7fbb6a8ad4759f73bf85 Mon Sep 17 00:00:00 2001
From: Remi Dettai <rdettai@gmail.com>
Date: Wed, 16 Jul 2025 16:29:13 +0200
Subject: [PATCH] Document sort order on search api

---
 docs/reference/rest-api.md                    | 25 ++++---
 .../sort_orders/0002-sort-searchapi.yaml      | 68 +++++++++++++++++++
 2 files changed, 83 insertions(+), 10 deletions(-)
 create mode 100644 quickwit/rest-api-tests/scenarii/sort_orders/0002-sort-searchapi.yaml

diff --git a/docs/reference/rest-api.md b/docs/reference/rest-api.md
index 5047afd6308..c491388ae65 100644
--- a/docs/reference/rest-api.md
+++ b/docs/reference/rest-api.md
@@ -60,16 +60,21 @@ POST api/v1/<index id>/search
 
 | Variable            | Type       | Description     | Default value   |
 |---------------------|------------|-----------------|-----------------|
-| `query`           | `String`   | Query text. See the [query language doc](query-language.md) | _required_ |
-| `start_timestamp` | `i64`      | If set, restrict search to documents with a `timestamp >= start_timestamp`, taking advantage of potential time pruning opportunities. The value must be in seconds. | |
-| `end_timestamp`   | `i64`      | If set, restrict search to documents with a `timestamp < end_timestamp`, taking advantage of potential time pruning opportunities. The value must be in seconds.    | |
-| `start_offset`    | `Integer`  | Number of documents to skip | `0` |
-| `max_hits`        | `Integer`  | Maximum number of hits to return (by default 20) | `20` |
-| `search_field`    | `[String]` | Fields to search on if no field name is specified in the query. Comma-separated list, e.g. "field1,field2"  | index_config.search_settings.default_search_fields |
-| `snippet_fields`  | `[String]` | Fields to extract snippet on. Comma-separated list, e.g. "field1,field2"  | |
-| `sort_by`         | `[String]` | Fields to sort the query results on. You can sort by one or two fast fields or by BM25 `_score` (requires fieldnorms). By default, hits are sorted in reverse order of their [document ID](/docs/overview/concepts/querying.md#document-id) (to show recent events first). | |
-| `format`          | `Enum`     | The output format. Allowed values are "json" or "pretty_json" | `pretty_json` |
-| `aggs`            | `JSON`     | The aggregations request. See the [aggregations doc](aggregation.md) for supported aggregations. | |
+| `query`           | `String`     | Query text. See the [query language doc](query-language.md) | _required_ |
+| `start_timestamp` | `i64`        | If set, restrict search to documents with a `timestamp >= start_timestamp`, taking advantage of potential time pruning opportunities. The value must be in seconds. | |
+| `end_timestamp`   | `i64`        | If set, restrict search to documents with a `timestamp < end_timestamp`, taking advantage of potential time pruning opportunities. The value must be in seconds.    | |
+| `start_offset`    | `Integer`.   | Number of documents to skip | `0` |
+| `max_hits`        | `Integer`    | Maximum number of hits to return (by default 20) | `20` |
+| `search_field`    | `[String]`\* | Fields to search on if no field name is specified in the query. | index_config.search_settings.default_search_fields |
+| `snippet_fields`  | `[String]`\* | Fields to extract snippet on. | |
+| `sort_by`         | `[String]`\* | Fields to sort the query results on. You can sort by one or two fast fields or by BM25 `_score` (requires fieldnorms). By default, fields are sorted in descending order, to sort by ascending order prepend `-` (e.g "-field1"). If no field is specified, hits are sorted in reverse order of their [document ID](/docs/overview/concepts/querying.md#document-id) (to show recent events first). | |
+| `format`          | `Enum`       | The output format. Allowed values are "json" or "pretty_json" | `pretty_json` |
+| `aggs`            | `JSON`       | The aggregations request. See the [aggregations doc](aggregation.md) for supported aggregations. | |
+
+
+
+\* Field lists of type `[String]` (`search_field`, `snippet_field` and `sort_by`) are comma-separated lists, e.g "field1,field2".
+
 
 :::info
 The `start_timestamp` and `end_timestamp` should be specified in seconds regardless of the timestamp field precision.
diff --git a/quickwit/rest-api-tests/scenarii/sort_orders/0002-sort-searchapi.yaml b/quickwit/rest-api-tests/scenarii/sort_orders/0002-sort-searchapi.yaml
new file mode 100644
index 00000000000..5bcce74d034
--- /dev/null
+++ b/quickwit/rest-api-tests/scenarii/sort_orders/0002-sort-searchapi.yaml
@@ -0,0 +1,68 @@
+method: [GET]
+engines:
+  - quickwit
+endpoint: sortorder/search
+params:
+  query: "*"
+  sort_by: "id"
+expected:
+  hits:
+    - {"id": 5}
+    - {"id": 4}
+    - {"id": 3}
+    - {"id": 2}
+    - {"id": 2}
+    - {"id": 1}
+    - {"id": 0}
+---
+method: [GET]
+engines:
+  - quickwit
+endpoint: sortorder/search
+params:
+  query: "*"
+  sort_by: "-id"
+expected:
+  hits:
+    - {"id": 0}
+    - {"id": 1}
+    - {"id": 2}
+    - {"id": 2}
+    - {"id": 3}
+    - {"id": 4}
+    - {"id": 5}
+---
+method: [GET]
+engines:
+  - quickwit
+endpoint: sortorder/search
+params:
+  query: "*"
+  sort_by: "-id,-count"
+expected:
+  hits:
+    - {"count": 10, "id": 0}
+    - {"count": 10, "id": 1}
+    - {"count": 10, "id": 2}
+    - {"count": 15, "id": 2}
+    - {"id": 3}
+    - {"count": -2.5, "id": 4}
+    - {"id": 5}
+---
+method: [POST]
+engines:
+  - quickwit
+endpoint: sortorder/search
+json:
+  query: "*"
+  sort_by: "-id,-count"
+expected:
+  hits:
+    - {"count": 10, "id": 0}
+    - {"count": 10, "id": 1}
+    - {"count": 10, "id": 2}
+    - {"count": 15, "id": 2}
+    - {"id": 3}
+    - {"count": -2.5, "id": 4}
+    - {"id": 5}
+---