-
Notifications
You must be signed in to change notification settings - Fork 24.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
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 Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
- Loading branch information
1 parent
b9b5380
commit 9a18504
Showing
9 changed files
with
319 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
41 changes: 41 additions & 0 deletions
41
docs/reference/sql/apis/delete-async-sql-search-api.asciidoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
67 changes: 67 additions & 0 deletions
67
docs/reference/sql/apis/get-async-sql-search-status-api.asciidoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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[] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
31 changes: 31 additions & 0 deletions
31
rest-api-spec/src/main/resources/rest-api-spec/api/sql.delete_async.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" | ||
} | ||
} | ||
} | ||
] | ||
} | ||
} | ||
} |
51 changes: 51 additions & 0 deletions
51
rest-api-spec/src/main/resources/rest-api-spec/api/sql.get_async.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" | ||
} | ||
} | ||
} | ||
} |
31 changes: 31 additions & 0 deletions
31
rest-api-spec/src/main/resources/rest-api-spec/api/sql.get_async_status.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" | ||
} | ||
} | ||
} | ||
] | ||
} | ||
} | ||
} |