Add gRPC support for Min and Max metric aggregations

This commit adds complete gRPC support for Min and Max metric aggregations,
including request parsing, response conversion, and integration with SearchSourceBuilder.

## Request-Side Converters (Proto → Java)

### Core Infrastructure:
- AggregationContainerProtoUtils: Central dispatcher routing aggregation types
  to specific converters, validates aggregation names
- ValuesSourceAggregationProtoUtils: Shared utilities for parsing common
  ValuesSource fields (field, missing, value_type, format, script)

### Min/Max Converters:
- MinAggregationProtoUtils: Converts proto MinAggregation → MinAggregationBuilder
- MaxAggregationProtoUtils: Converts proto MaxAggregation → MaxAggregationBuilder

### SearchSourceBuilder Integration:
- Updated SearchSourceBuilderProtoUtils to parse aggregations map from
  proto SearchRequestBody and add to SearchSourceBuilder

## Response-Side Converters (Java → Proto)

### Core Infrastructure:
- AggregateProtoUtils: Central dispatcher for converting InternalAggregation
  to proto Aggregate, with metadata and sub-aggregation helpers

### Min/Max Converters:
- MinAggregateProtoUtils: Converts InternalMin → proto MinAggregate
- MaxAggregateProtoUtils: Converts InternalMax → proto MaxAggregate
- Handles special values (infinity, NaN), formatting, and metadata

## Server-Side Changes

- InternalNumericMetricsAggregation: Added getFormat() getter to expose
  format information for gRPC converters

## Test Coverage

### Request-Side Tests (~260 tests):
- AggregationContainerProtoUtilsTests: 11 tests
- MinAggregationProtoUtilsTests: 108 tests
- MaxAggregationProtoUtilsTests: 108 tests
- ValuesSourceAggregationProtoUtilsTests: 40+ tests
- SearchSourceBuilderProtoUtilsTests: 2 new aggregation tests

### Response-Side Tests (~410 tests):
- AggregateProtoUtilsTests: 10 tests
- MinAggregateProtoUtilsTests: 190 tests (values, infinity, NaN, formatting)
- MaxAggregateProtoUtilsTests: 190 tests (values, infinity, NaN, formatting)
- InternalMinTests: 32 tests
- InternalMaxTests: 32 tests

**Total: ~670 test cases**

## Design Principles

- Mirrors REST API patterns for consistency
- Maintains behavioral parity with REST layer
- Comprehensive error handling and validation
- Special value support (infinity, NaN) matching REST behavior
- Metadata handling consistent across all aggregations

## Files Summary

- **New Implementation Files**: 11 (converters + infrastructure)
- **New Test Files**: 8 (comprehensive test coverage)
- **Modified Files**: 3 (SearchSourceBuilder integration + server changes)
- **Package Documentation**: 5 package-info.java files
- **Total Lines**: ~1,800 (implementation + tests)

Co-Authored-By: Claude (claude-sonnet-4-5) <noreply@anthropic.com>

Author: yiyupan

modules/transport-grpc/src/main/java/org/opensearch/transport/grpc/proto/request/search/SearchSourceBuilderProtoUtils.java

@@ -9,16 +9,19 @@
 
 import org.opensearch.common.unit.TimeValue;
 import org.opensearch.core.xcontent.XContentParser;
+import org.opensearch.protobufs.AggregationContainer;
 import org.opensearch.protobufs.DerivedField;
 import org.opensearch.protobufs.FieldAndFormat;
 import org.opensearch.protobufs.Rescore;
 import org.opensearch.protobufs.ScriptField;
 import org.opensearch.protobufs.SearchRequestBody;
 import org.opensearch.protobufs.TrackHits;
+import org.opensearch.search.aggregations.AggregationBuilder;
 import org.opensearch.search.builder.SearchSourceBuilder;
 import org.opensearch.search.sort.SortBuilder;
 import org.opensearch.transport.grpc.proto.request.common.FetchSourceContextProtoUtils;
 import org.opensearch.transport.grpc.proto.request.common.ScriptProtoUtils;
