Resolved errors

Author: mridula-s109

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

@@ -31,9 +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 for score normalization. This serves as the default normalizer for all sub-retrievers.
     See [normalizers](#linear-retriever-normalizers) for supported values.
-    Required when `query` is specified.
+    
+    When using the [multi-field query format](../retrievers.md#multi-field-query-format), this field is required when `query` is specified.
+    
+    When using the `retrievers` array format, this field serves as the default normalizer for all sub-retrievers. Individual sub-retrievers can override this default by specifying their own `normalizer` field.
 
     ::::{warning}
     Avoid using `none` as that will disable normalization and may bias the result set towards lexical matches.
@@ -91,3 +94,47 @@ The `linear` retriever supports the following normalizers:
     score = (score - min) / (max - min)
     ```
 * `l2_norm`: Normalizes scores using the L2 norm of the score values {applies_to}`stack: ga 9.1`
+
+## Examples [linear-retriever-examples]
+
+### Top-level normalizer example
+
+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": {
+              "query": {
+                "match": {
+                  "title": "elasticsearch"
+                }
+              }
+            }
+          },
+          "weight": 1.0
+        },
+        {
+          "retriever": {
+            "knn": {
+              "field": "title_vector",
+              "query_vector": [0.1, 0.2, 0.3],
+              "k": 10,
+              "num_candidates": 100
+            }
+          },
+          "weight": 2.0
+        }
+      ],
+      "normalizer": "minmax"
+    }
+  }
+}
+```
+
+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.

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

@@ -212,12 +212,17 @@ public LinearRetrieverBuilder(
         }
         this.weights = weights;
         this.normalizers = normalizers;
-        this.fields = fields;
-        this.query = query;
-        this.normalizer = normalizer;
-
-        normalizeNormalizerArray(normalizer, normalizers);
-
+        // Apply top-level normalizer priority system:
+        // 1. Retriever-specific override (if specified)
+        // 2. Top-level normalizer (if specified)
+        // 3. Default (IdentityScoreNormalizer.INSTANCE)
+        ScoreNormalizer effectiveNormalizer = normalizer != null ? normalizer : DEFAULT_NORMALIZER;
+        for (int i = 0; i < normalizers.length; i++) {
+            if (normalizers[i] == null || normalizers[i].equals(DEFAULT_NORMALIZER)) {
+                normalizers[i] = effectiveNormalizer;
+            }
+            // If per-retriever normalizer is explicitly specified, keep it (allow override)
+        }
     }
 
     public LinearRetrieverBuilder(
@@ -271,19 +276,7 @@ public ActionRequestValidationException validate(
                 ),
                 validationException
             );
-        } else if (innerRetrievers.isEmpty() == false && normalizer != null) {
-            validationException = addValidationError(
-                String.format(
-                    Locale.ROOT,
-                    "[%s] [%s] cannot be provided when [%s] is specified",
-                    getName(),
-                    NORMALIZER_FIELD.getPreferredName(),
-                    RETRIEVERS_FIELD.getPreferredName()
-                ),
-                validationException
-            );
         }
-
         return validationException;
     }
 

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

@@ -22,6 +22,7 @@
 import org.elasticsearch.index.query.QueryRewriteContext;
 import org.elasticsearch.search.builder.PointInTimeBuilder;
 import org.elasticsearch.search.retriever.CompoundRetrieverBuilder;
+import org.elasticsearch.search.retriever.KnnRetrieverBuilder;
 import org.elasticsearch.search.retriever.RetrieverBuilder;
 import org.elasticsearch.search.retriever.StandardRetrieverBuilder;
 import org.elasticsearch.test.ESTestCase;
@@ -326,4 +327,63 @@ public int hashCode() {
             return Objects.hash(retriever, weight, normalizer);
         }
     }
+
+    public void testTopLevelNormalizerWithRetrieversArray() {
+        StandardRetrieverBuilder standardRetriever = new StandardRetrieverBuilder(new MatchQueryBuilder("title", "elasticsearch"));
+        KnnRetrieverBuilder knnRetriever = new KnnRetrieverBuilder(
+            "title_vector",
+            new float[] { 0.1f, 0.2f, 0.3f },
+            null,
+            10,
+            100,
+            null,
+            null
+        );
+
+        LinearRetrieverBuilder retriever = new LinearRetrieverBuilder(
+            List.of(
+                CompoundRetrieverBuilder.RetrieverSource.from(standardRetriever),
+                CompoundRetrieverBuilder.RetrieverSource.from(knnRetriever)
+            ),
+            null, // fields
+            null, // query
+            MinMaxScoreNormalizer.INSTANCE, // top-level normalizer
+            DEFAULT_RANK_WINDOW_SIZE,
+            new float[] { 1.0f, 2.0f },
+            new ScoreNormalizer[] { null, null }
+        );
+
+        assertEquals(MinMaxScoreNormalizer.INSTANCE, retriever.getNormalizers()[0]);
+        assertEquals(MinMaxScoreNormalizer.INSTANCE, retriever.getNormalizers()[1]);
+    }
+
+    public void testTopLevelNormalizerWithPerRetrieverOverrides() {
+        StandardRetrieverBuilder standardRetriever = new StandardRetrieverBuilder(new MatchQueryBuilder("title", "elasticsearch"));
+        KnnRetrieverBuilder knnRetriever = new KnnRetrieverBuilder(
+            "title_vector",
+            new float[] { 0.1f, 0.2f, 0.3f },
+            null,
+            10,
+            100,
+            null,
+            null
+        );
+
+        LinearRetrieverBuilder retriever = new LinearRetrieverBuilder(
+            List.of(
+                CompoundRetrieverBuilder.RetrieverSource.from(standardRetriever),
+                CompoundRetrieverBuilder.RetrieverSource.from(knnRetriever)
+            ),
+            null, // fields
+            null, // query
+            MinMaxScoreNormalizer.INSTANCE, // top-level normalizer
+            DEFAULT_RANK_WINDOW_SIZE,
+            new float[] { 1.0f, 2.0f },
+            new ScoreNormalizer[] { L2ScoreNormalizer.INSTANCE, null }
+        );
+
+        assertEquals(L2ScoreNormalizer.INSTANCE, retriever.getNormalizers()[0]);
+        assertEquals(MinMaxScoreNormalizer.INSTANCE, retriever.getNormalizers()[1]);
+    }
+
 }