[DOCS] Document async SQL APIs (elastic#75078)

jrodewig · elasticsearchmachine · commit 610dde061d42 · 2021-07-12T14:13:44.000Z
Adds formal API docs and JSON specs for the following APIs: * Get async SQL search * Get async SQL search status * Delete async SQL search Closes elastic#74845
diff --git a/docs/reference/rest-api/index.asciidoc b/docs/reference/rest-api/index.asciidoc
@@ -41,6 +41,7 @@ not be included yet.
 * <<security-api,Security APIs>>
 * <<snapshot-restore-apis,Snapshot and restore APIs>>
 * <<snapshot-lifecycle-management-api,Snapshot lifecycle management APIs>>
+* <<sql-apis,SQL APIs>>
 * <<transform-apis,{transform-cap} APIs>>
 * <<usage-api,Usage API>>
 * <<watcher-api,Watcher APIs>>
@@ -77,6 +78,7 @@ include::{es-repo-dir}/searchable-snapshots/apis/searchable-snapshots-apis.ascii
 include::{xes-repo-dir}/rest-api/security.asciidoc[]
 include::{es-repo-dir}/snapshot-restore/apis/snapshot-restore-apis.asciidoc[]
 include::{es-repo-dir}/slm/apis/slm-api.asciidoc[]
+include::{es-repo-dir}/sql/apis/sql-apis.asciidoc[]
 include::{es-repo-dir}/transform/apis/index.asciidoc[]
 include::usage.asciidoc[]
 include::{xes-repo-dir}/rest-api/watcher.asciidoc[]
diff --git a/docs/reference/sql/apis/delete-async-sql-search-api.asciidoc b/docs/reference/sql/apis/delete-async-sql-search-api.asciidoc
@@ -0,0 +1,41 @@
+[role="xpack"]
+[testenv="basic"]
+[[delete-async-sql-search-api]]
+=== Delete async SQL search API
+++++
+<titleabbrev>Delete async SQL search</titleabbrev>
+++++
+
+Deletes an <<sql-async,async SQL search>> or a <<sql-store-searches,stored
+synchronous SQL search>>. If the search is still running, the API cancels it.
+
+[source,console]
+----
+DELETE /_sql/async/delete/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=
+----
+// TEST[skip: no access to search ID]
+
+[[delete-async-sql-search-api-request]]
+==== {api-request-title}
+
+`DELETE /_sql/async/delete/<search_id>`
+
+[[delete-async-sql-search-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, only the following users can
+use this API to delete a search:
+
+** Users with the `cancel_task` <<privileges-list-cluster,cluster privilege>>
+** The user who first submitted the search
+
+[[delete-async-sql-search-api-limitations]]
+===== Limitations
+
+See <<sql-limitations>>.
+
+[[delete-async-sql-search-api-path-params]]
+==== {api-path-parms-title}
+
+`<search_id>`::
+(Required, string) Identifier for the search.
diff --git a/docs/reference/sql/apis/get-async-sql-search-api.asciidoc b/docs/reference/sql/apis/get-async-sql-search-api.asciidoc
@@ -0,0 +1,64 @@
+[role="xpack"]
+[testenv="basic"]
+[[get-async-sql-search-api]]
+=== Get async SQL search API
+++++
+<titleabbrev>Get async SQL search</titleabbrev>
+++++
+
+Returns results for an <<sql-async,async SQL search>> or a
+<<sql-store-searches,stored synchronous SQL search>>.
+
+[source,console]
+----
+GET _sql/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=?format=json
+----
+// TEST[skip: no access to search ID]
+
+[[get-async-sql-search-api-request]]
+==== {api-request-title}
+
+`GET _sql/async/<search_id>`
+
+[[get-async-sql-search-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, only the user who first submitted
+the SQL search can retrieve the search using this API.
+
+[[get-async-sql-search-api-limitations]]
+===== Limitations
+
+See <<sql-limitations>>.
+
+[[get-async-sql-search-api-path-params]]
+==== {api-path-parms-title}
+
+`<search_id>`::
+(Required, string) Identifier for the search.
+
+[[get-async-sql-search-api-query-params]]
+==== {api-query-parms-title}
+
+`delimiter`::
+(Optional, string) Separator for CSV results. Defaults to `,`. The API only
+supports this parameter for CSV responses.
+
+`format`::
+(Required, string) Format for the response. You must specify a format using this
+parameter or the `Accept` HTTP header. If you specify both, the API uses this
+parameter. For valid values, see <<sql-rest-format>>.
+
+`keep_alive`::
+(Optional, <<time-units,time value>>) Retention period for the search and its
+results. Defaults to the `keep_alive` period for the original SQL search.
+
+`wait_for_completion_timeout`::
+(Optional, <<time-units,time value>>) Period to wait for complete results.
+Defaults to no timeout, meaning the request waits for complete search results.
+
+[[get-async-sql-search-api-response-body]]
+==== {api-response-body-title}
+
+The get async SQL search API returns the same response body as the SQL search
+API.
diff --git a/docs/reference/sql/apis/get-async-sql-search-status-api.asciidoc b/docs/reference/sql/apis/get-async-sql-search-status-api.asciidoc
@@ -0,0 +1,67 @@
+[role="xpack"]
+[testenv="basic"]
+[[get-async-sql-search-status-api]]
+=== Get async SQL search status API
+++++
+<titleabbrev>Get async SQL search status</titleabbrev>
+++++
+
+Returns the current status of an <<sql-async,async SQL search>> or a
+<<sql-store-searches,stored synchronous SQL search>>.
+
+[source,console]
+----
+GET _sql/async/status/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=?format=json
+----
+// TEST[skip: no access to search ID]
+
+[[get-async-sql-search-status-api-request]]
+==== {api-request-title}
+
+`GET _sql/async/status/<search_id>`
+
+[[get-async-sql-search-status-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `monitor`
+<<privileges-list-cluster,cluster privilege>> to use this API.
+
+[[get-async-sql-search-status-api-limitations]]
+===== Limitations
+
+See <<sql-limitations>>.
+
+[[get-async-sql-search-status-api-path-params]]
+==== {api-path-parms-title}
+
+`<search_id>`::
+(Required, string) Identifier for the search.
+
+[role="child_attributes"]
+[[get-async-sql-search-status-api-response-body]]
+==== {api-response-body-title}
+
+`id`::
+(string) Identifier for the search.
+
+`is_running`::
+(Boolean) If `true`, the search is still running. If `false`, the
+search has finished.
+
+`is_partial`::
+(Boolean) If `true`, the response does not contain complete search results. If
+`is_partial` is `true` and `is_running` is `true`, the search is still running.
+If `is_partial` is `true` but `is_running` is `false`, the results are partial
+due to a failure or timeout.
+
+`start_time_in_millis`::
+(integer) Timestamp, in milliseconds since the Unix epoch, when the search
+started. The API only returns this property for running searches.
+
+`expiration_time_in_millis`::
+(integer) Timestamp, in milliseconds since the Unix epoch, when {es} will delete
+the search and its results, even if the search is still running.
+
+`completion_status`::
+(integer) HTTP status code for the search. The API only returns this property
+for completed searches.
diff --git a/docs/reference/sql/apis/sql-apis.asciidoc b/docs/reference/sql/apis/sql-apis.asciidoc
@@ -0,0 +1,19 @@
+[role="xpack"]
+[testenv="basic"]
+[[sql-apis]]
+== SQL APIs
+
+NOTE: This list of SQL APIs is incomplete. We're working to add more.
+
+{es}'s SQL APIs let you run SQL queries on {es} indices and data streams.
+For an overview of {es}'s SQL features and related tutorials, see <<xpack-sql>>.
+
+* <<get-async-sql-search-api>>
+* <<get-async-sql-search-status-api>>
+* <<delete-async-sql-search-api>>
+
+include::delete-async-sql-search-api.asciidoc[]
+
+include::get-async-sql-search-api.asciidoc[]
+
+include::get-async-sql-search-status-api.asciidoc[]
diff --git a/docs/reference/sql/endpoints/rest.asciidoc b/docs/reference/sql/endpoints/rest.asciidoc
@@ -610,8 +610,8 @@ For CSV, TSV, and TXT responses, the API returns these values in the respective
 // TESTRESPONSE[s/"is_partial": true/"is_partial": $body.is_partial/]
 // TESTRESPONSE[s/"is_running": true/"is_running": $body.is_running/]
 
-To check the progress of an async search, use the search ID with the get async
-SQL search status API.
+To check the progress of an async search, use the search ID with the
+<<get-async-sql-search-status-api,get async SQL search status API>>.
 
 [source,console]
 ----
@@ -636,9 +636,10 @@ complete results.
 // TESTRESPONSE[s/FnR0TDhyWUVmUmVtWXRWZER4MXZiNFEad2F5UDk2ZVdTVHV1S0xDUy00SklUdzozMTU=/$body.id/]
 // TESTRESPONSE[s/"expiration_time_in_millis": 1611690295000/"expiration_time_in_millis": $body.expiration_time_in_millis/]
 
-To get the results, use the search ID with the get async SQL search API. If the
-search is still running, specify how long you’d like to wait using
-`wait_for_completion_timeout`. You can also specify the response `format`.
+To get the results, use the search ID with the <<get-async-sql-search-api,get
+async SQL search API>>. If the search is still running, specify how long you’d
+like to wait using `wait_for_completion_timeout`. You can also specify the
+response `format`.
 
 [source,console]
 ----
@@ -676,8 +677,9 @@ GET _sql/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxO
 ----
 // TEST[skip: no access to search ID]
 
-Use the delete async SQL search API to delete an async search before the
-`keep_alive` period ends. If the search is still running, {es} cancels it.
+Use the <<delete-async-sql-search-api,delete async SQL search API>> to delete an
+async search before the `keep_alive` period ends. If the search is still
+running, {es} cancels it.
 
 [source,console]
 ----
@@ -725,12 +727,13 @@ returned complete results.
 // TESTRESPONSE[s/"columns": \.\.\./"columns": $body.columns/]
 // TESTRESPONSE[s/"cursor": \.\.\./"cursor": $body.cursor/]
 
-You can get the same results later using the search ID with the get async SQL
-search API.
+You can get the same results later using the search ID with the
+<<get-async-sql-search-api,get async SQL search API>>.
 
 Saved synchronous searches are still subject to the `keep_alive` retention
 period. When this period ends, {es} deletes the search results. You can also
-delete saved searches using the delete async SQL search API.
+delete saved searches using the <<delete-async-sql-search-api,delete async SQL
+search API>>.
 
 [[sql-rest-fields]]
 === Supported REST parameters
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/sql.delete_async.json b/rest-api-spec/src/main/resources/rest-api-spec/api/sql.delete_async.json
@@ -0,0 +1,31 @@
+{
+  "sql.delete_async": {
+    "documentation": {
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/delete-async-sql-search-api.html",
+      "description": "Deletes an async SQL search or a stored synchronous SQL search. If the search is still running, the API cancels it."
+    },
+    "stability": "stable",
+    "visibility": "public",
+    "headers": {
+      "accept": [
+        "application/json"
+      ]
+    },
+    "url": {
+      "paths": [
+        {
+          "path": "/_sql/async/delete/{id}",
+          "methods": [
+            "DELETE"
+          ],
+          "parts": {
+            "id": {
+              "type": "string",
+              "description": "The async search ID"
+            }
+          }
+        }
+      ]
+    }
+  }
+}
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/sql.get_async.json b/rest-api-spec/src/main/resources/rest-api-spec/api/sql.get_async.json
@@ -0,0 +1,51 @@
+{
+  "sql.get_async": {
+    "documentation": {
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/get-async-sql-search-api.html",
+      "description": "Returns the current status and available results for an async SQL search or stored synchronous SQL search"
+    },
+    "stability": "stable",
+    "visibility": "public",
+    "headers": {
+      "accept": [
+        "application/json"
+      ]
+    },
+    "url": {
+      "paths": [
+        {
+          "path": "/_sql/async/{id}",
+          "methods": [
+            "GET"
+          ],
+          "parts": {
+            "id": {
+              "type": "string",
+              "description": "The async search ID"
+            }
+          }
+        }
+      ]
+    },
+    "params": {
+      "delimiter": {
+        "type": "string",
+        "description": "Separator for CSV results",
+        "default": ","
+      },
+      "format": {
+        "type": "string",
+        "description": "Short version of the Accept header, e.g. json, yaml"
+      },
+      "keep_alive": {
+        "type": "time",
+        "description": "Retention period for the search and its results",
+        "default": "5d"
+      },
+      "wait_for_completion_timeout": {
+        "type": "time",
+        "description": "Duration to wait for complete results"
+      }
+    }
+  }
+}
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/sql.get_async_status.json b/rest-api-spec/src/main/resources/rest-api-spec/api/sql.get_async_status.json
@@ -0,0 +1,31 @@
+{
+  "sql.get_async_status": {
+    "documentation": {
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/get-async-sql-search-status-api.html",
+      "description": "Returns the current status of an async SQL search or a stored synchronous SQL search"
+    },
+    "stability": "stable",
+    "visibility": "public",
+    "headers": {
+      "accept": [
+        "application/json"
+      ]
+    },
+    "url": {
+      "paths": [
+        {
+          "path": "/_sql/async/status/{id}",
+          "methods": [
+            "GET"
+          ],
+          "parts": {
+            "id": {
+              "type": "string",
+              "description": "The async search ID"
+            }
+          }
+        }
+      ]
+    }
+  }
+}