+import org.opensearch.transport.grpc.proto.request.search.aggregation.AggregationContainerProtoUtils;
 import org.opensearch.transport.grpc.proto.request.search.query.AbstractQueryBuilderProtoUtils;
 import org.opensearch.transport.grpc.proto.request.search.sort.SortBuilderProtoUtils;
 import org.opensearch.transport.grpc.spi.QueryBuilderProtoConverterRegistry;
@@ -31,8 +34,23 @@
 import static org.opensearch.search.internal.SearchContext.TRACK_TOTAL_HITS_DISABLED;
 
 /**
- * Utility class for converting SearchSourceBuilder Protocol Buffers to objects
+ * Utility class for converting SearchSourceBuilder Protocol Buffers to objects.
+ * This class handles the parsing of search request body from protobuf to OpenSearch's
+ * internal SearchSourceBuilder representation.
  *
+ * <p>Key conversions handled:
+ * <ul>
+ *   <li>Queries: InnerQueryBuilder proto → {@link org.opensearch.index.query.QueryBuilder}</li>
+ *   <li>Aggregations: Map&lt;String, AggregationContainer&gt; proto → {@link org.opensearch.search.aggregations.AggregationBuilder}</li>
+ *   <li>Sorts: SortCombinations proto → {@link org.opensearch.search.sort.SortBuilder}</li>
+ *   <li>Source filtering: SourceConfig proto → {@link org.opensearch.search.fetch.subphase.FetchSourceContext}</li>
+ * </ul>
+ * <p>
+ * Note: The REST API supports both "aggregations" and "aggs" field names as aliases.
+ * In protobuf, only the "aggregations" field is used (field 36 in SearchRequestBody).
+ *
+ * @see org.opensearch.search.builder.SearchSourceBuilder
+ * @see org.opensearch.search.aggregations.AggregatorFactories
  */
 public class SearchSourceBuilderProtoUtils {
 
@@ -152,13 +170,23 @@ private static void parseNonQueryFields(
             }
         }
 
-        // Aggregations field was removed in protobufs 1.0.0
-        // TODO: Support aggregations when they are re-added to the proto
-        /*
+        // Parse aggregations from protobuf
+        // Similar to REST API parsing in SearchSourceBuilder.parseXContent()
+        // REST side: aggregations = AggregatorFactories.parseAggregators(parser)
+        // Proto side: We parse from the protobuf AggregationContainer map
+        // @see org.opensearch.search.builder.SearchSourceBuilder#parseXContent(XContentParser, boolean)
+        // @see org.opensearch.search.aggregations.AggregatorFactories#parseAggregators(XContentParser)
+        //
+        // Note: In REST API, "aggregations" and "aggs" are aliases for the same JSON field.
+        // In protobuf, we only have the "aggregations" field (field 36).
         if (protoRequest.getAggregationsCount() > 0) {
-            throw new UnsupportedOperationException("aggregations param is not supported yet");
+            for (Map.Entry<String, AggregationContainer> entry : protoRequest.getAggregationsMap().entrySet()) {
+                String aggName = entry.getKey();
+                AggregationBuilder aggBuilder = AggregationContainerProtoUtils.fromProto(aggName, entry.getValue());
+                searchSourceBuilder.aggregation(aggBuilder);
+            }
         }
-        */
+
         if (protoRequest.hasHighlight()) {
             searchSourceBuilder.highlighter(HighlightBuilderProtoUtils.fromProto(protoRequest.getHighlight(), registry));
         }

modules/transport-grpc/src/main/java/org/opensearch/transport/grpc/proto/request/search/aggregation/AggregationContainerProtoUtils.java

