Worked on Michael comments

Author: mridula-s109

docs/reference/elasticsearch/rest-apis/retrievers/linear-retriever.md

@@ -31,11 +31,12 @@ Combining `query` and `retrievers` is not supported.
 `normalizer` {applies_to}`stack: ga 9.1`
 :   (Optional, String)
 
-    The normalizer to use when using the [multi-field query format](../retrievers.md#multi-field-query-format).
+    The normalizer to use when combining results.
     See [normalizers](#linear-retriever-normalizers) for supported values.
     Required when `query` is specified.
-
-    When used with `retrievers`, the top-level `normalizer` serves as a default for any sub-retriever that doesn't specify its own normalizer. Per-retriever normalizers always take precedence over the top-level normalizer when both are 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).
+    When used with `retrievers`, 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.
@@ -76,9 +77,9 @@ Each entry in the `retrievers` array specifies the following parameters:
 `normalizer`
 :   (Optional, String)
 
-    Specifies how the retriever’s score will be normalized before applying the specified `weight`.
+    Specifies how the retriever's score will be normalized before applying the specified `weight`.
     See [normalizers](#linear-retriever-normalizers) for supported values.
-    Defaults to `none`.
+    If not specified, uses the top-level `normalizer` or defaults to `none` if no top-level normalizer is set.
 
 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.
 
@@ -96,7 +97,7 @@ The `linear` retriever supports the following normalizers:
 
 ## Example
 
-This example of a hybrid search weights KNN results five times more heavily than BM25 results in the final ranking.
+This example of a hybrid search weights KNN results five times more heavily than BM25 results in the final ranking, with a top-level normalizer applied to all retrievers.
 
 ```console
 GET my_index/_search
@@ -107,35 +108,14 @@ GET my_index/_search
         {
           "retriever": {
             "knn": {
-              ...
+              "field": "title_vector",
+              "query_vector": [0.1, 0.2, 0.3],
+              "k": 10,
+              "num_candidates": 100
             }
           },
           "weight": 5 # KNN query weighted 5x
         },
-        {
-          "retriever": {
-            "standard": {
-              ...
-            }
-          },
-          "weight": 1.5 # BM25 query weighted 1.5x
-        }
-      ]
-    }
-  }
-}
-```
-
-### Using top-level normalizer
-
-This example shows how to use a top-level normalizer that applies to all sub-retrievers:
-
-```console
-GET my_index/_search
-{
-  "retriever": {
-    "linear": {
-      "retrievers": [
         {
           "retriever": {
             "standard": {
@@ -146,18 +126,7 @@ GET my_index/_search
               }
             }
           },
-          "weight": 1.0
-        },
-        {
-          "retriever": {
-            "knn": {
-              "field": "title_vector",
-              "query_vector": [0.1, 0.2, 0.3],
-              "k": 10,
-              "num_candidates": 100
-            }
-          },
-          "weight": 2.0
+          "weight": 1.5 # BM25 query weighted 1.5x
         }
       ],
       "normalizer": "minmax"
@@ -166,6 +135,6 @@ GET my_index/_search
 }
 ```
 
-In this example, the `minmax` normalizer is applied to both the standard retriever and the kNN retriever. The top-level normalizer serves as a default that can be overridden by individual sub-retrievers. When using the multi-field query format, the top-level normalizer is applied to all generated inner retrievers.
+In this example, the `minmax` normalizer is applied to both the kNN retriever and the standard retriever. The top-level normalizer serves as a default that can be overridden by individual sub-retrievers. When using the multi-field query format, the top-level normalizer is applied to all generated inner retrievers.
 
 See also [this hybrid search example](retrievers-examples.md#retrievers-examples-linear-retriever).

docs/reference/elasticsearch/rest-apis/retrievers/retrievers-examples.md

@@ -247,7 +247,7 @@ GET /retrievers_example/_search
                         }
                     },
                     "weight": 1.5,
-                    "normalizer": "minmax"
+                    "normalizer": "l2_norm"
                 }
             ],
             "rank_window_size": 10

x-pack/plugin/rank-rrf/src/main/java/org/elasticsearch/xpack/rank/linear/LinearRetrieverBuilder.java

@@ -178,8 +178,6 @@ public LinearRetrieverBuilder(
         this.query = query;
         this.normalizer = normalizer;
         this.weights = weights;
-
-        // Initialize normalizers array
         this.normalizers = new ScoreNormalizer[normalizers.length];
         for (int i = 0; i < normalizers.length; i++) {
             this.normalizers[i] = resolveNormalizer(normalizers[i], normalizer);

x-pack/plugin/rank-rrf/src/test/java/org/elasticsearch/xpack/rank/linear/LinearRetrieverBuilderParsingTests.java

@@ -69,11 +69,9 @@ protected LinearRetrieverBuilder createTestInstance() {
                 new CompoundRetrieverBuilder.RetrieverSource(TestRetrieverBuilder.createRandomTestRetrieverBuilder(), null)
             );
             weights[i] = randomFloat();
-            if (randomBoolean()) {
-                normalizers[i] = randomScoreNormalizer();
-            } else {
-                normalizers[i] = null;
-            }
+            normalizers[i] = randomFrom(
+                new ScoreNormalizer[] { null, MinMaxScoreNormalizer.INSTANCE, L2ScoreNormalizer.INSTANCE, IdentityScoreNormalizer.INSTANCE }
+            );
         }
 
         return new LinearRetrieverBuilder(innerRetrievers, fields, query, normalizer, rankWindowSize, weights, normalizers);