From 10139e657ff26c0ce42c7a9f98b0d16f380534af Mon Sep 17 00:00:00 2001 From: Stanislav Malyshev Date: Fri, 14 Mar 2025 15:46:57 -0600 Subject: [PATCH 1/3] Document changes in partial result reporting --- .../esql/esql-across-clusters.asciidoc | 3 ++- docs/reference/esql/esql-query-api.asciidoc | 17 ++++++++++++++--- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/reference/esql/esql-across-clusters.asciidoc b/docs/reference/esql/esql-across-clusters.asciidoc index d3ad58d95d972..f607f804549f3 100644 --- a/docs/reference/esql/esql-across-clusters.asciidoc +++ b/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 <>. +for example if it was interrupted before finishing using the <>, +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. diff --git a/docs/reference/esql/esql-query-api.asciidoc b/docs/reference/esql/esql-query-api.asciidoc index e5b29a5ca25f1..301f650dff116 100644 --- a/docs/reference/esql/esql-query-api.asciidoc +++ b/docs/reference/esql/esql-query-api.asciidoc @@ -78,6 +78,11 @@ responses. See <>. on each cluster. Defaults to `false`. The API only supports this parameter for CBOR, JSON, SMILE, and YAML responses. See <>. +`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 setting `esql.query.allow_partial_results`. + `locale`:: (Optional, string) Returns results (especially dates) formatted per the conventions of the locale. For syntax, refer to <>. @@ -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 failures in remote clusters +or single shards, or stopping an async query. + `_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 <> for more information. `profile`:: From a3d1f7dd27bb7a3bfd6a5d5714dce0ca1c2110bc Mon Sep 17 00:00:00 2001 From: Stanislav Malyshev Date: Fri, 14 Mar 2025 16:18:07 -0600 Subject: [PATCH 2/3] Move allow_partial_results to query params --- docs/reference/esql/esql-query-api.asciidoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/reference/esql/esql-query-api.asciidoc b/docs/reference/esql/esql-query-api.asciidoc index 301f650dff116..c384f1ff5c50c 100644 --- a/docs/reference/esql/esql-query-api.asciidoc +++ b/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 setting `esql.query.allow_partial_results`. + [discrete] [role="child_attributes"] [[esql-query-api-request-body]] @@ -78,11 +83,6 @@ responses. See <>. on each cluster. Defaults to `false`. The API only supports this parameter for CBOR, JSON, SMILE, and YAML responses. See <>. -`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 setting `esql.query.allow_partial_results`. - `locale`:: (Optional, string) Returns results (especially dates) formatted per the conventions of the locale. For syntax, refer to <>. From 1a0123c9ba4aace456aba39d061dbb297c8a3b58 Mon Sep 17 00:00:00 2001 From: Stanislav Malyshev Date: Mon, 17 Mar 2025 10:24:02 -0600 Subject: [PATCH 3/3] text edits --- docs/reference/esql/esql-query-api.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/esql/esql-query-api.asciidoc b/docs/reference/esql/esql-query-api.asciidoc index c384f1ff5c50c..e8180209073c3 100644 --- a/docs/reference/esql/esql-query-api.asciidoc +++ b/docs/reference/esql/esql-query-api.asciidoc @@ -66,7 +66,7 @@ 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 setting `esql.query.allow_partial_results`. +the cluster setting `esql.query.allow_partial_results`. [discrete] [role="child_attributes"] @@ -127,8 +127,8 @@ Values for the search results. `is_partial`:: (boolean) -Indicates whether the response is partial. Partial responses can happen due to failures in remote clusters -or single shards, or stopping an async query. +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 <>. `_clusters`:: (object)