Document changes in partial result reporting (elastic#124928)

* Document changes in partial result reporting

Author: smalyshev

docs/reference/esql/esql-across-clusters.asciidoc

@@ -293,7 +293,8 @@ which clusters have slower response times than others.
 skipped due to the can-match phase results. Shards are skipped when they cannot have any matching data
 and therefore are not included in the full ES|QL query.
 <7> The `is_partial` field is set to `true` if the search has partial results for any reason,
-for example if it was interrupted before finishing using the <<esql-async-query-stop-api,async query stop API>>.
+for example if it was interrupted before finishing using the <<esql-async-query-stop-api,async query stop API>>,
+or one of the remotes or shards failed.
 
 
 The cross-cluster metadata can be used to determine whether any data came back from a cluster.

docs/reference/esql/esql-query-api.asciidoc

@@ -63,6 +63,11 @@ You can also specify a format using the `Accept` HTTP header. If you specify
 both this parameter and the `Accept` HTTP header, this parameter takes
 precedence.
 
+`allow_partial_results`::
+(Optional, boolean) If `true`, partial results will be returned if there are shard failures, but
+the query can continue to execute on other clusters and shards. This defaults to the value of
+the cluster setting `esql.query.allow_partial_results`.
+
 [discrete]
 [role="child_attributes"]
 [[esql-query-api-request-body]]
@@ -120,11 +125,17 @@ returned if `drop_null_columns` is sent with the request.
 (array of arrays)
 Values for the search results.
 
+`is_partial`::
+(boolean)
+Indicates whether the response is partial. Partial responses can happen due to partial shard failures,
+failures in remote clusters, or if the async query was stopped by calling the <<esql-async-query-stop-api,async query stop API>>.
+
 `_clusters`::
 (object)
-Metadata about clusters involved in the execution of a cross-cluster query. Only returned (1) for
-cross-cluster searches and (2) when `include_ccs_metadata` is sent in the body and set to `true`
-and (3) when `format` of the response is set to JSON (the default), CBOR, SMILE, or YAML.
+Metadata about clusters involved in the execution of a query. This field is present in the response in the following cases:
+(1) for cross-cluster searches, when `include_ccs_metadata` is sent in the body and set to `true`;
+(2) the result is partial (`is_partial` is `true`) and there are failures on some clusters.
+It is only returned if the `format` of the response is set to JSON (the default), CBOR, SMILE, or YAML.
 See <<ccq-cluster-details>> for more information.
 
 `profile`::