[DOCS] EQL: Document get async EQL search API (#57366)

docs/reference/eql/eql-search-api.asciidoc

@@ -126,18 +126,14 @@ parameter. If both parameters are specified, only the query parameter is used.
 +
 --
 (Optional, <<time-units,time value>>)
-Timeout duration to block other requests while waiting for the search request to
-finish. Defaults to no timeout, meaning the search request waits for complete
-search results.
+Timeout duration to wait for the request to finish. Defaults to no
+timeout, meaning the request waits for complete search results.
 
-If this parameter is specified and the request completes before this period
-ends, complete search results are returned.
+If this parameter is specified and the request completes during this period,
+complete search results are returned.
 
-If the request does not complete before this period ends, the search becomes an
-<<eql-search-async,async search>>. A
-<<eql-search-api-response-body-search-id,search ID>> is returned at the end of
-the period. This ID can be used to monitor the progress of the async search as
-it runs.
+If the request does not complete during this period, the search becomes an
+<<eql-search-async,async search>>.
 
 [IMPORTANT]
 ====
@@ -253,18 +249,14 @@ ascending order.
 +
 --
 (Optional, <<time-units,time value>>)
-Timeout duration to block other requests while waiting for the search request to
-finish. Defaults to no timeout, meaning the search request waits for complete
-search results.
+Timeout duration to wait for the request to finish. Defaults to no
+timeout, meaning the request waits for complete search results.
 
-If this parameter is specified and the request completes before this period
-ends, complete search results are returned.
+If this parameter is specified and the request completes during this period,
+complete search results are returned.
 
-If the request does not complete before this period ends, the search becomes an
-<<eql-search-async,async search>>. A
-<<eql-search-api-response-body-search-id,search ID>> is returned at the end of
-the period. This ID can be used to monitor the ongoing progress of the search as
-it runs.
+If the request does not complete during this period, the search becomes an
+<<eql-search-async,async search>>.
 
 [IMPORTANT]
 ====
@@ -283,14 +275,17 @@ parameter. If both parameters are specified, only the query parameter is used.
 --
 Identifier for the search.
 
-This search ID is only provided if a search request does not return complete
-results during the timeout period set by the
-<<eql-search-api-wait-for-completion-timeout, `wait_for_completion_timeout`>>
-parameter, becoming an <<eql-search-async,async search>>.
+This search ID is only provided if one of the following conditions is met:
 
-You can use this ID to
-monitor the progress of an ongoing async search and retrieve complete results
-when the search finishes.
+* A search request does not return complete results during the
+  <<eql-search-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
+  parameter's timeout period, becoming an <<eql-search-async,async search>>.
+  
+* The search request's <<eql-search-api-keep-on-completion,`keep_on_completion`>>
+  parameter is `true`.
+
+You can use this ID with the <<get-async-eql-search-api,get async EQL search
+API>> to get the current status and available results for the search.
 --
 
 `is_partial`::

docs/reference/eql/get-async-eql-search-api.asciidoc

@@ -0,0 +1,82 @@
+[role="xpack"]
+[testenv="basic"]
+
+[[get-async-eql-search-api]]
+=== Get async EQL search API
+++++
+<titleabbrev>Get async EQL search</titleabbrev>
+++++
+
+dev::[]
+
+Returns the current status and available results for an <<eql-search-async,async
+EQL search>> or a <<eql-search-store-sync-eql-search,stored synchronous EQL
+search>>.
+
+[source,console]
+----
+GET /_eql/search/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=
+----
+// TEST[skip: no access to search ID]
+
+[[get-async-eql-search-api-request]]
+==== {api-request-title}
+
+`GET /_eql/search/<search_id>`
+
+[[get-async-eql-search-api-prereqs]]
+==== {api-prereq-title}
+
+See <<eql-requirements,EQL requirements>>.
+
+[[get-async-eql-search-api-limitations]]
+===== Limitations
+
+See <<eql-limitations,EQL limitations>>.
+
+[[get-async-eql-search-api-path-params]]
+==== {api-path-parms-title}
+
+`<search_id>`::
+(Required, string)
+Identifier for the search.
++
+A search ID is provided in the <<eql-search-api,EQL search API>>'s response for
+an <<eql-search-async,async search>>. A search ID is also provided if the
+request's <<eql-search-api-keep-on-completion,`keep_on_completion`>> parameter
+is `true`.
+
+[[get-async-eql-search-api-query-params]]
+==== {api-query-parms-title}
+
+`keep_alive`::
+(Optional, <<time-units,time value>>)
+Period for which the search and its results are stored on the cluster. Defaults
+to the `keep_alive` value set by the search's <<eql-search-api,EQL search
+API>> request.
++
+If specified, this parameter sets a new `keep_alive` period for the search,
+starting when the get async EQL search API request executes. This new period
+overwrites the one specified in the EQL search API request.
++
+When this period expires, the search and its results are deleted, even if the
+search is ongoing.
+
+`wait_for_completion_timeout`::
+(Optional, <<time-units,time value>>)
+Timeout duration to wait for the request to finish. Defaults to no timeout,
+meaning the request waits for complete search results.
++
+If this parameter is specified and the request completes during this period,
+complete search results are returned.
++
+If the request does not complete during this period, partial results, if
+available, are returned.
+
+[role="child_attributes"]
+[[get-async-eql-search-api-response-body]]
+==== {api-response-body-title}
+
+The async EQL search API returns the same response body as the EQL search API.
+See the EQL search API's <<eql-search-api-response-body,response body
+parameters>>.

docs/reference/eql/search.asciidoc

@@ -468,9 +468,8 @@ GET /sec_logs/_eql/search
 
 EQL searches in {es} are designed to run on large volumes of data quickly,
 often returning results in milliseconds. Because of this, the EQL search API
-runs _synchronous_ searches by default. This means the search request
-blocks other requests and waits for complete results before returning a
-response.
+runs _synchronous_ searches by default. This means the search request waits for
+complete results before returning a response.
 
 However, complete results can take longer for searches across:
 
@@ -492,6 +491,7 @@ API returns a response that includes:
 * An `is_partial` value of `true`, indicating the response does not contain
   complete search results.
 * An `is_running` value of `true`, indicating the search is async and ongoing.
+* Partial search results, if available, in the `hits` property.
 
 The async search continues to run in the background without blocking
 other requests.
@@ -503,7 +503,7 @@ The following request searches the `frozen_sec_logs` index, which has been
 <<frozen-indices,frozen>> for storage and is rarely searched.
 
 Because searches on frozen indices are expected to take longer to complete, the
-request contains a `wait_for_completion_timeout` query parameter value of `2s`
+request contains a `wait_for_completion_timeout` parameter value of `2s`
 (two seconds).
 
 If the request does not return complete results in two seconds, the search
@@ -520,9 +520,10 @@ GET /frozen_sec_logs/_eql/search
 }
 ----
 // TEST[s/frozen_sec_logs/sec_logs/]
