track_total_hits should be Union of boolean and integer

[russcam]

Issue

The search.json REST API spec in 7.x defines track_total_hits as a boolean

elasticsearch/rest-api-spec/src/main/resources/rest-api-spec/api/search.json

Lines 162 to 165 in c593085

	"track_total_hits": {
	"type" : "boolean",
	"description": "Indicate if the number of documents that match the query should be tracked"
	},

The documentation indicates however that track_total_hits can be a boolean or an integer i.e. a discriminated union of two different types.

Since Elasticsearch clients generate code from the REST API specs, track_total_hits will be modelled as a boolean only. For example

in elasticsearch-js

https://github.com/elastic/elasticsearch-js/blob/21863965706e0ebfcbe34e0436bf3359579dc834/api/requestParams.d.ts#L1123

in elasticsearch-net

https://github.com/elastic/elasticsearch-net/blob/69cf48c400bfc774ed16aeb502abd13565d72f3c/src/Nest/Requests.NoNamespace.cs#L2812-L2817

Request

track_total_hits should be modelled as a union of boolean and int. For example,

 "track_total_hits": { 
   "type" : "boolean|integer", 
   "description": "Indicate if the number of documents that match the query should be tracked (true or false), or an integer to accurately track the total hit count that match the query up to" 
 },

I propose making this change for 8.x. It would not be feasible to make this change in 7.x because it would break (binary) compatibility of already released, generated client code.

[elasticmachine]

Pinging @elastic/es-search

[karmi]

I can't find the previous conversation we had about this topic, but what about making the type an array? (Also related the schema change in #42346)

[russcam]

This was addressed in #51846. Closing