[BUG] How to sort by a sub-aggregation field in multi_terms aggregation using opensearch-java 3.1.0?

What is the bug?

The OpenSearch Java client (opensearch-java) does not provide a typed API to sort multi_terms aggregation results using sub-aggregation values.

While the REST API supports ordering multi_terms buckets by named sub-aggregation metrics, the Java client does not expose a corresponding supported DSL for this functionality.

As a result, it is not possible to:

• Sort multi_terms buckets using sub-aggregation names
• Pass named sub-aggregation keys into the order clause in a type-safe way
• Replicate REST API behavior using the typed Java client

This creates a gap between REST API capabilities and Java client support for bucket ordering in multi_terms aggregations.

How can one reproduce the bug?

Try to implement the following REST query using the OpenSearch Java client (3.1.0):

{
  "size": 0,
  "aggs": {
    "breakdown": {
      "multi_terms": {
        "terms": [
          { "field": "customer_name" },
          { "field": "customer_id" }
        ],
        "size": 1000,
        "order": {
          "active_orders": "desc"
        }
      },
      "aggs": {
        "inactive_orders": {
          "filter": {
            "bool": {
              "must_not": {
                "terms": { "status": ["SHIPPED", "DELIVERED"] }
              }
            }
          }
        },
        "active_orders": {
          "filter": {
            "terms": { "status": ["DELIVERED"] }
          },
          "aggs": {
            "price_ranges": {
              "range": {
                "field": "order_value",
                "ranges": [
                  { "key": "Low",    "from": 0,   "to": 100  },
                  { "key": "Medium", "from": 100, "to": 500  },
                  { "key": "High",   "from": 500, "to": 9999 }
                ]
              }
            }
          }
        }
      }
    }
  }
}

The order: { "active_orders": "desc" } sorts buckets by the doc count of the active_orders filter sub-aggregation. This works fine via REST.

But I can’t find the correct way to express the order part in the Java client. Things I’ve tried that don’t compile or don’t work:

• I assume it uses HistogramOrder class internally, but I don't think it accepts these named parameters
• .order(Map.of("active_orders", SortOrder.Desc)) — method not found
• MultiTermsOrder → ❌ I tired with this class, but it does not exist in 3.1.0

What is the expected behavior?

The OpenSearch Java client should support ordering multi_terms aggregation buckets using sub-aggregation results.

Specifically, it should allow something like:

• sort by sub-aggregation name (active_orders)
• using a typed DSL equivalent of the REST API

Example expected behavior:

• multi_terms.order should accept named sub-aggregation keys

• Java DSL should support:

  • "active_orders": "desc"

without requiring raw JSON.

What is your host/environment?

• org.opensearch.client:opensearch-java:3.1.0
• OpenSearch cluster version: 3.1

Start with the multi_terms aggregation API and its order handling, then compare the existing HistogramOrder support with the REST example's named active_orders key. Trace how aggregation order values are represented and serialized; done means a typed Java DSL can express active_orders descending and coverage verifies the resulting request.