@@ -0,0 +1,89 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+package org.opensearch.transport.grpc.proto.request.search.aggregation;
+
+import org.opensearch.protobufs.AggregationContainer;
+import org.opensearch.search.aggregations.AggregationBuilder;
+import org.opensearch.search.aggregations.AggregatorFactories;
+import org.opensearch.transport.grpc.proto.request.common.ObjectMapProtoUtils;
+import org.opensearch.transport.grpc.proto.request.search.aggregation.metrics.MaxAggregationProtoUtils;
+import org.opensearch.transport.grpc.proto.request.search.aggregation.metrics.MinAggregationProtoUtils;
+
+/**
+ * Utility class for converting AggregationContainer protocol buffers to OpenSearch AggregationBuilder objects.
+ *
+ * <p>This class serves as a central dispatcher that routes different aggregation types to their specific converters,
+ * similar to how {@link AggregatorFactories#parseAggregators} uses registered parsers with XContentParser.
+ *
+ * <p>Currently supports Min and Max metric aggregations.
+ *
+ * @see AggregatorFactories#parseAggregators
+ */
+public class AggregationContainerProtoUtils {
+
+    private AggregationContainerProtoUtils() {
+        // Utility class - no instances
+    }
+
+    /**
+     * Converts an AggregationContainer protobuf to an {@link AggregationBuilder}.
+     *
+     * <p>Mirrors {@link AggregatorFactories#parseAggregators}, serving as the central dispatcher
+     * for all aggregation types. Validates the aggregation name and delegates to type-specific converters.
+     *
+     * @param name The name of the aggregation
+     * @param aggContainer The protobuf aggregation container
+     * @return The corresponding {@link AggregationBuilder}
+     * @throws IllegalArgumentException if the aggregation type is not supported, container is null,
+     *         or aggregation name is invalid
+     */
+    public static AggregationBuilder fromProto(String name, AggregationContainer aggContainer) {
+        if (aggContainer == null) {
+            throw new IllegalArgumentException("AggregationContainer must not be null");
+        }
+        if (name == null || name.isEmpty()) {
+            throw new IllegalArgumentException("Aggregation name must not be null or empty");
+        }
+
+        // Validate aggregation name format (mirrors AggregatorFactories.parseAggregators)
+        if (!AggregatorFactories.VALID_AGG_NAME.matcher(name).matches()) {
+            throw new IllegalArgumentException(
+                "Invalid aggregation name ["
+                    + name
+                    + "]. Aggregation names can contain any character except '[', ']', and '>'"
+            );
+        }
+
+        AggregationBuilder builder;
+
+        // Dispatch to type-specific converter based on aggregation type
+        // This mirrors the REST-side pattern where each aggregation has a registered parser
+        switch (aggContainer.getAggregationContainerCase()) {
+            case MIN:
+                builder = MinAggregationProtoUtils.fromProto(name, aggContainer.getMin());
+                break;
+
+            case MAX:
+                builder = MaxAggregationProtoUtils.fromProto(name, aggContainer.getMax());
+                break;
+
+            case AGGREGATIONCONTAINER_NOT_SET:
+                throw new IllegalArgumentException("Aggregation type not set in container");
+
+            default:
+                throw new IllegalArgumentException("Unsupported aggregation type: " + aggContainer.getAggregationContainerCase());
+        }
+
+        // Apply metadata if present (common to all aggregations)
+        if (aggContainer.hasMeta()) {
+            builder.setMetadata(ObjectMapProtoUtils.fromProto(aggContainer.getMeta()));
+        }
+
+        return builder;
+    }
+}

modules/transport-grpc/src/main/java/org/opensearch/transport/grpc/proto/request/search/aggregation/metrics/MaxAggregationProtoUtils.java

