elastic · spong · Feb 6, 2024
@@ -0,0 +1,20 @@
+[[esql-apis]]
+== {esql} APIs
+
+The {es} Query Language ({esql}) provides a powerful way to filter, transform,
+and analyze data stored in {es}, and in the future in other runtimes. For an
+overview of {esql} and related tutorials, see <<esql>>.
+
+* <<esql-query-api>>
+* <<esql-async-query-api>>
+* <<esql-async-query-get-api>>
+* <<esql-async-query-delete-api>>
+
+
+include::esql-query-api.asciidoc[]
+
+include::esql-async-query-api.asciidoc[]
+
+include::esql-async-query-get-api.asciidoc[]
+
+include::esql-async-query-delete-api.asciidoc[]
@@ -0,0 +1,165 @@
+[[esql-async-query-api]]
+=== {esql} async query API
+++++
+<titleabbrev>{esql} async query API</titleabbrev>
+++++
+
+Runs an async <<esql,{esql} query>>.
+
+The async query API lets you asynchronously execute a query request,
+monitor its progress, and retrieve results when they become available.
+
+The API accepts the same parameters and request body as the synchronous
+<<esql-query-api,query API>>, along with additional async related
+properties as outlined below.
+
+[source,console]
+----
+POST /_query/async
+{
+  "query": """
+    FROM library
+    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
+    | STATS MAX(page_count) BY year
+    | SORT year
+    | LIMIT 5
+  """,
+  "wait_for_completion_timeout": "2s"
+}
+----
+// TEST[setup:library]
+
+If the results are not available within the given timeout period, 2 seconds
+in this case, no results are returned but rather a response that
+includes:
+
+ * A query ID
+ * An `is_running` value of _true_, indicating the query is ongoing
+
+The query continues to run in the background without blocking other
+requests.
+
+[source,console-result]
+----
+{
+  "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
+  "is_running": true
+}
+----
+// TEST[skip: no access to query ID - may return response values]
+
+Otherwise, if the response's `is_running` value is `false`, the async
+query has finished and the results are returned.
+
+[source,console-result]
+----
+{
+  "is_running": false,
+  "columns": ...
+}
+----
+// TEST[skip: no access to query ID - may return response values]
+
+[[esql-async-query-api-request]]
+==== {api-request-title}
+
+`POST /_query/async`
+
+[[esql-async-query-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `read`
+<<privileges-list-indices,index privilege>> for the data stream, index,
+or alias you query.
+
+[[esql-async-query-api-path-params]]
+==== {api-path-parms-title}
+
+The API accepts the same parameters as the synchronous
+<<esql-query-api-query-params,query API>>.
+
+[[esql-async-query-api-request-body]]
+==== {api-request-body-title}
+
+The API accepts the same request body as the synchronous
+<<esql-query-api-request-body,query API>>, along with the following
+parameters:
+
+[[esql-async-query-api-wait-for-completion-timeout]]
+`wait_for_completion_timeout`::
++
+--
+(Optional, <<time-units,time value>>)
+Timeout duration to wait for the request to finish. Defaults to a 1 second,
+meaning the request waits for 1 second for the query results.
+
+If the query completes during this period then results will be
+returned. Otherwise, a query `id` is returned that can later be used to
+retrieve the results.
+
+If the request does not complete during this period, a query
+<<esql-async-query-api-response-body-query-id,id>> is returned.
+--
+
+[[esql-async-query-api-keep-on-completion]]
+`keep_on_completion`::
++
+--
+(Optional, Boolean)
+If `true`, the query and its results are stored in the cluster.
+
+If `false`, the query and its results are stored in the cluster only if the
+request does not complete during the period set by the
+<<esql-async-query-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
+parameter. Defaults to `false`.
+--
+
+`keep_alive`::
++
+--
+(Optional, <<time-units,time value>>)
+Period for which the query and its results are stored in the cluster. Defaults
+to `5d` (five days).
+
+When this period expires, the query and its results are deleted, even if the
+query is still ongoing.
+
+If the <<esql-async-query-api-keep-on-completion,`keep_on_completion`>> parameter
+is `false`, {es} only stores async queries that do not complete within the period
+set by the <<esql-async-query-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
+parameter, regardless of this value.
+--
+
+[[esql-async-query-api-response-body]]
+==== {api-response-body-title}
+
+The API returns the same response body as the synchronous
+<<esql-query-api-response-body,query API>>, along with the following
+properties:
+
+[[esql-async-query-api-response-body-query-id]]
+`id`::
++
+--
+(string)
+Identifier for the query.
+
+This query ID is only provided if one of the following conditions is met:
+
+* A query request does not return complete results during the
+<<esql-async-query-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
+parameter's timeout period.
+
+* The query request's <<esql-async-query-api-keep-on-completion,`keep_on_completion`>>
+parameter is `true`.
+
+You can use this ID with the <<esql-async-query-get-api,{esql} async query get
+API>> to get the current status and available results for the query.
+--
+
+`is_running`::
++
+--
+(Boolean)
+If `true`, the query request is still executing.
+--
@@ -0,0 +1,42 @@
+[[esql-async-query-delete-api]]
+=== {esql} async query delete API
+++++
+<titleabbrev>{esql} async query delete API</titleabbrev>
+++++
+
+The {esql} async query delete API is used to manually delete an async query
+by ID. If the query is still running, the query will be cancelled. Otherwise,
+the stored results are deleted.
+
+[source,console]
+----
+DELETE /query/async/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=
+----
+// TEST[skip: no access to query ID]
+
+[[esql-async-query-delete-api-request]]
+==== {api-request-title}
+
+`DELETE /_query/async/<query_id>`
+
+[[esql-async-query-delete-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, only the following users can
+use this API to delete a query:
+
+** The authenticated user that submitted the original query request
+** Users with the `cancel_task` <<privileges-list-cluster,cluster privilege>>
+
+
+[[esql-async-query-delete-api-path-params]]
+==== {api-path-parms-title}
+
+`<query_id>`::
+(Required, string)
+Identifier for the query to delete.
++
+A query ID is provided in the <<esql-async-query-api,{esql} async query API>>'s
+response for a query that does not complete in the awaited time. A query ID is
+also provided if the request's <<esql-async-query-api-keep-on-completion,`keep_on_completion`>>
+parameter is `true`.
@@ -0,0 +1,58 @@
+[[esql-async-query-get-api]]
+=== {esql} async query get API
+++++
+<titleabbrev>{esql} async query get API</titleabbrev>
+++++
+
+Returns the current status and available results for an <<esql-async-query-api,{esql}
+async query>> or a stored results.
+
+[source,console]
+----
+GET /_query/async/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=
+----
+// TEST[skip: no access to query ID]
+
+[[esql-async-query-get-api-request]]
+==== {api-request-title}
+
+`GET /_query/async/<query_id>`
+
+[[esql-async-query-get-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, only the user who first submitted
+the {esql} query can retrieve the results using this API.
+
+[[esql-async-query-get-api-path-params]]
+==== {api-path-parms-title}
+
+`<query_id>`::
+(Required, string)
+Identifier for the query.
++
+A query ID is provided in the <<esql-async-query-api,{esql} async query API>>'s
+response for a query that does not complete in the awaited time. A query ID is
+also provided if the request's <<esql-async-query-api-keep-on-completion,`keep_on_completion`>>
+parameter is `true`.
+
+[[esql-async-query-get-api-query-params]]
+==== {api-query-parms-title}
+
+`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 query results.
++
+If this parameter is specified and the request completes during this period,
+complete query results are returned.
++
+If the request does not complete during this period, the response returns an
+`is_running` value of `true` and no results.
+
+[[esql-async-query-get-api-response-body]]
+==== {api-response-body-title}
+
+The {esql} async query get API returns the same response body as the {esql}
+query API. See the {esql} query API's <<esql-query-api-response-body,response
+body parameters>>.
@@ -5,6 +5,7 @@
 <titleabbrev>Commands</titleabbrev>
 ++++
 
+[[esql-source-commands]]
 // tag::source_commands[]
 ==== Source commands
 
@@ -20,6 +21,7 @@ image::images/esql/source-command.svg[A source command producing a table from {e
 
 // end::source_command[]
 
+[[esql-processing-commands]]
 // tag::proc_commands[]
 ==== Processing commands