From b33a60151c430229f2b9a3b02a18d21ef9fd63c1 Mon Sep 17 00:00:00 2001 From: Mridula Date: Fri, 5 Sep 2025 12:51:26 +0100 Subject: [PATCH 1/9] Improved changes to the doc --- .../rest-apis/retrievers/linear-retriever.md | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md index dd266b0092d6c..c817e7d33e915 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md @@ -28,7 +28,7 @@ Combining `query` and `retrievers` is not supported. Fields can include boost values using the `^` notation (e.g., `"field^2"`). If not specified, uses the index's default fields from the `index.query.default_field` index setting, which is `*` by default. -`normalizer` {applies_to}`stack: ga 9.1` +`normalizer` {applies_to}`stack: ga 9.2` : (Optional, String) The top-level normalizer to use when combining results. @@ -38,14 +38,6 @@ Combining `query` and `retrievers` is not supported. When used with the [multi-field query format](../retrievers.md#multi-field-query-format) (`query` parameter), normalizes scores per [field grouping](../retrievers.md#multi-field-field-grouping). Otherwise serves as the default normalizer for any sub-retriever that doesn't specify its own normalizer. Per-retriever normalizers always take precedence over the top-level normalizer. - :::{note} - **Top-level normalizer support for sub-retrievers**: The ability to use a top-level normalizer as a default for sub-retrievers was introduced in Elasticsearch 9.2+. In earlier versions, only per-retriever normalizers are supported. - ::: - - ::::{warning} - Avoid using `none` as that will disable normalization and may bias the result set towards lexical matches. - See [field grouping](../retrievers.md#multi-field-field-grouping) for more information. - :::: `retrievers` : (Optional, array of objects) @@ -83,8 +75,7 @@ Each entry in the `retrievers` array specifies the following parameters: Specifies how the retriever's score will be normalized before applying the specified `weight`. See [normalizers](#linear-retriever-normalizers) for supported values. - If not specified, uses the top-level `normalizer` or defaults to `none` if no top-level normalizer is set. - {applies_to}`stack: ga 9.2` + If not specified, uses the top-level `normalizer` (9.2+) or defaults to `none` (earlier versions). See also [this hybrid search example](retrievers-examples.md#retrievers-examples-linear-retriever) using a linear retriever on how to independently configure and apply normalizers to retrievers. From 1bd1d5b4fa02751dbc29532be0f55c6d387dc37d Mon Sep 17 00:00:00 2001 From: Mridula Date: Fri, 5 Sep 2025 12:52:53 +0100 Subject: [PATCH 2/9] Add back missing warning about avoiding 'none' normalizer with field grouping --- .../elasticsearch/rest-apis/retrievers/linear-retriever.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md index c817e7d33e915..aec5b20c72cd8 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md @@ -38,6 +38,10 @@ Combining `query` and `retrievers` is not supported. When used with the [multi-field query format](../retrievers.md#multi-field-query-format) (`query` parameter), normalizes scores per [field grouping](../retrievers.md#multi-field-field-grouping). Otherwise serves as the default normalizer for any sub-retriever that doesn't specify its own normalizer. Per-retriever normalizers always take precedence over the top-level normalizer. + ::::{warning} + Avoid using `none` as that will disable normalization and may bias the result set towards lexical matches. + See [field grouping](../retrievers.md#multi-field-field-grouping) for more information. + :::: `retrievers` : (Optional, array of objects) From 65ee6874326204597cde368e88d2d1035e7e5c99 Mon Sep 17 00:00:00 2001 From: Mridula Date: Fri, 5 Sep 2025 13:00:43 +0100 Subject: [PATCH 3/9] Move applies_to tag to specific behavior description to clarify version support --- .../elasticsearch/rest-apis/retrievers/linear-retriever.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md index aec5b20c72cd8..b0d7a05299b66 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md @@ -28,7 +28,7 @@ Combining `query` and `retrievers` is not supported. Fields can include boost values using the `^` notation (e.g., `"field^2"`). If not specified, uses the index's default fields from the `index.query.default_field` index setting, which is `*` by default. -`normalizer` {applies_to}`stack: ga 9.2` +`normalizer` {applies_to}`stack: ga 9.1` : (Optional, String) The top-level normalizer to use when combining results. @@ -36,13 +36,12 @@ Combining `query` and `retrievers` is not supported. Required when `query` is specified. When used with the [multi-field query format](../retrievers.md#multi-field-query-format) (`query` parameter), normalizes scores per [field grouping](../retrievers.md#multi-field-field-grouping). - Otherwise serves as the default normalizer for any sub-retriever that doesn't specify its own normalizer. Per-retriever normalizers always take precedence over the top-level normalizer. + Otherwise serves as the default normalizer for any sub-retriever that doesn't specify its own normalizer. Per-retriever normalizers always take precedence over the top-level normalizer. {applies_to}`stack: ga 9.2` ::::{warning} Avoid using `none` as that will disable normalization and may bias the result set towards lexical matches. See [field grouping](../retrievers.md#multi-field-field-grouping) for more information. :::: - `retrievers` : (Optional, array of objects) @@ -74,7 +73,7 @@ Each entry in the `retrievers` array specifies the following parameters: The weight that each score of this retriever’s top docs will be multiplied with. Must be greater or equal to 0. Defaults to 1.0. -`normalizer` +`normalizer` {applies_to}`stack: ga 9.1` : (Optional, String) Specifies how the retriever's score will be normalized before applying the specified `weight`. From d44c3fd81c9f859715a9f634cb86509539513155 Mon Sep 17 00:00:00 2001 From: Mridula Date: Fri, 5 Sep 2025 13:05:43 +0100 Subject: [PATCH 4/9] cleaning it up --- .../elasticsearch/rest-apis/retrievers/linear-retriever.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md index b0d7a05299b66..4cb986e32f4ad 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md @@ -36,12 +36,13 @@ Combining `query` and `retrievers` is not supported. Required when `query` is specified. When used with the [multi-field query format](../retrievers.md#multi-field-query-format) (`query` parameter), normalizes scores per [field grouping](../retrievers.md#multi-field-field-grouping). - Otherwise serves as the default normalizer for any sub-retriever that doesn't specify its own normalizer. Per-retriever normalizers always take precedence over the top-level normalizer. {applies_to}`stack: ga 9.2` + Otherwise serves as the default normalizer for any sub-retriever that doesn't specify its own normalizer. Per-retriever normalizers always take precedence over the top-level normalizer. ::::{warning} Avoid using `none` as that will disable normalization and may bias the result set towards lexical matches. See [field grouping](../retrievers.md#multi-field-field-grouping) for more information. :::: + `retrievers` : (Optional, array of objects) @@ -73,7 +74,7 @@ Each entry in the `retrievers` array specifies the following parameters: The weight that each score of this retriever’s top docs will be multiplied with. Must be greater or equal to 0. Defaults to 1.0. -`normalizer` {applies_to}`stack: ga 9.1` +`normalizer` : (Optional, String) Specifies how the retriever's score will be normalized before applying the specified `weight`. From 7cb08aee04ac56d9998e816cdcef6f321497bc6c Mon Sep 17 00:00:00 2001 From: Mridula Date: Fri, 5 Sep 2025 13:30:48 +0100 Subject: [PATCH 5/9] cleaned up --- .../elasticsearch/rest-apis/retrievers/linear-retriever.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md index 4cb986e32f4ad..9790c83e19837 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md @@ -28,7 +28,7 @@ Combining `query` and `retrievers` is not supported. Fields can include boost values using the `^` notation (e.g., `"field^2"`). If not specified, uses the index's default fields from the `index.query.default_field` index setting, which is `*` by default. -`normalizer` {applies_to}`stack: ga 9.1` +`normalizer` : (Optional, String) The top-level normalizer to use when combining results. From 8e24b5cb617047d7f6e49a8ea2155c293af533ca Mon Sep 17 00:00:00 2001 From: Mridula Date: Fri, 5 Sep 2025 13:31:26 +0100 Subject: [PATCH 6/9] cleaned up --- .../elasticsearch/rest-apis/retrievers/linear-retriever.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md index 9790c83e19837..aec5b20c72cd8 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md @@ -28,7 +28,7 @@ Combining `query` and `retrievers` is not supported. Fields can include boost values using the `^` notation (e.g., `"field^2"`). If not specified, uses the index's default fields from the `index.query.default_field` index setting, which is `*` by default. -`normalizer` +`normalizer` {applies_to}`stack: ga 9.2` : (Optional, String) The top-level normalizer to use when combining results. From a34eca960028cdfbb07f59b049c866a51cbc22d9 Mon Sep 17 00:00:00 2001 From: Mridula Date: Fri, 5 Sep 2025 14:56:48 +0100 Subject: [PATCH 7/9] Update linear-retriever.md --- .../elasticsearch/rest-apis/retrievers/linear-retriever.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md index aec5b20c72cd8..88442b5779f4b 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md @@ -28,7 +28,7 @@ Combining `query` and `retrievers` is not supported. Fields can include boost values using the `^` notation (e.g., `"field^2"`). If not specified, uses the index's default fields from the `index.query.default_field` index setting, which is `*` by default. -`normalizer` {applies_to}`stack: ga 9.2` +`normalizer` {applies_to}`stack: ga 9.1` : (Optional, String) The top-level normalizer to use when combining results. @@ -37,6 +37,7 @@ Combining `query` and `retrievers` is not supported. When used with the [multi-field query format](../retrievers.md#multi-field-query-format) (`query` parameter), normalizes scores per [field grouping](../retrievers.md#multi-field-field-grouping). Otherwise serves as the default normalizer for any sub-retriever that doesn't specify its own normalizer. Per-retriever normalizers always take precedence over the top-level normalizer. + {applies_to}`stack: ga 9.2` ::::{warning} Avoid using `none` as that will disable normalization and may bias the result set towards lexical matches. From 6e3162c0af9e0a7a575f09914ff44a0c44b18c4c Mon Sep 17 00:00:00 2001 From: Mridula Date: Mon, 15 Sep 2025 15:26:46 +0100 Subject: [PATCH 8/9] Update docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md Co-authored-by: Liam Thompson --- .../elasticsearch/rest-apis/retrievers/linear-retriever.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md index 88442b5779f4b..f16a86ebe9bd7 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md @@ -36,7 +36,8 @@ Combining `query` and `retrievers` is not supported. Required when `query` is specified. When used with the [multi-field query format](../retrievers.md#multi-field-query-format) (`query` parameter), normalizes scores per [field grouping](../retrievers.md#multi-field-field-grouping). - Otherwise serves as the default normalizer for any sub-retriever that doesn't specify its own normalizer. Per-retriever normalizers always take precedence over the top-level normalizer. + + Otherwise this serves as the default normalizer for any sub-retriever that doesn't specify its own normalizer. Per-retriever normalizers always take precedence over the top-level normalizer. {applies_to}`stack: ga 9.2` {applies_to}`stack: ga 9.2` ::::{warning} From eb2b6de521c45d0a0a8a69040c9c8636fc3a014e Mon Sep 17 00:00:00 2001 From: Mridula Date: Mon, 15 Sep 2025 15:27:07 +0100 Subject: [PATCH 9/9] Update docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md Co-authored-by: Liam Thompson --- .../elasticsearch/rest-apis/retrievers/linear-retriever.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md index f16a86ebe9bd7..cd62423e196f8 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md @@ -38,7 +38,6 @@ Combining `query` and `retrievers` is not supported. When used with the [multi-field query format](../retrievers.md#multi-field-query-format) (`query` parameter), normalizes scores per [field grouping](../retrievers.md#multi-field-field-grouping). Otherwise this serves as the default normalizer for any sub-retriever that doesn't specify its own normalizer. Per-retriever normalizers always take precedence over the top-level normalizer. {applies_to}`stack: ga 9.2` - {applies_to}`stack: ga 9.2` ::::{warning} Avoid using `none` as that will disable normalization and may bias the result set towards lexical matches.