@@ -0,0 +1,81 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+package org.opensearch.transport.grpc.proto.request.search.aggregation.metrics;
+
+import org.opensearch.protobufs.MaxAggregation;
+import org.opensearch.search.aggregations.metrics.MaxAggregationBuilder;
+import org.opensearch.transport.grpc.proto.request.search.aggregation.support.ValuesSourceAggregationProtoUtils;
+
+/**
+ * Utility class for converting MaxAggregation Protocol Buffers to MaxAggregationBuilder objects.
+ *
+ * <p>Field processing follows the exact sequence defined in {@link MaxAggregationBuilder#PARSER}
+ * to ensure identical behavior with REST API parsing. This includes:
+ * <ol>
+ *   <li>ValuesSourceAggregationBuilder fields (field, missing, value_type, format, script)</li>
+ * </ol>
+ *
+ * @see MaxAggregationBuilder#PARSER
+ * @see org.opensearch.search.aggregations.support.ValuesSourceAggregationBuilder#declareFields
+ */
+public class MaxAggregationProtoUtils {
+
+    private MaxAggregationProtoUtils() {
+        // Utility class
+    }
+
+    /**
+     * Converts a Protocol Buffer MaxAggregation to a MaxAggregationBuilder.
+     *
+     * <p>This method parallels the REST parsing logic in {@link MaxAggregationBuilder#PARSER},
+     * processing fields in the exact same sequence to ensure consistent validation and behavior.
+     *
+     * @param name The name of the aggregation (from parent container map key)
+     * @param maxAggProto The Protocol Buffer MaxAggregation to convert
+     * @return A configured MaxAggregationBuilder
+     * @throws IllegalArgumentException if required fields are missing or validation fails
+     * @see MaxAggregationBuilder#PARSER
+     */
+    public static MaxAggregationBuilder fromProto(String name, MaxAggregation maxAggProto) {
+        if (maxAggProto == null) {
+            throw new IllegalArgumentException("MaxAggregation proto must not be null");
+        }
+        if (name == null || name.isEmpty()) {
+            throw new IllegalArgumentException("Aggregation name must not be null or empty");
+        }
+
+        MaxAggregationBuilder builder = new MaxAggregationBuilder(name);
+
+        // ========================================
+        // ValuesSourceAggregationBuilder common fields
+        // ========================================
+        // @see ValuesSourceAggregationBuilder#declareFields called from MaxAggregationBuilder.PARSER
+        // For max aggregation: scriptable=true, formattable=true, timezoneAware=false, fieldRequired=true
+
+        // Always-declared fields (ValuesSourceAggregationBuilder lines 83-103)
+        ValuesSourceAggregationProtoUtils.parseField(builder, maxAggProto.hasField(), maxAggProto.getField());
+        ValuesSourceAggregationProtoUtils.parseMissing(builder, maxAggProto.hasMissing(), maxAggProto.getMissing());
+        ValuesSourceAggregationProtoUtils.parseValueType(builder, maxAggProto.hasValueType(), maxAggProto.getValueType());
+
+        // Conditional fields based on configuration (ValuesSourceAggregationBuilder lines 105-141)
+        ValuesSourceAggregationProtoUtils.parseConditionalFields(
+            builder,
+            maxAggProto.hasFormat(),
+            maxAggProto.getFormat(),
+            maxAggProto.hasScript(),
+            maxAggProto.getScript(),
+            maxAggProto.hasField() && !maxAggProto.getField().isEmpty(),
+            /* scriptable= */ true,
+            /* formattable= */ true,
+            /* timezoneAware= */ false,
+            /* fieldRequired= */ true
+        );
+
+        return builder;
+    }
+}

modules/transport-grpc/src/main/java/org/opensearch/transport/grpc/proto/request/search/aggregation/metrics/MinAggregationProtoUtils.java

