[FEATURE] Support `include_named_queries_score` to parsed scores of named queries

[briggySmalls]

Is your feature request related to a problem?

The OpenSearch Search API supports an include_named_queries_score parameter (introduced in OpenSearch 3.0 and backported to 2.x). When enabled, the matched_queries field in the response changes from a List<String> to a Map<String, Double>.

The Java client currently has no way to request this parameter, nor does Hit.java have a field to store the resulting scores. Furthermore, because Hit.matched_queries is strictly typed as List<String>, enabling this parameter manually via a raw request throws deserialization errors.

What solution would you like?

I would like to add support for requesting and accessing these scores without breaking backward compatibility for existing users.

The solution should:

• Enable setting the include_named_queries_score URL parameter.
• Enable setting the include_named_queries_score request body attribute.
• Add a new property to Hit.java: @Nullable Map<String, Double> matched_query_scores.

Implementation Note:
To maintain backward compatibility, the deserialization logic for Hit will need to handle the polymorphic nature of the matched_queries JSON field:

1. If JSON is List<String>: Populate existing matched_queries list; matched_query_scores remains null.
2. If JSON is Map<String, Double>: Populate the new matched_query_scores map AND populate the existing matched_queries list using the map keys. This ensures legacy code relying on the List continues to work seamlessly.

What alternatives have you considered?

[Breaking change] Change matched_queries to Map<String, Double>

The cleanest API solution would be to change the type of the existing field. However, Hit.matched_queries is currently exposed as a List<String>. Changing this would break binary and source compatibility for all users, which is likely unacceptable outside of a major version release.

Wrapper class

I considered introducing a wrapper class (e.g., MatchedQueries) to encapsulate the polymorphism. However, replacing the existing List<String> field with this wrapper is also a breaking change (same as above). Introducing a wrapper alongside the existing list seems overly complex compared to simply adding a Map field.

Do you have any additional context?

• OpenSearch server support added in: add support for scored named queries OpenSearch#11626
• Related discussion in elasticsearch-java (where they opted for a breaking change in a new major version): Support include_named_queries_score in search requests elastic/elasticsearch-java#634

Given that OpenSearch 3.0 was released recently, waiting for a new major version of the client to introduce this feature seems undesirable. The proposed additive solution allows immediate support.

[sam-briggs-depop]

Link to the include_named_queries_score URL parameter in the read-api-spec: https://github.com/opensearch-project/OpenSearch/blob/1ee30dcc8334f63c51bed276397fa4d50406a8e6/rest-api-spec/src/main/resources/rest-api-spec/api/search.json#L233-L237

[sam-briggs-depop]

I've noticed that the codebase generates the client from the OpenAPI specification that I assume is defined in https://github.com/opensearch-project/opensearch-api-specification/.

I've opened an issue there to fix the polymorphic matched_queries response: opensearch-project/opensearch-api-specification#998

Perhaps a breaking change would be accepted after all, if it was accepted in the upstream spec repo?