-// TEST[s/"wait_for_completion_timeout": "2s"/"wait_for_completion_timeout": "2s"/]
 
-After two seconds, the request returns the following response.
+After two seconds, the request returns the following response. Note the
+`is_partial` and `is_running` properties are `true`, indicating an ongoing async
+search.
 
 [source,console-result]
 ----
@@ -532,63 +533,56 @@ After two seconds, the request returns the following response.
   "is_running": true,
   "took": 2000,
   "timed_out": false,
-  "hits": {
-    "total": {
-      "value": 2,
-      "relation": "eq"
-    },
-    "events": [
-      {
-        "_index": "frozen_sec_logs",
-        "_id": "1",
-        "_score": null,
-        "_source": {
-          "@timestamp": "2020-12-06T11:04:05.000Z",
-          "agent": {
-            "id": "8a4f500d"
-          },
-          "event": {
-            "category": "process"
-          },
-          "process": {
-            "name": "cmd.exe",
-            "path": "C:\\Windows\\System32\\cmd.exe"
-          }
-        },
-        "sort": [
-          1607252645000
-        ]
-      },
-      {
-        "_index": "frozen_sec_logs",
-        "_id": "3",
-        "_score": null,
-        "_source": {
-          "@timestamp": "2020-12-07T11:06:07.000Z",
-          "agent": {
-            "id": "8a4f500d"
-          },
-          "event": {
-            "category": "process"
-          },
-          "process": {
-            "name": "cmd.exe",
-            "path": "C:\\Windows\\System32\\cmd.exe"
-          }
-        },
-        "sort": [
-          1607339167000
-        ]
-      }
-    ]
-  }
+  "hits": ...
 }
 ----
 // TESTRESPONSE[s/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=/$body.id/]
 // TESTRESPONSE[s/"is_partial": true/"is_partial": $body.is_partial/]
 // TESTRESPONSE[s/"is_running": true/"is_running": $body.is_running/]
 // TESTRESPONSE[s/"took": 2000/"took": $body.took/]