@@ -0,0 +1,81 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+package org.opensearch.transport.grpc.proto.request.search.aggregation.metrics;
+
+import org.opensearch.protobufs.MinAggregation;
+import org.opensearch.search.aggregations.metrics.MinAggregationBuilder;
+import org.opensearch.transport.grpc.proto.request.search.aggregation.support.ValuesSourceAggregationProtoUtils;
+
+/**
+ * Utility class for converting MinAggregation Protocol Buffers to MinAggregationBuilder objects.
+ *
+ * <p>Field processing follows the exact sequence defined in {@link MinAggregationBuilder#PARSER}
+ * to ensure identical behavior with REST API parsing. This includes:
+ * <ol>
+ *   <li>ValuesSourceAggregationBuilder fields (field, missing, value_type, format, script)</li>
+ * </ol>
+ *
+ * @see MinAggregationBuilder#PARSER
+ * @see org.opensearch.search.aggregations.support.ValuesSourceAggregationBuilder#declareFields
+ */
+public class MinAggregationProtoUtils {
+
+    private MinAggregationProtoUtils() {
+        // Utility class
+    }
+
+    /**
+     * Converts a Protocol Buffer MinAggregation to a MinAggregationBuilder.
+     *
+     * <p>This method parallels the REST parsing logic in {@link MinAggregationBuilder#PARSER},
+     * processing fields in the exact same sequence to ensure consistent validation and behavior.
+     *
+     * @param name The name of the aggregation (from parent container map key)
+     * @param minAggProto The Protocol Buffer MinAggregation to convert
+     * @return A configured MinAggregationBuilder
+     * @throws IllegalArgumentException if required fields are missing or validation fails
+     * @see MinAggregationBuilder#PARSER
+     */
+    public static MinAggregationBuilder fromProto(String name, MinAggregation minAggProto) {
+        if (minAggProto == null) {
+            throw new IllegalArgumentException("MinAggregation proto must not be null");
+        }
+        if (name == null || name.isEmpty()) {
+            throw new IllegalArgumentException("Aggregation name must not be null or empty");
+        }
+
+        MinAggregationBuilder builder = new MinAggregationBuilder(name);
+
+        // ========================================
+        // ValuesSourceAggregationBuilder common fields
+        // ========================================
+        // @see ValuesSourceAggregationBuilder#declareFields called from MinAggregationBuilder.PARSER
+        // For min aggregation: scriptable=true, formattable=true, timezoneAware=false, fieldRequired=true
+
+        // Always-declared fields (ValuesSourceAggregationBuilder lines 83-103)
+        ValuesSourceAggregationProtoUtils.parseField(builder, minAggProto.hasField(), minAggProto.getField());
+        ValuesSourceAggregationProtoUtils.parseMissing(builder, minAggProto.hasMissing(), minAggProto.getMissing());
+        ValuesSourceAggregationProtoUtils.parseValueType(builder, minAggProto.hasValueType(), minAggProto.getValueType());
+
+        // Conditional fields based on configuration (ValuesSourceAggregationBuilder lines 105-141)
+        ValuesSourceAggregationProtoUtils.parseConditionalFields(
+            builder,
+            minAggProto.hasFormat(),
+            minAggProto.getFormat(),
+            minAggProto.hasScript(),
+            minAggProto.getScript(),
+            minAggProto.hasField() && !minAggProto.getField().isEmpty(),
+            /* scriptable= */ true,
+            /* formattable= */ true,
+            /* timezoneAware= */ false,
+            /* fieldRequired= */ true
+        );
+
+        return builder;
+    }
+}

modules/transport-grpc/src/main/java/org/opensearch/transport/grpc/proto/request/search/aggregation/metrics/package-info.java

@@ -0,0 +1,13 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Protocol Buffer utilities for metrics aggregation requests.
+ * Contains converters from Protocol Buffer aggregation requests to OpenSearch metrics aggregation builders.
+ * <p>
+ * Metrics aggregations compute metrics (like min, max, avg, sum, cardinality) over a set of documents.
+ *
+ * @see org.opensearch.search.aggregations.metrics
+ */
+package org.opensearch.transport.grpc.proto.request.search.aggregation.metrics;

modules/transport-grpc/src/main/java/org/opensearch/transport/grpc/proto/request/search/aggregation/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+/**
+ * Protocol Buffer utilities for converting aggregation requests from proto to OpenSearch objects.
+ *
+ * <p>This package contains the central dispatcher {@link org.opensearch.transport.grpc.proto.request.search.aggregation.AggregationContainerProtoUtils}
+ * that routes aggregation containers to their type-specific converters.
+ *
+ * <p>Sub-packages:
+ * <ul>
+ *   <li>{@code metrics} - Metric aggregations (Min, Max, etc.)</li>
+ * </ul>
+ */
+package org.opensearch.transport.grpc.proto.request.search.aggregation;