From a27205a208ed5fe943b9fca77cf3242e572409ac Mon Sep 17 00:00:00 2001 From: Mayya Sharipova Date: Thu, 21 Aug 2025 16:21:15 -0400 Subject: [PATCH 01/12] Add documenation about script rescorer PR #74274 introduced a new rescorer based on script. This adds a documentation for this rescorer. --- .../rest-apis/filter-search-results.md | 123 ----------- .../rest-apis/rescore-search-results.md | 204 ++++++++++++++++++ 2 files changed, 204 insertions(+), 123 deletions(-) create mode 100644 docs/reference/elasticsearch/rest-apis/rescore-search-results.md diff --git a/docs/reference/elasticsearch/rest-apis/filter-search-results.md b/docs/reference/elasticsearch/rest-apis/filter-search-results.md index 5d5f32e9ee494..6bfa11f8cd0b1 100644 --- a/docs/reference/elasticsearch/rest-apis/filter-search-results.md +++ b/docs/reference/elasticsearch/rest-apis/filter-search-results.md @@ -12,10 +12,6 @@ You can use two methods to filter search results: * Use a boolean query with a `filter` clause. Search requests apply [boolean filters](/reference/query-languages/query-dsl/query-dsl-bool-query.md) to both search hits and [aggregations](/reference/aggregations/index.md). * Use the search API’s `post_filter` parameter. Search requests apply [post filters](#post-filter) only to search hits, not aggregations. You can use a post filter to calculate aggregations based on a broader result set, and then further narrow the results. - You can also [rescore](#rescore) hits after the post filter to improve relevance and reorder results. - - - ## Post filter [post-filter] When you use the `post_filter` parameter to filter search results, the search hits are filtered after the aggregations are calculated. A post filter has no impact on the aggregation results. @@ -125,122 +121,3 @@ GET /shirts/_search 2. The `colors` agg returns popular colors for shirts by Gucci. 3. The `color_red` agg limits the `models` sub-aggregation to **red** Gucci shirts. 4. Finally, the `post_filter` removes colors other than red from the search `hits`. - - - -## Rescore filtered search results [rescore] - -Rescoring can help to improve precision by reordering just the top (eg 100 - 500) documents returned by the [`query`](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search) and [`post_filter`](#post-filter) phases, using a secondary (usually more costly) algorithm, instead of applying the costly algorithm to all documents in the index. - -A `rescore` request is executed on each shard before it returns its results to be sorted by the node handling the overall search request. - -Currently the rescore API has only one implementation: the query rescorer, which uses a query to tweak the scoring. In the future, alternative rescorers may be made available, for example, a pair-wise rescorer. - -::::{note} -An error will be thrown if an explicit [`sort`](/reference/elasticsearch/rest-apis/sort-search-results.md) (other than `_score` in descending order) is provided with a `rescore` query. -:::: - - -::::{note} -when exposing pagination to your users, you should not change `window_size` as you step through each page (by passing different `from` values) since that can alter the top hits causing results to confusingly shift as the user steps through pages. -:::: - - - -### Query rescorer [query-rescorer] - -The query rescorer executes a second query only on the Top-K results returned by the [`query`](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search) and [`post_filter`](#post-filter) phases. The number of docs which will be examined on each shard can be controlled by the `window_size` parameter, which defaults to 10. - -By default the scores from the original query and the rescore query are combined linearly to produce the final `_score` for each document. The relative importance of the original query and of the rescore query can be controlled with the `query_weight` and `rescore_query_weight` respectively. Both default to `1`. - -For example: - -```console -POST /_search -{ - "query" : { - "match" : { - "message" : { - "operator" : "or", - "query" : "the quick brown" - } - } - }, - "rescore" : { - "window_size" : 50, - "query" : { - "rescore_query" : { - "match_phrase" : { - "message" : { - "query" : "the quick brown", - "slop" : 2 - } - } - }, - "query_weight" : 0.7, - "rescore_query_weight" : 1.2 - } - } -} -``` - -The way the scores are combined can be controlled with the `score_mode`: - -| Score Mode | Description | -| --- | --- | -| `total` | Add the original score and the rescore query score. The default. | -| `multiply` | Multiply the original score by the rescore query score. Usefulfor [`function query`](/reference/query-languages/query-dsl/query-dsl-function-score-query.md) rescores. | -| `avg` | Average the original score and the rescore query score. | -| `max` | Take the max of original score and the rescore query score. | -| `min` | Take the min of the original score and the rescore query score. | - - -### Multiple rescores [multiple-rescores] - -It is also possible to execute multiple rescores in sequence: - -```console -POST /_search -{ - "query" : { - "match" : { - "message" : { - "operator" : "or", - "query" : "the quick brown" - } - } - }, - "rescore" : [ { - "window_size" : 100, - "query" : { - "rescore_query" : { - "match_phrase" : { - "message" : { - "query" : "the quick brown", - "slop" : 2 - } - } - }, - "query_weight" : 0.7, - "rescore_query_weight" : 1.2 - } - }, { - "window_size" : 10, - "query" : { - "score_mode": "multiply", - "rescore_query" : { - "function_score" : { - "script_score": { - "script": { - "source": "Math.log10(doc.count.value + 2)" - } - } - } - } - } - } ] -} -``` - -The first one gets the results of the query then the second one gets the results of the first, etc. The second rescore will "see" the sorting done by the first rescore so it is possible to use a large window on the first rescore to pull documents into a smaller window for the second rescore. - diff --git a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md new file mode 100644 index 0000000000000..f2bf16dab0161 --- /dev/null +++ b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md @@ -0,0 +1,204 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/rescore-search-results.html +applies_to: + stack: all +--- + +# Rescore search results [rescore-search-results] + +Rescoring can help to improve precision by reordering just the top +(e.g. 100 - 500) documents returned by initial retrieval phase +(query, knn search) by using a secondary (usually more costly) algorithm, +instead of applying the costly algorithm to all documents in the index. + +A `rescore` request is executed on each shard before it returns its results +to be sorted by the node handling the overall search request. + +The rescore API has 3 options: + +1. `query` rescorer that executes a provided `rescore_query` on the top documents +2. `script` rescorer that uses a script to modify the scores of the top documents +3. `learning_to_rank` rescorer that uses an LTR model to re-rank the top documents + +All rescores have the `window_size` parameter that controls how many top +documents will be considered for rescoring. The default is 10. + +::::{note} +When implementing pagination, keep the `window_size` consistent across pages. +Changing it while advancing through results (by using different `from` values) +can cause the top hits to shift, leading to a confusing user experience. +:::: + +### Query Rescorer [query-rescorer] + +The query rescorer executes a second query only on the top documents returned +from the previous phase. The number of docs which is examined on each shard +can be controlled by the `window_size` parameter. + +By default, the scores from the original query and the rescore query are combined +linearly to produce the final `_score` for each document. +The relative importance of the original query and of the rescore query can be +controlled with the `query_weight` and `rescore_query_weight` respectively. +Both default to `1`. + +For example: + +```console +POST /_search +{ + "query" : { + "match" : { + "message" : { + "operator" : "or", + "query" : "the quick brown" + } + } + }, + "rescore" : { + "window_size" : 10, + "query" : { + "rescore_query" : { + "match_phrase" : { + "message" : { + "query" : "the quick brown", + "slop" : 2 + } + } + }, + "query_weight" : 0.7, + "rescore_query_weight" : 1.2 + } + } +} +``` + +::::{note} +An error will be thrown if an explicit [`sort`](/reference/elasticsearch/rest-apis/sort-search-results.md) +(other than `_score` in descending order) is provided with a `rescore` query. +:::: + + +The way the scores are combined can be controlled with the `score_mode`: + +| Score Mode | Description | +| --- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `total` | Add the original score and the rescore query score. The default. | +| `multiply` | Multiply the original score by the rescore query score. Useful for [`function query`](/reference/query-languages/query-dsl/query-dsl-function-score-query.md) rescores. | +| `avg` | Average the original score and the rescore query score. | +| `max` | Take the max of original score and the rescore query score. | +| `min` | Take the min of the original score and the rescore query score. | + +### Script rescorer [script-rescorer] + +`script` rescorer uses a script to rescore the top documents returned +from the previous phase. The script has access to the original score as well +as values of document fields. + +For example, the following script rescores documents based on the document's +original query score and the value of field `num_likes`: + +```console +POST /_search +{ + "query" : { + "match" : { + "message" : { + "operator" : "or", + "query" : "the quick brown" + } + } + }, + "rescore" : { + "window_size" : 10, + "script" : { + "script" : { + "source": "doc['num_likes'].value * params.multiplier + _score", + "parameters": { + "multiplier": 0.1 + } + } + } + } +} +``` + +### Learning to rank rescorer [learning-to-rank-rescorer] +`learning_to_rank` uses an LTR model to rescore the top documents. You must +provide the `model_id` of a deployed model, as well as any named parameters +required by the query templates for features used by the model. + +```console +GET my-index/_search +{ + "query": { <1> + "multi_match": { + "fields": ["title", "content"], + "query": "the quick brown fox" + } + }, + "rescore": { + "learning_to_rank": { + "model_id": "ltr-model", + "params": { + "query_text": "the quick brown fox" + } + }, + "window_size": 100 + } +} +``` + +### Multiple rescores [multiple-rescores] + +You can apply multiple rescoring operations in sequence. The first rescorer +works on the top documents from the initial retrieval phase, while the second +rescorer works on the output of the first rescorer, and so on. A common practice +is to use a larger window for the first rescorer and smaller windows for more +expensive subsequent rescorers. + +```console +POST /_search +{ + "query": { + "match": { + "message": { + "operator": "or", + "query": "the quick brown" + } + } + }, + "rescore": [ + { + "window_size": 10, + "query": { + "rescore_query": { + "match_phrase": { + "message": { + "query": "the quick brown", + "slop": 2 + } + } + }, + "query_weight": 0.7, + "rescore_query_weight": 1.2 + } + }, + { + "window_size": 5, + "query": { + "score_mode": "multiply", + "rescore_query": { + "function_score": { + "script_score": { + "script": { + "source": "Math.log10(doc.count.value + 2)" + } + } + } + } + } + } + ] +} +``` From 6f1535a7794191351591b58fe8aa8f04b1e0cdd8 Mon Sep 17 00:00:00 2001 From: Mayya Sharipova Date: Fri, 22 Aug 2025 12:56:03 -0400 Subject: [PATCH 02/12] Add applies to and redirect --- docs/redirects.yml | 9 ++++++++- .../elasticsearch/rest-apis/rescore-search-results.md | 6 +++--- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/redirects.yml b/docs/redirects.yml index 646937892e06a..b0f0ab8621c92 100644 --- a/docs/redirects.yml +++ b/docs/redirects.yml @@ -85,4 +85,11 @@ redirects: - to: 'reference/query-languages/esql/commands/stats-by.md' anchors: {'esql-stats-by'} - to: 'reference/query-languages/esql/commands/where.md' - anchors: {'esql-where'} \ No newline at end of file + anchors: {'esql-where'} + + # https://github.com/elastic/elasticsearch/pull/133359 + 'reference/elasticsearch/rest-apis/filter-search-results.md': + to: 'reference/elasticsearch/rest-apis/rescore-search-results.md' + anchors: + 'old-anchor': 'rescore' + 'removed-anchor': diff --git a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md index f2bf16dab0161..40701d5831210 100644 --- a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md +++ b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md @@ -1,10 +1,7 @@ --- mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/rescore-search-results.html -applies_to: - stack: all --- - # Rescore search results [rescore-search-results] Rescoring can help to improve precision by reordering just the top @@ -90,6 +87,9 @@ The way the scores are combined can be controlled with the `score_mode`: | `min` | Take the min of the original score and the rescore query score. | ### Script rescorer [script-rescorer] +```{applies_to} +stack: ga 9.2 +``` `script` rescorer uses a script to rescore the top documents returned from the previous phase. The script has access to the original score as well From ee7d806f160d8a1bc511645f127d1aa1aca7d84c Mon Sep 17 00:00:00 2001 From: Mayya Sharipova Date: Mon, 25 Aug 2025 09:21:48 -0400 Subject: [PATCH 03/12] Add applies to --- .../elasticsearch/rest-apis/rescore-search-results.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md index 40701d5831210..01966ac3f49aa 100644 --- a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md +++ b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md @@ -1,6 +1,9 @@ --- mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/rescore-search-results.html +applies_to: + stack: all + serverless: all --- # Rescore search results [rescore-search-results] From f7d408664b0fef8a1050a2e3818f6feb4ad5e0a7 Mon Sep 17 00:00:00 2001 From: Mayya Sharipova Date: Mon, 25 Aug 2025 12:51:34 -0400 Subject: [PATCH 04/12] Update docs/redirects.yml Co-authored-by: Liam Thompson --- docs/redirects.yml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/redirects.yml b/docs/redirects.yml index b0f0ab8621c92..a7e50dbb9ddb3 100644 --- a/docs/redirects.yml +++ b/docs/redirects.yml @@ -89,7 +89,9 @@ redirects: # https://github.com/elastic/elasticsearch/pull/133359 'reference/elasticsearch/rest-apis/filter-search-results.md': - to: 'reference/elasticsearch/rest-apis/rescore-search-results.md' - anchors: - 'old-anchor': 'rescore' - 'removed-anchor': + many: + - to: 'reference/elasticsearch/rest-apis/rescore-search-results.md' + anchors: + 'rescore': 'rescore-search-results' + 'query-rescorer': 'query-rescorer' + 'multiple-rescores': 'multiple-rescores' From f369595946e97287ec6e737d0edd407c71c38b64 Mon Sep 17 00:00:00 2001 From: Mayya Sharipova Date: Mon, 25 Aug 2025 14:59:10 -0400 Subject: [PATCH 05/12] Add document to toc --- docs/reference/elasticsearch/toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/elasticsearch/toc.yml b/docs/reference/elasticsearch/toc.yml index 9e534a54fa20a..0db2d2ccfb62f 100644 --- a/docs/reference/elasticsearch/toc.yml +++ b/docs/reference/elasticsearch/toc.yml @@ -86,6 +86,7 @@ toc: - file: rest-apis/collapse-search-results.md - file: rest-apis/create-index-from-source.md - file: rest-apis/filter-search-results.md + - file: rest-apis/rescore-search-results.md - file: rest-apis/find-text-structure-examples.md - file: rest-apis/highlighting.md - file: rest-apis/optimistic-concurrency-control.md From 6450d82732e3330710dfe8013c0561338545b61d Mon Sep 17 00:00:00 2001 From: Mayya Sharipova Date: Mon, 25 Aug 2025 15:17:15 -0400 Subject: [PATCH 06/12] Test to fix CI --- docs/redirects.yml | 2 +- .../reference/elasticsearch/rest-apis/rescore-search-results.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/redirects.yml b/docs/redirects.yml index a7e50dbb9ddb3..66354251a2e5c 100644 --- a/docs/redirects.yml +++ b/docs/redirects.yml @@ -92,6 +92,6 @@ redirects: many: - to: 'reference/elasticsearch/rest-apis/rescore-search-results.md' anchors: - 'rescore': 'rescore-search-results' + 'rescore': 'rescore-main' 'query-rescorer': 'query-rescorer' 'multiple-rescores': 'multiple-rescores' diff --git a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md index 01966ac3f49aa..b2714e013a4b4 100644 --- a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md +++ b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md @@ -5,7 +5,7 @@ applies_to: stack: all serverless: all --- -# Rescore search results [rescore-search-results] +# Rescore search results [rescore-main] Rescoring can help to improve precision by reordering just the top (e.g. 100 - 500) documents returned by initial retrieval phase From 646b8cd66fb64db3fc708e9579aa678905b6f5cf Mon Sep 17 00:00:00 2001 From: Mayya Sharipova Date: Mon, 25 Aug 2025 15:27:28 -0400 Subject: [PATCH 07/12] Make redirect simplier --- docs/redirects.yml | 10 +++------- .../elasticsearch/rest-apis/rescore-search-results.md | 2 +- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/redirects.yml b/docs/redirects.yml index 66354251a2e5c..0f3aa8ae74581 100644 --- a/docs/redirects.yml +++ b/docs/redirects.yml @@ -88,10 +88,6 @@ redirects: anchors: {'esql-where'} # https://github.com/elastic/elasticsearch/pull/133359 - 'reference/elasticsearch/rest-apis/filter-search-results.md': - many: - - to: 'reference/elasticsearch/rest-apis/rescore-search-results.md' - anchors: - 'rescore': 'rescore-main' - 'query-rescorer': 'query-rescorer' - 'multiple-rescores': 'multiple-rescores' + 'reference/elasticsearch/rest-apis/filter-search-results.md#rescore': 'reference/elasticsearch/rest-apis/rescore-search-results.md#rescore-main' + 'reference/elasticsearch/rest-apis/filter-search-results.md#query-rescorer': 'reference/elasticsearch/rest-apis/rescore-search-results.md#query-rescorer' + 'reference/elasticsearch/rest-apis/filter-search-results.md#multiple-rescores': 'reference/elasticsearch/rest-apis/rescore-search-results.md#multiple-rescores' diff --git a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md index b2714e013a4b4..07b23e3579cb4 100644 --- a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md +++ b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md @@ -204,4 +204,4 @@ POST /_search } ] } -``` +``` \ No newline at end of file From 7c42c4ce0d58fe2bbafacaef300d7bf226c89a0d Mon Sep 17 00:00:00 2001 From: Mayya Sharipova Date: Mon, 25 Aug 2025 15:30:52 -0400 Subject: [PATCH 08/12] Revert "Make redirect simplier" This reverts commit 646b8cd66fb64db3fc708e9579aa678905b6f5cf. --- docs/redirects.yml | 10 +++++++--- .../elasticsearch/rest-apis/rescore-search-results.md | 2 +- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/redirects.yml b/docs/redirects.yml index 0f3aa8ae74581..66354251a2e5c 100644 --- a/docs/redirects.yml +++ b/docs/redirects.yml @@ -88,6 +88,10 @@ redirects: anchors: {'esql-where'} # https://github.com/elastic/elasticsearch/pull/133359 - 'reference/elasticsearch/rest-apis/filter-search-results.md#rescore': 'reference/elasticsearch/rest-apis/rescore-search-results.md#rescore-main' - 'reference/elasticsearch/rest-apis/filter-search-results.md#query-rescorer': 'reference/elasticsearch/rest-apis/rescore-search-results.md#query-rescorer' - 'reference/elasticsearch/rest-apis/filter-search-results.md#multiple-rescores': 'reference/elasticsearch/rest-apis/rescore-search-results.md#multiple-rescores' + 'reference/elasticsearch/rest-apis/filter-search-results.md': + many: + - to: 'reference/elasticsearch/rest-apis/rescore-search-results.md' + anchors: + 'rescore': 'rescore-main' + 'query-rescorer': 'query-rescorer' + 'multiple-rescores': 'multiple-rescores' diff --git a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md index 07b23e3579cb4..b2714e013a4b4 100644 --- a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md +++ b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md @@ -204,4 +204,4 @@ POST /_search } ] } -``` \ No newline at end of file +``` From 376f8d2fb34162b20cbd51736bf9977c61a878d3 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 26 Aug 2025 09:54:41 +0200 Subject: [PATCH 09/12] pass-through unlisted anchors in the many ruleset for redirects --- docs/redirects.yml | 11 +++++++---- .../elasticsearch/rest-apis/rescore-search-results.md | 2 +- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/redirects.yml b/docs/redirects.yml index 66354251a2e5c..93546f93f0139 100644 --- a/docs/redirects.yml +++ b/docs/redirects.yml @@ -89,9 +89,12 @@ redirects: # https://github.com/elastic/elasticsearch/pull/133359 'reference/elasticsearch/rest-apis/filter-search-results.md': + to: 'reference/elasticsearch/rest-apis/filter-search-results.md' + anchors: {} # pass-through unlisted anchors in the `many` ruleset many: - to: 'reference/elasticsearch/rest-apis/rescore-search-results.md' - anchors: - 'rescore': 'rescore-main' - 'query-rescorer': 'query-rescorer' - 'multiple-rescores': 'multiple-rescores' + anchors: {'rescore'} + - to: 'reference/elasticsearch/rest-apis/rescore-search-results.md' + anchors: {'query-rescorer'} + - to: 'reference/elasticsearch/rest-apis/rescore-search-results.md' + anchors: {'multiple-rescores'} diff --git a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md index b2714e013a4b4..64e20059162c4 100644 --- a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md +++ b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md @@ -5,7 +5,7 @@ applies_to: stack: all serverless: all --- -# Rescore search results [rescore-main] +# Rescore search results [rescore] Rescoring can help to improve precision by reordering just the top (e.g. 100 - 500) documents returned by initial retrieval phase From faf8ee9f275f97df819fe7b61a04fa4dbb15a3ea Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 26 Aug 2025 10:14:47 +0200 Subject: [PATCH 10/12] try moving anchor, update heading levels --- .../rest-apis/rescore-search-results.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md index 64e20059162c4..e5d2080309e1b 100644 --- a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md +++ b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md @@ -5,13 +5,16 @@ applies_to: stack: all serverless: all --- -# Rescore search results [rescore] + +# Rescore search results Rescoring can help to improve precision by reordering just the top (e.g. 100 - 500) documents returned by initial retrieval phase (query, knn search) by using a secondary (usually more costly) algorithm, instead of applying the costly algorithm to all documents in the index. +## How `rescore` works [rescore] + A `rescore` request is executed on each shard before it returns its results to be sorted by the node handling the overall search request. @@ -30,7 +33,7 @@ Changing it while advancing through results (by using different `from` values) can cause the top hits to shift, leading to a confusing user experience. :::: -### Query Rescorer [query-rescorer] +## Query Rescorer [query-rescorer] The query rescorer executes a second query only on the top documents returned from the previous phase. The number of docs which is examined on each shard @@ -89,7 +92,7 @@ The way the scores are combined can be controlled with the `score_mode`: | `max` | Take the max of original score and the rescore query score. | | `min` | Take the min of the original score and the rescore query score. | -### Script rescorer [script-rescorer] +## Script rescorer [script-rescorer] ```{applies_to} stack: ga 9.2 ``` @@ -126,7 +129,7 @@ POST /_search } ``` -### Learning to rank rescorer [learning-to-rank-rescorer] +## Learning to rank rescorer [learning-to-rank-rescorer] `learning_to_rank` uses an LTR model to rescore the top documents. You must provide the `model_id` of a deployed model, as well as any named parameters required by the query templates for features used by the model. @@ -152,7 +155,7 @@ GET my-index/_search } ``` -### Multiple rescores [multiple-rescores] +## Multiple rescores [multiple-rescores] You can apply multiple rescoring operations in sequence. The first rescorer works on the top documents from the initial retrieval phase, while the second From 98203682e5ec3918fed83577c56681172f74fa59 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 26 Aug 2025 11:26:36 +0200 Subject: [PATCH 11/12] delete empty annotation --- .../elasticsearch/rest-apis/rescore-search-results.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md index e5d2080309e1b..6f253279cc199 100644 --- a/docs/reference/elasticsearch/rest-apis/rescore-search-results.md +++ b/docs/reference/elasticsearch/rest-apis/rescore-search-results.md @@ -130,6 +130,7 @@ POST /_search ``` ## Learning to rank rescorer [learning-to-rank-rescorer] + `learning_to_rank` uses an LTR model to rescore the top documents. You must provide the `model_id` of a deployed model, as well as any named parameters required by the query templates for features used by the model. @@ -137,7 +138,7 @@ required by the query templates for features used by the model. ```console GET my-index/_search { - "query": { <1> + "query": { "multi_match": { "fields": ["title", "content"], "query": "the quick brown fox" From b33aeff435ffefa1897c1a74c5a998ed53aaca95 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 26 Aug 2025 11:29:05 +0200 Subject: [PATCH 12/12] just find/replace --- .../search-aggregations-metrics-top-hits-aggregation.md | 2 +- .../elasticsearch/rest-apis/collapse-search-results.md | 4 ++-- .../elasticsearch/rest-apis/reciprocal-rank-fusion.md | 2 +- docs/reference/elasticsearch/rest-apis/retrievers.md | 4 ++-- .../elasticsearch/rest-apis/retrievers/rescorer-retriever.md | 4 ++-- .../query-dsl/query-dsl-sparse-vector-query.md | 2 +- .../query-dsl/query-dsl-text-expansion-query.md | 2 +- .../query-dsl/query-dsl-weighted-tokens-query.md | 2 +- 8 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/reference/aggregations/search-aggregations-metrics-top-hits-aggregation.md b/docs/reference/aggregations/search-aggregations-metrics-top-hits-aggregation.md index 05ff8160a122d..741ffd3fdae7c 100644 --- a/docs/reference/aggregations/search-aggregations-metrics-top-hits-aggregation.md +++ b/docs/reference/aggregations/search-aggregations-metrics-top-hits-aggregation.md @@ -43,7 +43,7 @@ If you **only** need `docvalue_fields`, `size`, and `sort` then [Top metrics](/r :::: -`top_hits` does not support the [`rescore`](/reference/elasticsearch/rest-apis/filter-search-results.md#rescore) parameter. Query rescoring applies only to search hits, not aggregation results. To change the scores used by aggregations, use a [`function_score`](/reference/query-languages/query-dsl/query-dsl-function-score-query.md) or [`script_score`](/reference/query-languages/query-dsl/query-dsl-script-score-query.md) query. +`top_hits` does not support the [`rescore`](/reference/elasticsearch/rest-apis/rescore-search-results.md#rescore) parameter. Query rescoring applies only to search hits, not aggregation results. To change the scores used by aggregations, use a [`function_score`](/reference/query-languages/query-dsl/query-dsl-function-score-query.md) or [`script_score`](/reference/query-languages/query-dsl/query-dsl-script-score-query.md) query. ## Example [_example_6] diff --git a/docs/reference/elasticsearch/rest-apis/collapse-search-results.md b/docs/reference/elasticsearch/rest-apis/collapse-search-results.md index a1939da075e2f..c238daa0b80a6 100644 --- a/docs/reference/elasticsearch/rest-apis/collapse-search-results.md +++ b/docs/reference/elasticsearch/rest-apis/collapse-search-results.md @@ -173,7 +173,7 @@ GET /my-index-000001/_search ## Rescore collapse results [rescore-collapse-results] -You can use field collapsing alongside the [`rescore`](/reference/elasticsearch/rest-apis/filter-search-results.md#rescore) search parameter. Rescorers run on every shard for the top-ranked document per collapsed field. To maintain a reliable order, it is recommended to cluster documents sharing the same collapse field value on one shard. This is achieved by assigning the collapse field value as the [routing key](/reference/elasticsearch/rest-apis/search-shard-routing.md#search-routing) during indexing: +You can use field collapsing alongside the [`rescore`](/reference/elasticsearch/rest-apis/rescore-search-results.md#rescore) search parameter. Rescorers run on every shard for the top-ranked document per collapsed field. To maintain a reliable order, it is recommended to cluster documents sharing the same collapse field value on one shard. This is achieved by assigning the collapse field value as the [routing key](/reference/elasticsearch/rest-apis/search-shard-routing.md#search-routing) during indexing: ```console POST /my-index-000001/_doc?routing=xyz <1> @@ -189,7 +189,7 @@ POST /my-index-000001/_doc?routing=xyz <1> By doing this, you guarantee that only one top document per collapse key gets rescored globally. -The following request utilizes field collapsing on the `user.id` field and then rescores the top groups with a [query rescorer](/reference/elasticsearch/rest-apis/filter-search-results.md#query-rescorer): +The following request utilizes field collapsing on the `user.id` field and then rescores the top groups with a [query rescorer](/reference/elasticsearch/rest-apis/rescore-search-results.md#query-rescorer): ```console GET /my-index-000001/_search diff --git a/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion.md b/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion.md index c640929584bb7..6e22e2504bb68 100644 --- a/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion.md +++ b/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion.md @@ -114,7 +114,7 @@ The `rrf` retriever does not currently support: * [scroll](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search#search-api-scroll-query-param) * [sort](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search#search-sort-param) -* [rescore](/reference/elasticsearch/rest-apis/filter-search-results.md#rescore) +* [rescore](/reference/elasticsearch/rest-apis/rescore-search-results.md#rescore) Using unsupported features as part of a search with an `rrf` retriever results in an exception. diff --git a/docs/reference/elasticsearch/rest-apis/retrievers.md b/docs/reference/elasticsearch/rest-apis/retrievers.md index a076d34941c09..8654a5407ba0b 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers.md @@ -27,7 +27,7 @@ The following retrievers are available: : The [pinned](retrievers/pinned-retriever.md) retriever always places specified documents at the top of the results, with the remaining hits provided by a secondary retriever. `rescorer` -: The [rescorer](retrievers/rescorer-retriever.md) retriever replaces the functionality of the [query rescorer](/reference/elasticsearch/rest-apis/filter-search-results.md#rescore). +: The [rescorer](retrievers/rescorer-retriever.md) retriever replaces the functionality of the [query rescorer](/reference/elasticsearch/rest-apis/rescore-search-results.md#rescore). `rrf` : The [rrf](retrievers/rrf-retriever.md) retriever produces top documents from [reciprocal rank fusion (RRF)](/reference/elasticsearch/rest-apis/reciprocal-rank-fusion.md). @@ -63,7 +63,7 @@ When a retriever is specified as part of a search, the following elements are no * [`search_after`](/reference/elasticsearch/rest-apis/paginate-search-results.md#search-after) * [`terminate_after`](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search#request-body-search-terminate-after) * [`sort`](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search#search-sort-param) -* [`rescore`](/reference/elasticsearch/rest-apis/filter-search-results.md#rescore) use a [rescorer retriever](retrievers/rescorer-retriever.md) instead +* [`rescore`](/reference/elasticsearch/rest-apis/rescore-search-results.md#rescore) use a [rescorer retriever](retrievers/rescorer-retriever.md) instead ## Multi-field query format [multi-field-query-format] diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/rescorer-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/rescorer-retriever.md index b9f12e6dce795..3770fd2121678 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/rescorer-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/rescorer-retriever.md @@ -24,9 +24,9 @@ When using the `rescorer`, an error is returned if the following conditions are ## Parameters [rescorer-retriever-parameters] `rescore` -: (Required. [A rescorer definition or an array of rescorer definitions](/reference/elasticsearch/rest-apis/filter-search-results.md#rescore)) +: (Required. [A rescorer definition or an array of rescorer definitions](/reference/elasticsearch/rest-apis/rescore-search-results.md#rescore)) - Defines the [rescorers](/reference/elasticsearch/rest-apis/filter-search-results.md#rescore) applied sequentially to the top documents returned by the child retriever. + Defines the [rescorers](/reference/elasticsearch/rest-apis/rescore-search-results.md#rescore) applied sequentially to the top documents returned by the child retriever. `retriever` diff --git a/docs/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md b/docs/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md index 7274da6058fe4..cdc2613a3aa24 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md @@ -208,7 +208,7 @@ GET my-index/_search The following is an extension to the above example that adds a pruning configuration to the `sparse_vector` query. The pruning configuration identifies non-significant tokens to prune from the query in order to improve query performance. -Token pruning happens at the shard level. While this should result in the same tokens being labeled as insignificant across shards, this is not guaranteed based on the composition of each shard. Therefore, if you are running `sparse_vector` with a `pruning_config` on a multi-shard index, we strongly recommend adding a [Rescore filtered search results](/reference/elasticsearch/rest-apis/filter-search-results.md#rescore) function with the tokens that were originally pruned from the query. This will help mitigate any shard-level inconsistency with pruned tokens and provide better relevance overall. +Token pruning happens at the shard level. While this should result in the same tokens being labeled as insignificant across shards, this is not guaranteed based on the composition of each shard. Therefore, if you are running `sparse_vector` with a `pruning_config` on a multi-shard index, we strongly recommend adding a [Rescore filtered search results](/reference/elasticsearch/rest-apis/rescore-search-results.md#rescore) function with the tokens that were originally pruned from the query. This will help mitigate any shard-level inconsistency with pruned tokens and provide better relevance overall. ```console GET my-index/_search diff --git a/docs/reference/query-languages/query-dsl/query-dsl-text-expansion-query.md b/docs/reference/query-languages/query-dsl/query-dsl-text-expansion-query.md index 7c81e300a5abb..9e0a9bfcaaf77 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-text-expansion-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-text-expansion-query.md @@ -192,7 +192,7 @@ GET my-index/_search The following is an extension to the above example that adds a [preview] pruning configuration to the `text_expansion` query. The pruning configuration identifies non-significant tokens to prune from the query in order to improve query performance. -Token pruning happens at the shard level. While this should result in the same tokens being labeled as insignificant across shards, this is not guaranteed based on the composition of each shard. Therefore, if you are running `text_expansion` with a `pruning_config` on a multi-shard index, we strongly recommend adding a [Rescore filtered search results](/reference/elasticsearch/rest-apis/filter-search-results.md#rescore) function with the tokens that were originally pruned from the query. This will help mitigate any shard-level inconsistency with pruned tokens and provide better relevance overall. +Token pruning happens at the shard level. While this should result in the same tokens being labeled as insignificant across shards, this is not guaranteed based on the composition of each shard. Therefore, if you are running `text_expansion` with a `pruning_config` on a multi-shard index, we strongly recommend adding a [Rescore filtered search results](/reference/elasticsearch/rest-apis/rescore-search-results.md#rescore) function with the tokens that were originally pruned from the query. This will help mitigate any shard-level inconsistency with pruned tokens and provide better relevance overall. ```console GET my-index/_search diff --git a/docs/reference/query-languages/query-dsl/query-dsl-weighted-tokens-query.md b/docs/reference/query-languages/query-dsl/query-dsl-weighted-tokens-query.md index c04a4c19f8192..3db7b2922f335 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-weighted-tokens-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-weighted-tokens-query.md @@ -75,7 +75,7 @@ POST _search The following example adds a pruning configuration to the `text_expansion` query. The pruning configuration identifies non-significant tokens to prune from the query in order to improve query performance. -Token pruning happens at the shard level. While this should result in the same tokens being labeled as insignificant across shards, this is not guaranteed based on the composition of each shard. Therefore, if you are running `text_expansion` with a `pruning_config` on a multi-shard index, we strongly recommend adding a [Rescore filtered search results](/reference/elasticsearch/rest-apis/filter-search-results.md#rescore) function with the tokens that were originally pruned from the query. This will help mitigate any shard-level inconsistency with pruned tokens and provide better relevance overall. +Token pruning happens at the shard level. While this should result in the same tokens being labeled as insignificant across shards, this is not guaranteed based on the composition of each shard. Therefore, if you are running `text_expansion` with a `pruning_config` on a multi-shard index, we strongly recommend adding a [Rescore filtered search results](/reference/elasticsearch/rest-apis/rescore-search-results.md#rescore) function with the tokens that were originally pruned from the query. This will help mitigate any shard-level inconsistency with pruned tokens and provide better relevance overall. ```console GET my-index/_search