+// TESTRESPONSE[s/"hits": \.\.\./"hits": $body.hits/]
+====
+
+You can use the the returned search ID and the <<get-async-eql-search-api,get
+async EQL search API>> to check the progress of an ongoing async search.
+
+The get async EQL search API also accepts a `wait_for_completion_timeout` query
+parameter. Set the `wait_for_completion_timeout` parameter to a duration you'd
+like to wait for complete search results. If the search does not finish during
+this period, partial search results, if available, are returned.
+
+[%collapsible]
+.*Example*
+====
+The following get async EQL search API request checks the progress of the
+previous async EQL search. The request specifies a `wait_for_completion_timeout`
+query parameter value of `2s` (two seconds).
+
+[source,console]
+----
+GET /_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=2s
+----
+// TEST[skip: no access to search ID]
+
+The request returns the following response. Note the `is_partial` and
+`is_running` properties are `false`, indicating the async EQL search has
+finished and the search results in the `hits` property are complete.
+
+[source,console-result]
+----
+{
+  "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
+  "is_partial": false,
+  "is_running": false,
+  "took": 2000,
+  "timed_out": false,
+  "hits": ...
+}
+----
+// TESTRESPONSE[s/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=/$body.id/]
+// TESTRESPONSE[s/"took": 2000/"took": $body.took/]
 // TESTRESPONSE[s/"_index": "frozen_sec_logs"/"_index": "sec_logs"/]
+// TESTRESPONSE[s/"hits": \.\.\./"hits": $body.hits/]
 ====
 
 [discrete]
@@ -598,10 +592,11 @@ After two seconds, the request returns the following response.
 By default, the EQL search API only stores async searches and their results for
 five days. After this period, any ongoing searches or saved results are deleted.
 
-You can use the `keep_alive` parameter to change the duration of this period.
+You can use the EQL search API's `keep_alive` parameter to change the duration
+of this period.
 
-[%collapsible]
 .*Example*
+[%collapsible]
 ====
 In the following EQL search API request, the `keep_alive` parameter is `2d` (two
 days). This means that if the search becomes async, its results
@@ -621,6 +616,24 @@ GET /sec_logs/_eql/search
 ----
 ====
 
+You can use the <<get-async-eql-search-api,get async EQL search API>>'s
+`keep_alive` query parameter to later change the retention period. The new
+retention period starts after the get async EQL search API request executes.
+
+.*Example*
+[%collapsible]
+====
+The following get async EQL search API request sets the `keep_alive` query
+parameter to `5d` (five days). The async search and its results are deleted five
+days after the get async EQL search API request executes.
+
+[source,console]
+----
+GET /_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?keep_alive=5d
+----
+// TEST[skip: no access to search ID]
+====
+
 [discrete]
 [[eql-search-store-sync-eql-search]]
 === Store synchronous EQL searches
@@ -651,8 +664,35 @@ GET /sec_logs/_eql/search
   """
 }
 ----
-====
 
+The API returns the following response. Note that a search ID is provided in the
+`id` property. The `is_partial` and `is_running` properties are `false`,
+indicating the EQL search was synchronous and returned complete search results.
+
+[source,console-result]
+----
+{
+  "id": "FjlmbndxNmJjU0RPdExBTGg0elNOOEEaQk9xSjJBQzBRMldZa1VVQ2pPa01YUToxMDY=",
+  "is_partial": false,
+  "is_running": false,
+  "took": 52,
+  "timed_out": false,
+  "hits": ...
+}
+----
+// TESTRESPONSE[s/FjlmbndxNmJjU0RPdExBTGg0elNOOEEaQk9xSjJBQzBRMldZa1VVQ2pPa01YUToxMDY=/$body.id/]
+// TESTRESPONSE[s/"took": 52/"took": $body.took/]
+// TESTRESPONSE[s/"hits": \.\.\./"hits": $body.hits/]
+
+You can use the search ID and the <<get-async-eql-search-api,get async EQL
+search API>> to retrieve the same results later.
+
+[source,console]
+----
+GET /_eql/search/FjlmbndxNmJjU0RPdExBTGg0elNOOEEaQk9xSjJBQzBRMldZa1VVQ2pPa01YUToxMDY=
+----
+// TEST[skip: no access to search ID]
+====
 
 [discrete]
 [[eql-search-case-sensitive]]

docs/reference/search.asciidoc

@@ -168,6 +168,8 @@ ifdef::permanently-unreleased-branch[]
 
 include::eql/eql-search-api.asciidoc[]
 
+include::eql/get-async-eql-search-api.asciidoc[]
+
 endif::[]
 
 include::search/count.asciidoc[]