Browse Source

[DOCS] Clarify async search response flags (#55574)

Relates to #55572
Luca Cavanna 5 years ago
parent
commit
c04bf6e14a
1 changed files with 16 additions and 5 deletions
  1. 16 5
      docs/reference/search/async-search.asciidoc

+ 16 - 5
docs/reference/search/async-search.asciidoc

@@ -80,12 +80,21 @@ results are returned as part of the <<search-api-response-body,`response`>> obje
 // TESTRESPONSE[s/"relation" : "gte"/"relation": $body.response.hits.total.relation/]
 // TESTRESPONSE[s/"hits" : \[ \]\n\s\s\s\s\}/"hits" : \[\]},"aggregations":  $body.response.aggregations/]
 
-<1> Identifier of the async search that can be used to monitor its progress, retrieve its results, and/or delete it.
-<2> Whether the returned search results are partial or final
+<1> Identifier of the async search that can be used to monitor its progress,
+retrieve its results, and/or delete it
+<2> When the query is no longer running, indicates whether the search failed
+or was successfully completed on all shards. While the query is being
+executed, `is_partial` is always set to `true`
 <3> Whether the search is still being executed or it has completed
 <4> How many shards the search will be executed on, overall
 <5> How many shards have successfully completed the search
-<6> How many documents are currently matching the query, which belong to the shards that have already completed the search
+<6> How many documents are currently matching the query, which belong to the
+shards that have already completed the search
+
+NOTE: Although the query is no longer running, hence `is_running` is set to
+`false`, results may be partial. That happens in case the search failed after
+some shards returned their results, or when the node that is coordinating the
+ async search dies.
 
 It is possible to block and wait until the search is completed up to a certain
 timeout by providing the `wait_for_completion_timeout` parameter, which
@@ -181,10 +190,12 @@ GET /_async_search/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsd
 // TESTRESPONSE[s/"buckets" : \[\]/"buckets": $body.response.aggregations.sale_date.buckets/]
 // TESTRESPONSE[s/"num_reduce_phases" : 46,//]
 
-<1> Whether the returned search results are partial or final
+<1> When the query is no longer running, indicates whether the search failed
+or was successfully completed on all shards. While the query is being
+executed, `is_partial` is always set to `true`
 <2> Whether the search is still being executed or it has completed
 <3> When the async search will expire
-<4> Indicates how many reduction of the results have been performed. If this
+<4> Indicates how many reductions of the results have been performed. If this
 number increases compared to the last retrieved results, you can expect
 additional results included in the search response
 <5> Indicates how many shards have executed the query. Note that in order for