From 610dde061d426ef8f115effec3d099f768aedbc5 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Mon, 12 Jul 2021 10:12:02 -0400 Subject: [PATCH] [DOCS] Document async SQL APIs (#75078) 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 #74845 --- docs/reference/rest-api/index.asciidoc | 2 + .../apis/delete-async-sql-search-api.asciidoc | 41 ++++++++++++ .../apis/get-async-sql-search-api.asciidoc | 64 ++++++++++++++++++ .../get-async-sql-search-status-api.asciidoc | 67 +++++++++++++++++++ docs/reference/sql/apis/sql-apis.asciidoc | 19 ++++++ docs/reference/sql/endpoints/rest.asciidoc | 23 ++++--- .../rest-api-spec/api/sql.delete_async.json | 31 +++++++++ .../rest-api-spec/api/sql.get_async.json | 51 ++++++++++++++ .../api/sql.get_async_status.json | 31 +++++++++ 9 files changed, 319 insertions(+), 10 deletions(-) create mode 100644 docs/reference/sql/apis/delete-async-sql-search-api.asciidoc create mode 100644 docs/reference/sql/apis/get-async-sql-search-api.asciidoc create mode 100644 docs/reference/sql/apis/get-async-sql-search-status-api.asciidoc create mode 100644 docs/reference/sql/apis/sql-apis.asciidoc create mode 100644 rest-api-spec/src/main/resources/rest-api-spec/api/sql.delete_async.json create mode 100644 rest-api-spec/src/main/resources/rest-api-spec/api/sql.get_async.json create mode 100644 rest-api-spec/src/main/resources/rest-api-spec/api/sql.get_async_status.json diff --git a/docs/reference/rest-api/index.asciidoc b/docs/reference/rest-api/index.asciidoc index 934e296272cff..19338d667e3c6 100644 --- a/docs/reference/rest-api/index.asciidoc +++ b/docs/reference/rest-api/index.asciidoc @@ -41,6 +41,7 @@ not be included yet. * <> * <> * <> +* <> * <> * <> * <> @@ -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 new file mode 100644 index 0000000000000..48f1f32e5253d --- /dev/null +++ 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 +++++ +Delete async SQL search +++++ + +Deletes an <> or a <>. 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/` + +[[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` <> +** The user who first submitted the search + +[[delete-async-sql-search-api-limitations]] +===== Limitations + +See <>. + +[[delete-async-sql-search-api-path-params]] +==== {api-path-parms-title} + +``:: +(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 new file mode 100644 index 0000000000000..59ab886017f34 --- /dev/null +++ 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 +++++ +Get async SQL search +++++ + +Returns results for an <> or a +<>. + +[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/` + +[[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 <>. + +[[get-async-sql-search-api-path-params]] +==== {api-path-parms-title} + +``:: +(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 <>. + +`keep_alive`:: +(Optional, <>) Retention period for the search and its +results. Defaults to the `keep_alive` period for the original SQL search. + +`wait_for_completion_timeout`:: +(Optional, <>) 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 new file mode 100644 index 0000000000000..7d4d3b3086927 --- /dev/null +++ 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 +++++ +Get async SQL search status +++++ + +Returns the current status of an <> or a +<>. + +[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/` + +[[get-async-sql-search-status-api-prereqs]] +==== {api-prereq-title} + +* If the {es} {security-features} are enabled, you must have the `monitor` +<> to use this API. + +[[get-async-sql-search-status-api-limitations]] +===== Limitations + +See <>. + +[[get-async-sql-search-status-api-path-params]] +==== {api-path-parms-title} + +``:: +(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 new file mode 100644 index 0000000000000..aed82905de4b7 --- /dev/null +++ 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 <>. + +* <> +* <> +* <> + +include::delete-async-sql-search-api.asciidoc[] + +include::get-async-sql-search-api.asciidoc[] + +include::get-async-sql-search-status-api.asciidoc[] \ No newline at end of file diff --git a/docs/reference/sql/endpoints/rest.asciidoc b/docs/reference/sql/endpoints/rest.asciidoc index 9835b8f1be47d..e336872b219ed 100644 --- 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 +<>. [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 <>. 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 <> 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 +<>. 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 <>. [[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 new file mode 100644 index 0000000000000..1a2a6f6c4c052 --- /dev/null +++ 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 new file mode 100644 index 0000000000000..d0a5a3c565a18 --- /dev/null +++ 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 new file mode 100644 index 0000000000000..d433063d93c85 --- /dev/null +++ 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" + } + } + } + ] + } + } +}