From ab13d850dee8dc170104b175a14035e7bdd5af3e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 9 Jan 2025 12:13:32 -0800 Subject: [PATCH] Add SQL API examples (#3479) (#3503) Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> (cherry picked from commit 28adc40486492649445daa94cdc6facea3fee902) Co-authored-by: Lisa Cawley --- output/openapi/elasticsearch-openapi.json | 142 +++---- .../elasticsearch-serverless-openapi.json | 142 +++---- output/schema/schema.json | 361 ++++++++++-------- output/typescript/types.ts | 21 +- specification/_doc_ids/table.csv | 11 +- .../sql/clear_cursor/ClearSqlCursorRequest.ts | 1 + .../ClearSqlCursorRequestExample1.yaml | 7 + .../sql/delete_async/SqlDeleteAsyncRequest.ts | 9 +- .../sql/get_async/SqlGetAsyncRequest.ts | 21 +- .../sql/get_async/SqlGetAsyncResponse.ts | 28 +- .../SqlGetAsyncStatusRequest.ts | 4 +- .../SqlGetAsyncStatusResponse.ts | 28 +- specification/sql/query/QuerySqlRequest.ts | 104 +++-- specification/sql/query/QuerySqlResponse.ts | 42 +- .../request/QuerySqlRequestExample1.yaml | 7 + .../sql/translate/TranslateSqlRequest.ts | 13 +- .../request/TranslateSqlRequestExample1.yaml | 7 + 17 files changed, 539 insertions(+), 409 deletions(-) create mode 100644 specification/sql/clear_cursor/examples/request/ClearSqlCursorRequestExample1.yaml create mode 100644 specification/sql/query/examples/request/QuerySqlRequestExample1.yaml create mode 100644 specification/sql/translate/examples/request/TranslateSqlRequestExample1.yaml diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 091c81fa68..2f95ae0917 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -34199,13 +34199,13 @@ "sql" ], "summary": "Delete an async SQL search", - "description": "Delete an async SQL search or a stored synchronous SQL search.\nIf the search is still running, the API cancels it.", + "description": "Delete an async SQL search or a stored synchronous SQL search.\nIf the search is still running, the API cancels it.\n\nIf the Elasticsearch security features are enabled, only the following users can use this API to delete a search:\n\n* Users with the `cancel_task` cluster privilege.\n* The user who first submitted the search.", "operationId": "sql-delete-async", "parameters": [ { "in": "path", "name": "id", - "description": "Identifier for the search.", + "description": "The identifier for the search.", "required": true, "deprecated": false, "schema": { @@ -34235,13 +34235,13 @@ "sql" ], "summary": "Get async SQL search results", - "description": "Get the current status and available results for an async SQL search or stored synchronous SQL search.", + "description": "Get the current status and available results for an async SQL search or stored synchronous SQL search.\n\nIf the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API.", "operationId": "sql-get-async", "parameters": [ { "in": "path", "name": "id", - "description": "Identifier for the search.", + "description": "The identifier for the search.", "required": true, "deprecated": false, "schema": { @@ -34252,7 +34252,7 @@ { "in": "query", "name": "delimiter", - "description": "Separator for CSV results. The API only supports this parameter for CSV responses.", + "description": "The separator for CSV results.\nThe API supports this parameter only for CSV responses.", "deprecated": false, "schema": { "type": "string" @@ -34262,7 +34262,7 @@ { "in": "query", "name": "format", - "description": "Format for the response. You must specify a format using this parameter or the\nAccept HTTP header. If you specify both, the API uses this parameter.", + "description": "The format for the response.\nYou must specify a format using this parameter or the `Accept` HTTP header.\nIf you specify both, the API uses this parameter.", "deprecated": false, "schema": { "type": "string" @@ -34272,7 +34272,7 @@ { "in": "query", "name": "keep_alive", - "description": "Retention period for the search and its results. Defaults\nto the `keep_alive` period for the original SQL search.", + "description": "The retention period for the search and its results.\nIt defaults to the `keep_alive` period for the original SQL search.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -34282,7 +34282,7 @@ { "in": "query", "name": "wait_for_completion_timeout", - "description": "Period to wait for complete results. Defaults to no timeout,\nmeaning the request waits for complete search results.", + "description": "The period to wait for complete results.\nIt defaults to no timeout, meaning the request waits for complete search results.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -34302,11 +34302,11 @@ "$ref": "#/components/schemas/_types:Id" }, "is_running": { - "description": "If `true`, the search is still running. If false, the search has finished.\nThis value is only returned for async and saved synchronous searches. For\nCSV, TSV, and TXT responses, this value is returned in the `Async-partial`\nHTTP header.", + "description": "If `true`, the search is still running.\nIf `false`, the search has finished.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", "type": "boolean" }, "is_partial": { - "description": "If `true`, the response does not contain complete search results. If `is_partial`\nis `true` and `is_running` is `true`, the search is still running. If `is_partial`\nis `true` but `is_running` is `false`, the results are partial due to a failure or\ntimeout. This value is only returned for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", + "description": "If `true`, the response does not contain complete search results.\nIf `is_partial` is `true` and `is_running` is `true`, the search is still running.\nIf `is_partial` is `true` but `is_running` is `false`, the results are partial due to a failure or timeout.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", "type": "boolean" }, "columns": { @@ -34317,11 +34317,11 @@ } }, "cursor": { - "description": "Cursor for the next set of paginated results. For CSV, TSV, and\nTXT responses, this value is returned in the `Cursor` HTTP header.", + "description": "The cursor for the next set of paginated results.\nFor CSV, TSV, and TXT responses, this value is returned in the `Cursor` HTTP header.", "type": "string" }, "rows": { - "description": "Values for the search results.", + "description": "The values for the search results.", "type": "array", "items": { "$ref": "#/components/schemas/sql:Row" @@ -34354,7 +34354,7 @@ { "in": "path", "name": "id", - "description": "Identifier for the search.", + "description": "The identifier for the search.", "required": true, "deprecated": false, "schema": { @@ -34371,34 +34371,34 @@ "schema": { "type": "object", "properties": { + "expiration_time_in_millis": { + "$ref": "#/components/schemas/_types:EpochTimeUnitMillis" + }, "id": { - "description": "Identifier for the search.", + "description": "The identifier for the search.", "type": "string" }, "is_running": { - "description": "If `true`, the search is still running. If `false`, the search has finished.", + "description": "If `true`, the search is still running.\nIf `false`, the search has finished.", "type": "boolean" }, "is_partial": { - "description": "If `true`, the response does not contain complete search results. If `is_partial`\nis `true` and `is_running` is `true`, the search is still running. If `is_partial`\nis `true` but `is_running` is `false`, the results are partial due to a failure or\ntimeout.", + "description": "If `true`, the response does not contain complete search results.\nIf `is_partial` is `true` and `is_running` is `true`, the search is still running.\nIf `is_partial` is `true` but `is_running` is `false`, the results are partial due to a failure or timeout.", "type": "boolean" }, "start_time_in_millis": { "$ref": "#/components/schemas/_types:EpochTimeUnitMillis" }, - "expiration_time_in_millis": { - "$ref": "#/components/schemas/_types:EpochTimeUnitMillis" - }, "completion_status": { "$ref": "#/components/schemas/_types:uint" } }, "required": [ + "expiration_time_in_millis", "id", "is_running", "is_partial", - "start_time_in_millis", - "expiration_time_in_millis" + "start_time_in_millis" ] } } @@ -34460,7 +34460,7 @@ "sql" ], "summary": "Translate SQL into Elasticsearch queries", - "description": "Translate an SQL search into a search API request containing Query DSL.", + "description": "Translate an SQL search into a search API request containing Query DSL.\nIt accepts the same request body parameters as the SQL search API, excluding `cursor`.", "operationId": "sql-translate-1", "requestBody": { "$ref": "#/components/requestBodies/sql.translate" @@ -34477,7 +34477,7 @@ "sql" ], "summary": "Translate SQL into Elasticsearch queries", - "description": "Translate an SQL search into a search API request containing Query DSL.", + "description": "Translate an SQL search into a search API request containing Query DSL.\nIt accepts the same request body parameters as the SQL search API, excluding `cursor`.", "operationId": "sql-translate", "requestBody": { "$ref": "#/components/requestBodies/sql.translate" @@ -95280,17 +95280,6 @@ "schema": { "type": "object", "properties": { - "id": { - "$ref": "#/components/schemas/_types:Id" - }, - "is_running": { - "description": "If `true`, the search is still running. If false, the search has finished.\nThis value is only returned for async and saved synchronous searches. For\nCSV, TSV, and TXT responses, this value is returned in the `Async-partial`\nHTTP header.", - "type": "boolean" - }, - "is_partial": { - "description": "If `true`, the response does not contain complete search results. If `is_partial`\nis `true` and `is_running` is `true`, the search is still running. If `is_partial`\nis `true` but `is_running` is `false`, the results are partial due to a failure or\ntimeout. This value is only returned for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", - "type": "boolean" - }, "columns": { "description": "Column headings for the search results. Each object is a column.", "type": "array", @@ -95299,11 +95288,22 @@ } }, "cursor": { - "description": "Cursor for the next set of paginated results. For CSV, TSV, and\nTXT responses, this value is returned in the `Cursor` HTTP header.", + "description": "The cursor for the next set of paginated results.\nFor CSV, TSV, and TXT responses, this value is returned in the `Cursor` HTTP header.", "type": "string" }, + "id": { + "$ref": "#/components/schemas/_types:Id" + }, + "is_running": { + "description": "If `true`, the search is still running.\nIf `false`, the search has finished.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", + "type": "boolean" + }, + "is_partial": { + "description": "If `true`, the response does not contain complete search results.\nIf `is_partial` is `true` and `is_running` is `true`, the search is still running.\nIf `is_partial` is `true` but `is_running` is `false`, the results are partial due to a failure or timeout.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", + "type": "boolean" + }, "rows": { - "description": "Values for the search results.", + "description": "The values for the search results.", "type": "array", "items": { "$ref": "#/components/schemas/sql:Row" @@ -104766,7 +104766,7 @@ "sql.query#format": { "in": "query", "name": "format", - "description": "Format for the response.", + "description": "The format for the response.\nYou can also specify a format using the `Accept` HTTP header.\nIf you specify both this parameter and the `Accept` HTTP header, this parameter takes precedence.", "deprecated": false, "schema": { "$ref": "#/components/schemas/sql.query:SqlFormat" @@ -107931,65 +107931,75 @@ "schema": { "type": "object", "properties": { + "allow_partial_search_results": { + "description": "If `true`, the response has partial results when there are shard request timeouts or shard failures.\nIf `false`, the API returns an error with no partial results.", + "type": "boolean" + }, "catalog": { - "description": "Default catalog (cluster) for queries. If unspecified, the queries execute on the data in the local cluster only.", + "description": "The default catalog (cluster) for queries.\nIf unspecified, the queries execute on the data in the local cluster only.", "type": "string" }, "columnar": { - "description": "If true, the results in a columnar fashion: one row represents all the values of a certain column from the current page of results.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-rest-columnar.html" + }, + "description": "If `true`, the results are in a columnar fashion: one row represents all the values of a certain column from the current page of results.\nThe API supports this parameter only for CBOR, JSON, SMILE, and YAML responses.", "type": "boolean" }, "cursor": { - "description": "Cursor used to retrieve a set of paginated results.\nIf you specify a cursor, the API only uses the `columnar` and `time_zone` request body parameters.\nIt ignores other request body parameters.", + "description": "The cursor used to retrieve a set of paginated results.\nIf you specify a cursor, the API only uses the `columnar` and `time_zone` request body parameters.\nIt ignores other request body parameters.", "type": "string" }, "fetch_size": { - "description": "The maximum number of rows (or entries) to return in one response", + "description": "The maximum number of rows (or entries) to return in one response.", "type": "number" }, + "field_multi_value_leniency": { + "description": "If `false`, the API returns an exception when encountering multiple values for a field.\nIf `true`, the API is lenient and returns the API returns the first value from the array with no guarantee of consistent results.", + "type": "boolean" + }, "filter": { "$ref": "#/components/schemas/_types.query_dsl:QueryContainer" }, - "query": { - "description": "SQL query to run.", - "type": "string" - }, - "request_timeout": { - "$ref": "#/components/schemas/_types:Duration" + "index_using_frozen": { + "description": "If `true`, the search can run on frozen indices.", + "type": "boolean" }, - "page_timeout": { + "keep_alive": { "$ref": "#/components/schemas/_types:Duration" }, - "time_zone": { - "$ref": "#/components/schemas/_types:TimeZone" - }, - "field_multi_value_leniency": { - "description": "Throw an exception when encountering multiple values for a field (default) or be lenient and return the first value from the list (without any guarantees of what that will be - typically the first in natural ascending order).", + "keep_on_completion": { + "description": "If `true`, Elasticsearch stores synchronous searches if you also specify the `wait_for_completion_timeout` parameter.\nIf `false`, Elasticsearch only stores async searches that don't finish before the `wait_for_completion_timeout`.", "type": "boolean" }, - "runtime_mappings": { - "$ref": "#/components/schemas/_types.mapping:RuntimeFields" - }, - "wait_for_completion_timeout": { + "page_timeout": { "$ref": "#/components/schemas/_types:Duration" }, "params": { - "description": "Values for parameters in the query.", + "description": "The values for parameters in the query.", "type": "object", "additionalProperties": { "type": "object" } }, - "keep_alive": { + "query": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-spec.html" + }, + "description": "The SQL query to run.", + "type": "string" + }, + "request_timeout": { "$ref": "#/components/schemas/_types:Duration" }, - "keep_on_completion": { - "description": "If true, Elasticsearch stores synchronous searches if you also specify the wait_for_completion_timeout parameter. If false, Elasticsearch only stores async searches that don’t finish before the wait_for_completion_timeout.", - "type": "boolean" + "runtime_mappings": { + "$ref": "#/components/schemas/_types.mapping:RuntimeFields" }, - "index_using_frozen": { - "description": "If true, the search can run on frozen indices. Defaults to false.", - "type": "boolean" + "time_zone": { + "$ref": "#/components/schemas/_types:TimeZone" + }, + "wait_for_completion_timeout": { + "$ref": "#/components/schemas/_types:Duration" } } } @@ -108011,7 +108021,7 @@ "$ref": "#/components/schemas/_types.query_dsl:QueryContainer" }, "query": { - "description": "SQL query to run.", + "description": "The SQL query to run.", "type": "string" }, "time_zone": { diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index fd866bf735..c1bb4be2dd 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -17746,13 +17746,13 @@ "sql" ], "summary": "Delete an async SQL search", - "description": "Delete an async SQL search or a stored synchronous SQL search.\nIf the search is still running, the API cancels it.", + "description": "Delete an async SQL search or a stored synchronous SQL search.\nIf the search is still running, the API cancels it.\n\nIf the Elasticsearch security features are enabled, only the following users can use this API to delete a search:\n\n* Users with the `cancel_task` cluster privilege.\n* The user who first submitted the search.", "operationId": "sql-delete-async", "parameters": [ { "in": "path", "name": "id", - "description": "Identifier for the search.", + "description": "The identifier for the search.", "required": true, "deprecated": false, "schema": { @@ -17782,13 +17782,13 @@ "sql" ], "summary": "Get async SQL search results", - "description": "Get the current status and available results for an async SQL search or stored synchronous SQL search.", + "description": "Get the current status and available results for an async SQL search or stored synchronous SQL search.\n\nIf the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API.", "operationId": "sql-get-async", "parameters": [ { "in": "path", "name": "id", - "description": "Identifier for the search.", + "description": "The identifier for the search.", "required": true, "deprecated": false, "schema": { @@ -17799,7 +17799,7 @@ { "in": "query", "name": "delimiter", - "description": "Separator for CSV results. The API only supports this parameter for CSV responses.", + "description": "The separator for CSV results.\nThe API supports this parameter only for CSV responses.", "deprecated": false, "schema": { "type": "string" @@ -17809,7 +17809,7 @@ { "in": "query", "name": "format", - "description": "Format for the response. You must specify a format using this parameter or the\nAccept HTTP header. If you specify both, the API uses this parameter.", + "description": "The format for the response.\nYou must specify a format using this parameter or the `Accept` HTTP header.\nIf you specify both, the API uses this parameter.", "deprecated": false, "schema": { "type": "string" @@ -17819,7 +17819,7 @@ { "in": "query", "name": "keep_alive", - "description": "Retention period for the search and its results. Defaults\nto the `keep_alive` period for the original SQL search.", + "description": "The retention period for the search and its results.\nIt defaults to the `keep_alive` period for the original SQL search.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -17829,7 +17829,7 @@ { "in": "query", "name": "wait_for_completion_timeout", - "description": "Period to wait for complete results. Defaults to no timeout,\nmeaning the request waits for complete search results.", + "description": "The period to wait for complete results.\nIt defaults to no timeout, meaning the request waits for complete search results.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -17849,11 +17849,11 @@ "$ref": "#/components/schemas/_types:Id" }, "is_running": { - "description": "If `true`, the search is still running. If false, the search has finished.\nThis value is only returned for async and saved synchronous searches. For\nCSV, TSV, and TXT responses, this value is returned in the `Async-partial`\nHTTP header.", + "description": "If `true`, the search is still running.\nIf `false`, the search has finished.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", "type": "boolean" }, "is_partial": { - "description": "If `true`, the response does not contain complete search results. If `is_partial`\nis `true` and `is_running` is `true`, the search is still running. If `is_partial`\nis `true` but `is_running` is `false`, the results are partial due to a failure or\ntimeout. This value is only returned for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", + "description": "If `true`, the response does not contain complete search results.\nIf `is_partial` is `true` and `is_running` is `true`, the search is still running.\nIf `is_partial` is `true` but `is_running` is `false`, the results are partial due to a failure or timeout.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", "type": "boolean" }, "columns": { @@ -17864,11 +17864,11 @@ } }, "cursor": { - "description": "Cursor for the next set of paginated results. For CSV, TSV, and\nTXT responses, this value is returned in the `Cursor` HTTP header.", + "description": "The cursor for the next set of paginated results.\nFor CSV, TSV, and TXT responses, this value is returned in the `Cursor` HTTP header.", "type": "string" }, "rows": { - "description": "Values for the search results.", + "description": "The values for the search results.", "type": "array", "items": { "$ref": "#/components/schemas/sql:Row" @@ -17901,7 +17901,7 @@ { "in": "path", "name": "id", - "description": "Identifier for the search.", + "description": "The identifier for the search.", "required": true, "deprecated": false, "schema": { @@ -17918,34 +17918,34 @@ "schema": { "type": "object", "properties": { + "expiration_time_in_millis": { + "$ref": "#/components/schemas/_types:EpochTimeUnitMillis" + }, "id": { - "description": "Identifier for the search.", + "description": "The identifier for the search.", "type": "string" }, "is_running": { - "description": "If `true`, the search is still running. If `false`, the search has finished.", + "description": "If `true`, the search is still running.\nIf `false`, the search has finished.", "type": "boolean" }, "is_partial": { - "description": "If `true`, the response does not contain complete search results. If `is_partial`\nis `true` and `is_running` is `true`, the search is still running. If `is_partial`\nis `true` but `is_running` is `false`, the results are partial due to a failure or\ntimeout.", + "description": "If `true`, the response does not contain complete search results.\nIf `is_partial` is `true` and `is_running` is `true`, the search is still running.\nIf `is_partial` is `true` but `is_running` is `false`, the results are partial due to a failure or timeout.", "type": "boolean" }, "start_time_in_millis": { "$ref": "#/components/schemas/_types:EpochTimeUnitMillis" }, - "expiration_time_in_millis": { - "$ref": "#/components/schemas/_types:EpochTimeUnitMillis" - }, "completion_status": { "$ref": "#/components/schemas/_types:uint" } }, "required": [ + "expiration_time_in_millis", "id", "is_running", "is_partial", - "start_time_in_millis", - "expiration_time_in_millis" + "start_time_in_millis" ] } } @@ -18007,7 +18007,7 @@ "sql" ], "summary": "Translate SQL into Elasticsearch queries", - "description": "Translate an SQL search into a search API request containing Query DSL.", + "description": "Translate an SQL search into a search API request containing Query DSL.\nIt accepts the same request body parameters as the SQL search API, excluding `cursor`.", "operationId": "sql-translate-1", "requestBody": { "$ref": "#/components/requestBodies/sql.translate" @@ -18024,7 +18024,7 @@ "sql" ], "summary": "Translate SQL into Elasticsearch queries", - "description": "Translate an SQL search into a search API request containing Query DSL.", + "description": "Translate an SQL search into a search API request containing Query DSL.\nIt accepts the same request body parameters as the SQL search API, excluding `cursor`.", "operationId": "sql-translate", "requestBody": { "$ref": "#/components/requestBodies/sql.translate" @@ -57174,17 +57174,6 @@ "schema": { "type": "object", "properties": { - "id": { - "$ref": "#/components/schemas/_types:Id" - }, - "is_running": { - "description": "If `true`, the search is still running. If false, the search has finished.\nThis value is only returned for async and saved synchronous searches. For\nCSV, TSV, and TXT responses, this value is returned in the `Async-partial`\nHTTP header.", - "type": "boolean" - }, - "is_partial": { - "description": "If `true`, the response does not contain complete search results. If `is_partial`\nis `true` and `is_running` is `true`, the search is still running. If `is_partial`\nis `true` but `is_running` is `false`, the results are partial due to a failure or\ntimeout. This value is only returned for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", - "type": "boolean" - }, "columns": { "description": "Column headings for the search results. Each object is a column.", "type": "array", @@ -57193,11 +57182,22 @@ } }, "cursor": { - "description": "Cursor for the next set of paginated results. For CSV, TSV, and\nTXT responses, this value is returned in the `Cursor` HTTP header.", + "description": "The cursor for the next set of paginated results.\nFor CSV, TSV, and TXT responses, this value is returned in the `Cursor` HTTP header.", "type": "string" }, + "id": { + "$ref": "#/components/schemas/_types:Id" + }, + "is_running": { + "description": "If `true`, the search is still running.\nIf `false`, the search has finished.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", + "type": "boolean" + }, + "is_partial": { + "description": "If `true`, the response does not contain complete search results.\nIf `is_partial` is `true` and `is_running` is `true`, the search is still running.\nIf `is_partial` is `true` but `is_running` is `false`, the results are partial due to a failure or timeout.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", + "type": "boolean" + }, "rows": { - "description": "Values for the search results.", + "description": "The values for the search results.", "type": "array", "items": { "$ref": "#/components/schemas/sql:Row" @@ -62422,7 +62422,7 @@ "sql.query#format": { "in": "query", "name": "format", - "description": "Format for the response.", + "description": "The format for the response.\nYou can also specify a format using the `Accept` HTTP header.\nIf you specify both this parameter and the `Accept` HTTP header, this parameter takes precedence.", "deprecated": false, "schema": { "$ref": "#/components/schemas/sql.query:SqlFormat" @@ -64206,65 +64206,75 @@ "schema": { "type": "object", "properties": { + "allow_partial_search_results": { + "description": "If `true`, the response has partial results when there are shard request timeouts or shard failures.\nIf `false`, the API returns an error with no partial results.", + "type": "boolean" + }, "catalog": { - "description": "Default catalog (cluster) for queries. If unspecified, the queries execute on the data in the local cluster only.", + "description": "The default catalog (cluster) for queries.\nIf unspecified, the queries execute on the data in the local cluster only.", "type": "string" }, "columnar": { - "description": "If true, the results in a columnar fashion: one row represents all the values of a certain column from the current page of results.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-rest-columnar.html" + }, + "description": "If `true`, the results are in a columnar fashion: one row represents all the values of a certain column from the current page of results.\nThe API supports this parameter only for CBOR, JSON, SMILE, and YAML responses.", "type": "boolean" }, "cursor": { - "description": "Cursor used to retrieve a set of paginated results.\nIf you specify a cursor, the API only uses the `columnar` and `time_zone` request body parameters.\nIt ignores other request body parameters.", + "description": "The cursor used to retrieve a set of paginated results.\nIf you specify a cursor, the API only uses the `columnar` and `time_zone` request body parameters.\nIt ignores other request body parameters.", "type": "string" }, "fetch_size": { - "description": "The maximum number of rows (or entries) to return in one response", + "description": "The maximum number of rows (or entries) to return in one response.", "type": "number" }, + "field_multi_value_leniency": { + "description": "If `false`, the API returns an exception when encountering multiple values for a field.\nIf `true`, the API is lenient and returns the API returns the first value from the array with no guarantee of consistent results.", + "type": "boolean" + }, "filter": { "$ref": "#/components/schemas/_types.query_dsl:QueryContainer" }, - "query": { - "description": "SQL query to run.", - "type": "string" - }, - "request_timeout": { - "$ref": "#/components/schemas/_types:Duration" + "index_using_frozen": { + "description": "If `true`, the search can run on frozen indices.", + "type": "boolean" }, - "page_timeout": { + "keep_alive": { "$ref": "#/components/schemas/_types:Duration" }, - "time_zone": { - "$ref": "#/components/schemas/_types:TimeZone" - }, - "field_multi_value_leniency": { - "description": "Throw an exception when encountering multiple values for a field (default) or be lenient and return the first value from the list (without any guarantees of what that will be - typically the first in natural ascending order).", + "keep_on_completion": { + "description": "If `true`, Elasticsearch stores synchronous searches if you also specify the `wait_for_completion_timeout` parameter.\nIf `false`, Elasticsearch only stores async searches that don't finish before the `wait_for_completion_timeout`.", "type": "boolean" }, - "runtime_mappings": { - "$ref": "#/components/schemas/_types.mapping:RuntimeFields" - }, - "wait_for_completion_timeout": { + "page_timeout": { "$ref": "#/components/schemas/_types:Duration" }, "params": { - "description": "Values for parameters in the query.", + "description": "The values for parameters in the query.", "type": "object", "additionalProperties": { "type": "object" } }, - "keep_alive": { + "query": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-spec.html" + }, + "description": "The SQL query to run.", + "type": "string" + }, + "request_timeout": { "$ref": "#/components/schemas/_types:Duration" }, - "keep_on_completion": { - "description": "If true, Elasticsearch stores synchronous searches if you also specify the wait_for_completion_timeout parameter. If false, Elasticsearch only stores async searches that don’t finish before the wait_for_completion_timeout.", - "type": "boolean" + "runtime_mappings": { + "$ref": "#/components/schemas/_types.mapping:RuntimeFields" }, - "index_using_frozen": { - "description": "If true, the search can run on frozen indices. Defaults to false.", - "type": "boolean" + "time_zone": { + "$ref": "#/components/schemas/_types:TimeZone" + }, + "wait_for_completion_timeout": { + "$ref": "#/components/schemas/_types:Duration" } } } @@ -64286,7 +64296,7 @@ "$ref": "#/components/schemas/_types.query_dsl:QueryContainer" }, "query": { - "description": "SQL query to run.", + "description": "The SQL query to run.", "type": "string" }, "time_zone": { diff --git a/output/schema/schema.json b/output/schema/schema.json index 392024c566..4c6c8052ff 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -19393,7 +19393,8 @@ } }, "description": "Clear an SQL search cursor.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/clear-sql-cursor-api.html", + "docId": "sql-clear-cursor-api", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-sql-cursor-api.html", "name": "sql.clear_cursor", "request": { "name": "Request", @@ -19430,9 +19431,15 @@ "stability": "stable" } }, - "description": "Delete an async SQL search.\nDelete an async SQL search or a stored synchronous SQL search.\nIf the search is still running, the API cancels it.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/delete-async-sql-search-api.html", + "description": "Delete an async SQL search.\nDelete an async SQL search or a stored synchronous SQL search.\nIf the search is still running, the API cancels it.\n\nIf the Elasticsearch security features are enabled, only the following users can use this API to delete a search:\n\n* Users with the `cancel_task` cluster privilege.\n* The user who first submitted the search.", + "docId": "sql-delete-async-api", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-async-sql-search-api.html", "name": "sql.delete_async", + "privileges": { + "cluster": [ + "cancel_task" + ] + }, "request": { "name": "Request", "namespace": "sql.delete_async" @@ -19465,8 +19472,9 @@ "stability": "stable" } }, - "description": "Get async SQL search results.\nGet the current status and available results for an async SQL search or stored synchronous SQL search.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/get-async-sql-search-api.html", + "description": "Get async SQL search results.\nGet the current status and available results for an async SQL search or stored synchronous SQL search.\n\nIf the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API.", + "docId": "sql-async-search-api", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-api.html", "name": "sql.get_async", "request": { "name": "Request", @@ -19501,8 +19509,14 @@ } }, "description": "Get the async SQL search status.\nGet the current status of an async SQL search or a stored synchronous SQL search.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/get-async-sql-search-status-api.html", + "docId": "sql-async-status-api", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-status-api.html", "name": "sql.get_async_status", + "privileges": { + "cluster": [ + "monitor" + ] + }, "request": { "name": "Request", "namespace": "sql.get_async_status" @@ -19536,8 +19550,14 @@ } }, "description": "Get SQL search results.\nRun an SQL request.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-search-api.html", + "docId": "sql-search-api", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-search-api.html", "name": "sql.query", + "privileges": { + "index": [ + "read" + ] + }, "request": { "name": "Request", "namespace": "sql.query" @@ -19574,9 +19594,15 @@ "stability": "stable" } }, - "description": "Translate SQL into Elasticsearch queries.\nTranslate an SQL search into a search API request containing Query DSL.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-translate-api.html", + "description": "Translate SQL into Elasticsearch queries.\nTranslate an SQL search into a search API request containing Query DSL.\nIt accepts the same request body parameters as the SQL search API, excluding `cursor`.", + "docId": "sql-translate-api", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-translate-api.html", "name": "sql.translate", + "privileges": { + "index": [ + "read" + ] + }, "request": { "name": "Request", "namespace": "sql.translate" @@ -209186,7 +209212,7 @@ }, "path": [], "query": [], - "specLocation": "sql/clear_cursor/ClearSqlCursorRequest.ts#L22-L35" + "specLocation": "sql/clear_cursor/ClearSqlCursorRequest.ts#L22-L36" }, { "kind": "response", @@ -209220,7 +209246,7 @@ "body": { "kind": "no_body" }, - "description": "Delete an async SQL search.\nDelete an async SQL search or a stored synchronous SQL search.\nIf the search is still running, the API cancels it.", + "description": "Delete an async SQL search.\nDelete an async SQL search or a stored synchronous SQL search.\nIf the search is still running, the API cancels it.\n\nIf the Elasticsearch security features are enabled, only the following users can use this API to delete a search:\n\n* Users with the `cancel_task` cluster privilege.\n* The user who first submitted the search.", "inherits": { "type": { "name": "RequestBase", @@ -209233,7 +209259,7 @@ }, "path": [ { - "description": "Identifier for the search.", + "description": "The identifier for the search.", "name": "id", "required": true, "type": { @@ -209246,7 +209272,7 @@ } ], "query": [], - "specLocation": "sql/delete_async/SqlDeleteAsyncRequest.ts#L23-L38" + "specLocation": "sql/delete_async/SqlDeleteAsyncRequest.ts#L23-L45" }, { "kind": "response", @@ -209274,7 +209300,7 @@ "body": { "kind": "no_body" }, - "description": "Get async SQL search results.\nGet the current status and available results for an async SQL search or stored synchronous SQL search.", + "description": "Get async SQL search results.\nGet the current status and available results for an async SQL search or stored synchronous SQL search.\n\nIf the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API.", "inherits": { "type": { "name": "RequestBase", @@ -209287,7 +209313,7 @@ }, "path": [ { - "description": "Identifier for the search.", + "description": "The identifier for the search.", "name": "id", "required": true, "type": { @@ -209301,7 +209327,7 @@ ], "query": [ { - "description": "Separator for CSV results. The API only supports this parameter for CSV responses.", + "description": "The separator for CSV results.\nThe API supports this parameter only for CSV responses.", "name": "delimiter", "required": false, "serverDefault": ",", @@ -209314,7 +209340,7 @@ } }, { - "description": "Format for the response. You must specify a format using this parameter or the\nAccept HTTP header. If you specify both, the API uses this parameter.", + "description": "The format for the response.\nYou must specify a format using this parameter or the `Accept` HTTP header.\nIf you specify both, the API uses this parameter.", "name": "format", "required": false, "type": { @@ -209326,7 +209352,7 @@ } }, { - "description": "Retention period for the search and its results. Defaults\nto the `keep_alive` period for the original SQL search.", + "description": "The retention period for the search and its results.\nIt defaults to the `keep_alive` period for the original SQL search.", "name": "keep_alive", "required": false, "type": { @@ -209338,7 +209364,7 @@ } }, { - "description": "Period to wait for complete results. Defaults to no timeout,\nmeaning the request waits for complete search results.", + "description": "The period to wait for complete results.\nIt defaults to no timeout, meaning the request waits for complete search results.", "name": "wait_for_completion_timeout", "required": false, "type": { @@ -209350,7 +209376,7 @@ } } ], - "specLocation": "sql/get_async/SqlGetAsyncRequest.ts#L24-L60" + "specLocation": "sql/get_async/SqlGetAsyncRequest.ts#L24-L65" }, { "kind": "response", @@ -209358,7 +209384,7 @@ "kind": "properties", "properties": [ { - "description": "Identifier for the search. This value is only returned for async and saved\nsynchronous searches. For CSV, TSV, and TXT responses, this value is returned\nin the `Async-ID` HTTP header.", + "description": "Identifier for the search.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-ID` HTTP header.", "name": "id", "required": true, "type": { @@ -209370,7 +209396,7 @@ } }, { - "description": "If `true`, the search is still running. If false, the search has finished.\nThis value is only returned for async and saved synchronous searches. For\nCSV, TSV, and TXT responses, this value is returned in the `Async-partial`\nHTTP header.", + "description": "If `true`, the search is still running.\nIf `false`, the search has finished.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", "name": "is_running", "required": true, "type": { @@ -209382,7 +209408,7 @@ } }, { - "description": "If `true`, the response does not contain complete search results. If `is_partial`\nis `true` and `is_running` is `true`, the search is still running. If `is_partial`\nis `true` but `is_running` is `false`, the results are partial due to a failure or\ntimeout. This value is only returned for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", + "description": "If `true`, the response does not contain complete search results.\nIf `is_partial` is `true` and `is_running` is `true`, the search is still running.\nIf `is_partial` is `true` but `is_running` is `false`, the results are partial due to a failure or timeout.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", "name": "is_partial", "required": true, "type": { @@ -209409,7 +209435,7 @@ } }, { - "description": "Cursor for the next set of paginated results. For CSV, TSV, and\nTXT responses, this value is returned in the `Cursor` HTTP header.", + "description": "The cursor for the next set of paginated results.\nFor CSV, TSV, and TXT responses, this value is returned in the `Cursor` HTTP header.", "name": "cursor", "required": false, "type": { @@ -209421,7 +209447,7 @@ } }, { - "description": "Values for the search results.", + "description": "The values for the search results.", "name": "rows", "required": true, "type": { @@ -209464,7 +209490,7 @@ }, "path": [ { - "description": "Identifier for the search.", + "description": "The identifier for the search.", "name": "id", "required": true, "type": { @@ -209477,7 +209503,7 @@ } ], "query": [], - "specLocation": "sql/get_async_status/SqlGetAsyncStatusRequest.ts#L23-L37" + "specLocation": "sql/get_async_status/SqlGetAsyncStatusRequest.ts#L23-L39" }, { "kind": "response", @@ -209485,32 +209511,41 @@ "kind": "properties", "properties": [ { - "description": "Identifier for the search.", - "name": "id", + "description": "The timestamp, in milliseconds since the Unix epoch, when Elasticsearch will delete the search and its results, even if the search is still running.", + "name": "expiration_time_in_millis", "required": true, "type": { "kind": "instance_of", + "generics": [ + { + "kind": "instance_of", + "type": { + "name": "UnitMillis", + "namespace": "_types" + } + } + ], "type": { - "name": "string", - "namespace": "_builtins" + "name": "EpochTime", + "namespace": "_types" } } }, { - "description": "If `true`, the search is still running. If `false`, the search has finished.", - "name": "is_running", + "description": "The identifier for the search.", + "name": "id", "required": true, "type": { "kind": "instance_of", "type": { - "name": "boolean", + "name": "string", "namespace": "_builtins" } } }, { - "description": "If `true`, the response does not contain complete search results. If `is_partial`\nis `true` and `is_running` is `true`, the search is still running. If `is_partial`\nis `true` but `is_running` is `false`, the results are partial due to a failure or\ntimeout.", - "name": "is_partial", + "description": "If `true`, the search is still running.\nIf `false`, the search has finished.", + "name": "is_running", "required": true, "type": { "kind": "instance_of", @@ -209521,29 +209556,20 @@ } }, { - "description": "Timestamp, in milliseconds since the Unix epoch, when the search started.\nThe API only returns this property for running searches.", - "name": "start_time_in_millis", + "description": "If `true`, the response does not contain complete search results.\nIf `is_partial` is `true` and `is_running` is `true`, the search is still running.\nIf `is_partial` is `true` but `is_running` is `false`, the results are partial due to a failure or timeout.", + "name": "is_partial", "required": true, "type": { "kind": "instance_of", - "generics": [ - { - "kind": "instance_of", - "type": { - "name": "UnitMillis", - "namespace": "_types" - } - } - ], "type": { - "name": "EpochTime", - "namespace": "_types" + "name": "boolean", + "namespace": "_builtins" } } }, { - "description": "Timestamp, in milliseconds since the Unix epoch, when Elasticsearch will delete\nthe search and its results, even if the search is still running.", - "name": "expiration_time_in_millis", + "description": "The timestamp, in milliseconds since the Unix epoch, when the search started.\nThe API returns this property only for running searches.", + "name": "start_time_in_millis", "required": true, "type": { "kind": "instance_of", @@ -209563,7 +209589,7 @@ } }, { - "description": "HTTP status code for the search. The API only returns this property for completed searches.", + "description": "The HTTP status code for the search.\nThe API returns this property only for completed searches.", "name": "completion_status", "required": false, "type": { @@ -209591,7 +209617,20 @@ "kind": "properties", "properties": [ { - "description": "Default catalog (cluster) for queries. If unspecified, the queries execute on the data in the local cluster only.", + "description": "If `true`, the response has partial results when there are shard request timeouts or shard failures.\nIf `false`, the API returns an error with no partial results.", + "name": "allow_partial_search_results", + "required": false, + "serverDefault": false, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } + }, + { + "description": "The default catalog (cluster) for queries.\nIf unspecified, the queries execute on the data in the local cluster only.", "name": "catalog", "required": false, "type": { @@ -209603,7 +209642,9 @@ } }, { - "description": "If true, the results in a columnar fashion: one row represents all the values of a certain column from the current page of results.", + "description": "If `true`, the results are in a columnar fashion: one row represents all the values of a certain column from the current page of results.\nThe API supports this parameter only for CBOR, JSON, SMILE, and YAML responses.", + "extDocId": "sql-rest-columnar", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-columnar.html", "name": "columnar", "required": false, "serverDefault": false, @@ -209616,7 +209657,7 @@ } }, { - "description": "Cursor used to retrieve a set of paginated results.\nIf you specify a cursor, the API only uses the `columnar` and `time_zone` request body parameters.\nIt ignores other request body parameters.", + "description": "The cursor used to retrieve a set of paginated results.\nIf you specify a cursor, the API only uses the `columnar` and `time_zone` request body parameters.\nIt ignores other request body parameters.", "name": "cursor", "required": false, "type": { @@ -209628,7 +209669,7 @@ } }, { - "description": "The maximum number of rows (or entries) to return in one response", + "description": "The maximum number of rows (or entries) to return in one response.", "name": "fetch_size", "required": false, "serverDefault": 1000, @@ -209641,75 +209682,62 @@ } }, { - "description": "Elasticsearch query DSL for additional filtering.", - "docId": "sql-rest-filtering", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-filtering.html", - "name": "filter", - "required": false, - "serverDefault": "none", - "type": { - "kind": "instance_of", - "type": { - "name": "QueryContainer", - "namespace": "_types.query_dsl" - } - } - }, - { - "description": "SQL query to run.", - "name": "query", + "description": "If `false`, the API returns an exception when encountering multiple values for a field.\nIf `true`, the API is lenient and returns the API returns the first value from the array with no guarantee of consistent results.", + "name": "field_multi_value_leniency", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { - "name": "string", + "name": "boolean", "namespace": "_builtins" } } }, { - "description": "The timeout before the request fails.", - "name": "request_timeout", + "description": "The Elasticsearch query DSL for additional filtering.", + "extDocId": "sql-rest-filtering", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-filtering.html", + "name": "filter", "required": false, - "serverDefault": "90s", + "serverDefault": "none", "type": { "kind": "instance_of", "type": { - "name": "Duration", - "namespace": "_types" + "name": "QueryContainer", + "namespace": "_types.query_dsl" } } }, { - "description": "The timeout before a pagination request fails.", - "name": "page_timeout", + "description": "If `true`, the search can run on frozen indices.", + "name": "index_using_frozen", "required": false, - "serverDefault": "45s", + "serverDefault": false, "type": { "kind": "instance_of", "type": { - "name": "Duration", - "namespace": "_types" + "name": "boolean", + "namespace": "_builtins" } } }, { - "description": "ISO-8601 time zone ID for the search.", - "docUrl": "https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html", - "name": "time_zone", + "description": "The retention period for an async or saved synchronous search.", + "name": "keep_alive", "required": false, - "serverDefault": "Z", + "serverDefault": "5d", "type": { "kind": "instance_of", "type": { - "name": "TimeZone", + "name": "Duration", "namespace": "_types" } } }, { - "description": "Throw an exception when encountering multiple values for a field (default) or be lenient and return the first value from the list (without any guarantees of what that will be - typically the first in natural ascending order).", - "name": "field_multi_value_leniency", + "description": "If `true`, Elasticsearch stores synchronous searches if you also specify the `wait_for_completion_timeout` parameter.\nIf `false`, Elasticsearch only stores async searches that don't finish before the `wait_for_completion_timeout`.", + "name": "keep_on_completion", "required": false, "serverDefault": false, "type": { @@ -209721,21 +209749,10 @@ } }, { - "description": "Defines one or more runtime fields in the search request. These fields take\nprecedence over mapped fields with the same name.", - "name": "runtime_mappings", - "required": false, - "type": { - "kind": "instance_of", - "type": { - "name": "RuntimeFields", - "namespace": "_types.mapping" - } - } - }, - { - "description": "Period to wait for complete results. Defaults to no timeout, meaning the request waits for complete search results. If the search doesn’t finish within this period, the search becomes async.", - "name": "wait_for_completion_timeout", + "description": "The minimum retention period for the scroll cursor.\nAfter this time period, a pagination request might fail because the scroll cursor is no longer available.\nSubsequent scroll requests prolong the lifetime of the scroll cursor by the duration of `page_timeout` in the scroll request.", + "name": "page_timeout", "required": false, + "serverDefault": "45s", "type": { "kind": "instance_of", "type": { @@ -209745,7 +209762,7 @@ } }, { - "description": "Values for parameters in the query.", + "description": "The values for parameters in the query.", "name": "params", "required": false, "type": { @@ -209764,10 +209781,24 @@ } }, { - "description": "Retention period for an async or saved synchronous search.", - "name": "keep_alive", + "description": "The SQL query to run.", + "extDocId": "sql-spec", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-spec.html", + "name": "query", "required": false, - "serverDefault": "5d", + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } + }, + { + "description": "The timeout before the request fails.", + "name": "request_timeout", + "required": false, + "serverDefault": "90s", "type": { "kind": "instance_of", "type": { @@ -209777,28 +209808,41 @@ } }, { - "description": "If true, Elasticsearch stores synchronous searches if you also specify the wait_for_completion_timeout parameter. If false, Elasticsearch only stores async searches that don’t finish before the wait_for_completion_timeout.", - "name": "keep_on_completion", + "description": "One or more runtime fields for the search request.\nThese fields take precedence over mapped fields with the same name.", + "name": "runtime_mappings", "required": false, - "serverDefault": false, "type": { "kind": "instance_of", "type": { - "name": "boolean", - "namespace": "_builtins" + "name": "RuntimeFields", + "namespace": "_types.mapping" } } }, { - "description": "If true, the search can run on frozen indices. Defaults to false.", - "name": "index_using_frozen", + "description": "The ISO-8601 time zone ID for the search.", + "extDocId": "time-zone-id", + "extDocUrl": "https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html", + "name": "time_zone", "required": false, - "serverDefault": false, + "serverDefault": "Z", "type": { "kind": "instance_of", "type": { - "name": "boolean", - "namespace": "_builtins" + "name": "TimeZone", + "namespace": "_types" + } + } + }, + { + "description": "The period to wait for complete results.\nIt defaults to no timeout, meaning the request waits for complete search results.\nIf the search doesn't finish within this period, the search becomes async.\n\nTo save a synchronous search, you must specify this parameter and the `keep_on_completion` parameter.", + "name": "wait_for_completion_timeout", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "Duration", + "namespace": "_types" } } } @@ -209818,9 +209862,9 @@ "path": [], "query": [ { - "description": "Format for the response.", - "docId": "sql-rest-format", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-format.html", + "description": "The format for the response.\nYou can also specify a format using the `Accept` HTTP header.\nIf you specify both this parameter and the `Accept` HTTP header, this parameter takes precedence.", + "extDocId": "sql-rest-format", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-format.html", "name": "format", "required": false, "type": { @@ -209832,7 +209876,7 @@ } } ], - "specLocation": "sql/query/QuerySqlRequest.ts#L28-L124" + "specLocation": "sql/query/QuerySqlRequest.ts#L28-L146" }, { "kind": "response", @@ -209840,70 +209884,70 @@ "kind": "properties", "properties": [ { - "description": "Identifier for the search. This value is only returned for async and saved\nsynchronous searches. For CSV, TSV, and TXT responses, this value is returned\nin the `Async-ID` HTTP header.", - "name": "id", + "description": "Column headings for the search results. Each object is a column.", + "name": "columns", "required": false, "type": { - "kind": "instance_of", - "type": { - "name": "Id", - "namespace": "_types" + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "Column", + "namespace": "sql" + } } } }, { - "description": "If `true`, the search is still running. If false, the search has finished.\nThis value is only returned for async and saved synchronous searches. For\nCSV, TSV, and TXT responses, this value is returned in the `Async-partial`\nHTTP header.", - "name": "is_running", + "description": "The cursor for the next set of paginated results.\nFor CSV, TSV, and TXT responses, this value is returned in the `Cursor` HTTP header.", + "name": "cursor", "required": false, "type": { "kind": "instance_of", "type": { - "name": "boolean", + "name": "string", "namespace": "_builtins" } } }, { - "description": "If `true`, the response does not contain complete search results. If `is_partial`\nis `true` and `is_running` is `true`, the search is still running. If `is_partial`\nis `true` but `is_running` is `false`, the results are partial due to a failure or\ntimeout. This value is only returned for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", - "name": "is_partial", + "description": "The identifier for the search.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-ID` HTTP header.", + "name": "id", "required": false, "type": { "kind": "instance_of", "type": { - "name": "boolean", - "namespace": "_builtins" + "name": "Id", + "namespace": "_types" } } }, { - "description": "Column headings for the search results. Each object is a column.", - "name": "columns", + "description": "If `true`, the search is still running.\nIf `false`, the search has finished.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", + "name": "is_running", "required": false, "type": { - "kind": "array_of", - "value": { - "kind": "instance_of", - "type": { - "name": "Column", - "namespace": "sql" - } + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" } } }, { - "description": "Cursor for the next set of paginated results. For CSV, TSV, and\nTXT responses, this value is returned in the `Cursor` HTTP header.", - "name": "cursor", + "description": "If `true`, the response does not contain complete search results.\nIf `is_partial` is `true` and `is_running` is `true`, the search is still running.\nIf `is_partial` is `true` but `is_running` is `false`, the results are partial due to a failure or timeout.\nThis value is returned only for async and saved synchronous searches.\nFor CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.", + "name": "is_partial", "required": false, "type": { "kind": "instance_of", "type": { - "name": "string", + "name": "boolean", "namespace": "_builtins" } } }, { - "description": "Values for the search results.", + "description": "The values for the search results.", "name": "rows", "required": true, "type": { @@ -209954,7 +209998,7 @@ "name": "SqlFormat", "namespace": "sql.query" }, - "specLocation": "sql/query/QuerySqlRequest.ts#L126-L134" + "specLocation": "sql/query/QuerySqlRequest.ts#L148-L156" }, { "kind": "request", @@ -209978,9 +210022,9 @@ } }, { - "description": "Elasticsearch query DSL for additional filtering.", - "docId": "sql-rest-filtering", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-filtering.html", + "description": "The Elasticsearch query DSL for additional filtering.", + "extDocId": "sql-rest-filtering", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-filtering.html", "name": "filter", "required": false, "serverDefault": "none", @@ -209993,7 +210037,7 @@ } }, { - "description": "SQL query to run.", + "description": "The SQL query to run.", "name": "query", "required": true, "type": { @@ -210005,8 +210049,9 @@ } }, { - "description": "ISO-8601 time zone ID for the search.", - "docUrl": "https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html", + "description": "The ISO-8601 time zone ID for the search.", + "extDocId": "time-zone-id", + "extDocUrl": "https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html", "name": "time_zone", "required": false, "serverDefault": "Z", @@ -210020,7 +210065,7 @@ } ] }, - "description": "Translate SQL into Elasticsearch queries.\nTranslate an SQL search into a search API request containing Query DSL.", + "description": "Translate SQL into Elasticsearch queries.\nTranslate an SQL search into a search API request containing Query DSL.\nIt accepts the same request body parameters as the SQL search API, excluding `cursor`.", "inherits": { "type": { "name": "RequestBase", @@ -210033,7 +210078,7 @@ }, "path": [], "query": [], - "specLocation": "sql/translate/TranslateSqlRequest.ts#L25-L56" + "specLocation": "sql/translate/TranslateSqlRequest.ts#L25-L59" }, { "kind": "response", diff --git a/output/typescript/types.ts b/output/typescript/types.ts index 522f53b0ae..aaecec5bb1 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -19776,42 +19776,43 @@ export interface SqlGetAsyncStatusRequest extends RequestBase { } export interface SqlGetAsyncStatusResponse { + expiration_time_in_millis: EpochTime id: string is_running: boolean is_partial: boolean start_time_in_millis: EpochTime - expiration_time_in_millis: EpochTime completion_status?: uint } export interface SqlQueryRequest extends RequestBase { format?: SqlQuerySqlFormat body?: { + allow_partial_search_results?: boolean catalog?: string columnar?: boolean cursor?: string fetch_size?: integer + field_multi_value_leniency?: boolean filter?: QueryDslQueryContainer + index_using_frozen?: boolean + keep_alive?: Duration + keep_on_completion?: boolean + page_timeout?: Duration + params?: Record query?: string request_timeout?: Duration - page_timeout?: Duration - time_zone?: TimeZone - field_multi_value_leniency?: boolean runtime_mappings?: MappingRuntimeFields + time_zone?: TimeZone wait_for_completion_timeout?: Duration - params?: Record - keep_alive?: Duration - keep_on_completion?: boolean - index_using_frozen?: boolean } } export interface SqlQueryResponse { + columns?: SqlColumn[] + cursor?: string id?: Id is_running?: boolean is_partial?: boolean - columns?: SqlColumn[] - cursor?: string rows: SqlRow[] } diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 4e294162c2..b58d6620af 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -67,7 +67,6 @@ ccs-network-delays,https://www.elastic.co/guide/en/elasticsearch/reference/{bran clean-up-snapshot-repo,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html#snapshots-repository-cleanup clear-repositories-metering-archive-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-repositories-metering-archive-api.html clear-scroll-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-scroll-api.html -clear-sql-cursor-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-sql-cursor-api.html cluster-allocation-explain,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-allocation-explain.html cluster-get-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-get-settings.html cluster-health,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-health.html @@ -130,7 +129,6 @@ data-streams,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/da date-index-name-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/date-index-name-processor.html dcg,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html#_discounted_cumulative_gain_dcg defining-roles,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/defining-roles.html -delete-async-sql-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-async-sql-search-api.html delete-enrich-policy-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-enrich-policy-api.html delete-license,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-license.html delete-pipeline-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-pipeline-api.html @@ -188,8 +186,6 @@ geo-shape,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/geo-s geo-grid-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ingest-geo-grid-processor.html geoip-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/geoip-processor.html geoip-stats-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/geoip-stats-api.html -get-async-sql-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-api.html -get-async-sql-search-status-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-status-api.html get-basic-status,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-basic-status.html get-dfanalytics-stats,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-dfanalytics-stats.html get-dfanalytics,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-dfanalytics.html @@ -478,6 +474,8 @@ reroute-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branc render-search-template-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/render-search-template-api.html reset-transform,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/reset-transform.html restore-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-restore-snapshot.html +sql-delete-async-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-async-sql-search-api.html +sql-clear-cursor-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-sql-cursor-api.html rollup-agg-limitations,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-agg-limitations.html rollup-delete-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-delete-job.html rollup-get-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-get-job.html @@ -680,9 +678,13 @@ sort-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{bra sort-tiebreaker,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql.html#eql-search-specify-a-sort-tiebreaker query-dsl-sparse-vector-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-sparse-vector-query.html split-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/split-processor.html +sql-async-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-api.html +sql-async-status-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-status-api.html +sql-rest-columnar,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-columnar.html sql-rest-filtering,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-filtering.html sql-rest-format,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-format.html sql-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-search-api.html +sql-spec,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-spec.html sql-translate-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-translate-api.html start-basic,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/start-basic.html start-dfanalytics,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/start-dfanalytics.html @@ -705,6 +707,7 @@ tasks,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/tasks.htm templating-role-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/field-and-document-access-control.html#templating-role-query terminate-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/terminate-processor.html time-value,https://github.com/elastic/elasticsearch/blob/{branch}/libs/core/src/main/java/org/elasticsearch/core/TimeValue.java +time-zone-id,https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html trim-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/trim-processor.html unfreeze-index-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/unfreeze-index-api.html update-dfanalytics,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/update-dfanalytics.html diff --git a/specification/sql/clear_cursor/ClearSqlCursorRequest.ts b/specification/sql/clear_cursor/ClearSqlCursorRequest.ts index 1961b1a53d..06313452ac 100644 --- a/specification/sql/clear_cursor/ClearSqlCursorRequest.ts +++ b/specification/sql/clear_cursor/ClearSqlCursorRequest.ts @@ -24,6 +24,7 @@ import { RequestBase } from '@_types/Base' * @rest_spec_name sql.clear_cursor * @availability stack since=6.3.0 stability=stable * @availability serverless stability=stable visibility=public + * @doc_id sql-clear-cursor-api */ export interface Request extends RequestBase { body: { diff --git a/specification/sql/clear_cursor/examples/request/ClearSqlCursorRequestExample1.yaml b/specification/sql/clear_cursor/examples/request/ClearSqlCursorRequestExample1.yaml new file mode 100644 index 0000000000..baa774b12a --- /dev/null +++ b/specification/sql/clear_cursor/examples/request/ClearSqlCursorRequestExample1.yaml @@ -0,0 +1,7 @@ +# summary: +# method_request: POST _sql/close +description: Run `POST _sql/close` to clear an SQL search cursor. +# type: request +value: + "{\n \"cursor\": \"sDXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAEWYUpOYklQMHhRUEtld3RsNnFtYU1hQQ==:BAFmBGRhdGUBZgVsaWtlcwFzB21lc3NhZ2UBZgR1c2Vy9f///w8=\"\ + \n}" diff --git a/specification/sql/delete_async/SqlDeleteAsyncRequest.ts b/specification/sql/delete_async/SqlDeleteAsyncRequest.ts index b4ef516e60..f5a68a896b 100644 --- a/specification/sql/delete_async/SqlDeleteAsyncRequest.ts +++ b/specification/sql/delete_async/SqlDeleteAsyncRequest.ts @@ -24,14 +24,21 @@ import { Id } from '@_types/common' * Delete an async SQL search. * Delete an async SQL search or a stored synchronous SQL search. * If the search is still running, the API cancels it. + * + * If the Elasticsearch security features are enabled, only the following users can use this API to delete a search: + * + * * Users with the `cancel_task` cluster privilege. + * * The user who first submitted the search. * @rest_spec_name sql.delete_async * @availability stack since=7.15.0 stability=stable * @availability serverless stability=stable visibility=public + * @cluster_privileges cancel_task + * @doc_id sql-delete-async-api */ export interface Request extends RequestBase { path_parts: { /** - * Identifier for the search. + * The identifier for the search. */ id: Id } diff --git a/specification/sql/get_async/SqlGetAsyncRequest.ts b/specification/sql/get_async/SqlGetAsyncRequest.ts index 4159eba4ed..908b249e44 100644 --- a/specification/sql/get_async/SqlGetAsyncRequest.ts +++ b/specification/sql/get_async/SqlGetAsyncRequest.ts @@ -24,36 +24,41 @@ import { Duration } from '@_types/Time' /** * Get async SQL search results. * Get the current status and available results for an async SQL search or stored synchronous SQL search. + * + * If the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API. * @rest_spec_name sql.get_async * @availability stack since=7.15.0 stability=stable * @availability serverless stability=stable visibility=public + * @doc_id sql-async-search-api */ export interface Request extends RequestBase { path_parts: { /** - * Identifier for the search. + * The identifier for the search. */ id: Id } query_parameters: { /** - * Separator for CSV results. The API only supports this parameter for CSV responses. + * The separator for CSV results. + * The API supports this parameter only for CSV responses. * @server_default , */ delimiter?: 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. + * The 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. */ format?: string /** - * Retention period for the search and its results. Defaults - * to the `keep_alive` period for the original SQL search. + * The retention period for the search and its results. + * It defaults to the `keep_alive` period for the original SQL search. */ keep_alive?: Duration /** - * Period to wait for complete results. Defaults to no timeout, - * meaning the request waits for complete search results. + * The period to wait for complete results. + * It defaults to no timeout, meaning the request waits for complete search results. */ wait_for_completion_timeout?: Duration } diff --git a/specification/sql/get_async/SqlGetAsyncResponse.ts b/specification/sql/get_async/SqlGetAsyncResponse.ts index 2a1c8c3acd..34f9aa2651 100644 --- a/specification/sql/get_async/SqlGetAsyncResponse.ts +++ b/specification/sql/get_async/SqlGetAsyncResponse.ts @@ -23,23 +23,23 @@ import { Column, Row } from '../types' export class Response { body: { /** - * Identifier for the search. This value is only returned for async and saved - * synchronous searches. For CSV, TSV, and TXT responses, this value is returned - * in the `Async-ID` HTTP header. + * Identifier for the search. + * This value is returned only for async and saved synchronous searches. + * For CSV, TSV, and TXT responses, this value is returned in the `Async-ID` HTTP header. */ id: Id /** - * If `true`, the search is still running. If false, the search has finished. - * This value is only returned for async and saved synchronous searches. For - * CSV, TSV, and TXT responses, this value is returned in the `Async-partial` - * HTTP header. + * If `true`, the search is still running. + * If `false`, the search has finished. + * This value is returned only for async and saved synchronous searches. + * For CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header. */ is_running: 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. This value is only returned for async and saved synchronous searches. + * 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. + * This value is returned only for async and saved synchronous searches. * For CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header. */ is_partial: boolean @@ -48,12 +48,12 @@ export class Response { */ columns?: Column[] /** - * Cursor for the next set of paginated results. For CSV, TSV, and - * TXT responses, this value is returned in the `Cursor` HTTP header. + * The cursor for the next set of paginated results. + * For CSV, TSV, and TXT responses, this value is returned in the `Cursor` HTTP header. */ cursor?: string /** - * Values for the search results. + * The values for the search results. */ rows: Row[] } diff --git a/specification/sql/get_async_status/SqlGetAsyncStatusRequest.ts b/specification/sql/get_async_status/SqlGetAsyncStatusRequest.ts index ed6be9c7cc..7bd0d6a44f 100644 --- a/specification/sql/get_async_status/SqlGetAsyncStatusRequest.ts +++ b/specification/sql/get_async_status/SqlGetAsyncStatusRequest.ts @@ -26,11 +26,13 @@ import { Id } from '@_types/common' * @rest_spec_name sql.get_async_status * @availability stack since=7.15.0 stability=stable * @availability serverless stability=stable visibility=public + * @cluster_privileges monitor + * @doc_id sql-async-status-api */ export interface Request extends RequestBase { path_parts: { /** - * Identifier for the search. + * The identifier for the search. */ id: Id } diff --git a/specification/sql/get_async_status/SqlGetAsyncStatusResponse.ts b/specification/sql/get_async_status/SqlGetAsyncStatusResponse.ts index 4e1f3e6df7..53aede18c6 100644 --- a/specification/sql/get_async_status/SqlGetAsyncStatusResponse.ts +++ b/specification/sql/get_async_status/SqlGetAsyncStatusResponse.ts @@ -23,32 +23,32 @@ import { EpochTime, UnitMillis } from '@_types/Time' export class Response { body: { /** - * Identifier for the search. + * The timestamp, in milliseconds since the Unix epoch, when Elasticsearch will delete the search and its results, even if the search is still running. + */ + expiration_time_in_millis: EpochTime + /** + * The identifier for the search. */ id: string /** - * If `true`, the search is still running. If `false`, the search has finished. + * If `true`, the search is still running. + * If `false`, the search has finished. */ is_running: 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. + * 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. */ is_partial: boolean /** - * Timestamp, in milliseconds since the Unix epoch, when the search started. - * The API only returns this property for running searches. + * The timestamp, in milliseconds since the Unix epoch, when the search started. + * The API returns this property only for running searches. */ start_time_in_millis: EpochTime /** - * Timestamp, in milliseconds since the Unix epoch, when Elasticsearch will delete - * the search and its results, even if the search is still running. - */ - expiration_time_in_millis: EpochTime - /** - * HTTP status code for the search. The API only returns this property for completed searches. + * The HTTP status code for the search. + * The API returns this property only for completed searches. */ completion_status?: uint } diff --git a/specification/sql/query/QuerySqlRequest.ts b/specification/sql/query/QuerySqlRequest.ts index 11625631d9..592a116eb7 100644 --- a/specification/sql/query/QuerySqlRequest.ts +++ b/specification/sql/query/QuerySqlRequest.ts @@ -31,95 +31,117 @@ import { Duration, TimeZone } from '@_types/Time' * @rest_spec_name sql.query * @availability stack since=6.3.0 stability=stable * @availability serverless stability=stable visibility=public + * @index_privileges read + * @doc_id sql-search-api */ export interface Request extends RequestBase { query_parameters: { /** - * Format for the response. - * @doc_id sql-rest-format + * The format for the response. + * You can also specify a format using the `Accept` HTTP header. + * If you specify both this parameter and the `Accept` HTTP header, this parameter takes precedence. + * @ext_doc_id sql-rest-format */ format?: SqlFormat } body: { /** - * Default catalog (cluster) for queries. If unspecified, the queries execute on the data in the local cluster only. + * If `true`, the response has partial results when there are shard request timeouts or shard failures. + * If `false`, the API returns an error with no partial results. + * @server_default false + */ + allow_partial_search_results?: boolean + /** + * The default catalog (cluster) for queries. + * If unspecified, the queries execute on the data in the local cluster only. */ catalog?: string /** - * If true, the results in a columnar fashion: one row represents all the values of a certain column from the current page of results. + * If `true`, the results are in a columnar fashion: one row represents all the values of a certain column from the current page of results. + * The API supports this parameter only for CBOR, JSON, SMILE, and YAML responses. + * @ext_doc_id sql-rest-columnar * @server_default false */ columnar?: boolean /** - * Cursor used to retrieve a set of paginated results. + * The cursor used to retrieve a set of paginated results. * If you specify a cursor, the API only uses the `columnar` and `time_zone` request body parameters. * It ignores other request body parameters. */ cursor?: string /** - * The maximum number of rows (or entries) to return in one response + * The maximum number of rows (or entries) to return in one response. * @server_default 1000 */ fetch_size?: integer /** - * Elasticsearch query DSL for additional filtering. - * @doc_id sql-rest-filtering - * @server_default none + * If `false`, the API returns an exception when encountering multiple values for a field. + * If `true`, the API is lenient and returns the first value from the array with no guarantee of consistent results. + * @server_default false */ - filter?: QueryContainer + field_multi_value_leniency?: boolean /** - * SQL query to run. + * The Elasticsearch query DSL for additional filtering. + * @ext_doc_id sql-rest-filtering + * @server_default none */ - query?: string + filter?: QueryContainer /** - * The timeout before the request fails. - * @server_default 90s + * If `true`, the search can run on frozen indices. + * @server_default false */ - request_timeout?: Duration + index_using_frozen?: boolean /** - * The timeout before a pagination request fails. - * @server_default 45s + * The retention period for an async or saved synchronous search. + * @server_default 5d */ - page_timeout?: Duration + keep_alive?: Duration /** - * ISO-8601 time zone ID for the search. - * @doc_url https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html - * @server_default Z + * If `true`, Elasticsearch stores synchronous searches if you also specify the `wait_for_completion_timeout` parameter. + * If `false`, Elasticsearch only stores async searches that don't finish before the `wait_for_completion_timeout`. + * @server_default false */ - time_zone?: TimeZone + keep_on_completion?: boolean /** - * Throw an exception when encountering multiple values for a field (default) or be lenient and return the first value from the list (without any guarantees of what that will be - typically the first in natural ascending order). - * @server_default false + * The minimum retention period for the scroll cursor. + * After this time period, a pagination request might fail because the scroll cursor is no longer available. + * Subsequent scroll requests prolong the lifetime of the scroll cursor by the duration of `page_timeout` in the scroll request. + * @server_default 45s */ - field_multi_value_leniency?: boolean + page_timeout?: Duration /** - * Defines one or more runtime fields in the search request. These fields take - * precedence over mapped fields with the same name. + * The values for parameters in the query. */ - runtime_mappings?: RuntimeFields + params?: Dictionary /** - * Period to wait for complete results. Defaults to no timeout, meaning the request waits for complete search results. If the search doesn’t finish within this period, the search becomes async. + * The SQL query to run. + * @ext_doc_id sql-spec */ - wait_for_completion_timeout?: Duration + query?: string /** - * Values for parameters in the query. + * The timeout before the request fails. + * @server_default 90s */ - params?: Dictionary + request_timeout?: Duration /** - * Retention period for an async or saved synchronous search. - * @server_default 5d + * One or more runtime fields for the search request. + * These fields take precedence over mapped fields with the same name. */ - keep_alive?: Duration + runtime_mappings?: RuntimeFields /** - * If true, Elasticsearch stores synchronous searches if you also specify the wait_for_completion_timeout parameter. If false, Elasticsearch only stores async searches that don’t finish before the wait_for_completion_timeout. - * @server_default false + * The ISO-8601 time zone ID for the search. + * @ext_doc_id time-zone-id + * @server_default Z */ - keep_on_completion?: boolean + time_zone?: TimeZone /** - * If true, the search can run on frozen indices. Defaults to false. - * @server_default false + * The period to wait for complete results. + * It defaults to no timeout, meaning the request waits for complete search results. + * If the search doesn't finish within this period, the search becomes async. + * + * To save a synchronous search, you must specify this parameter and the `keep_on_completion` parameter. */ - index_using_frozen?: boolean + wait_for_completion_timeout?: Duration } } diff --git a/specification/sql/query/QuerySqlResponse.ts b/specification/sql/query/QuerySqlResponse.ts index 3b9ad5c5f5..29e6a69e94 100644 --- a/specification/sql/query/QuerySqlResponse.ts +++ b/specification/sql/query/QuerySqlResponse.ts @@ -23,37 +23,37 @@ import { Column, Row } from '../types' export class Response { body: { /** - * Identifier for the search. This value is only returned for async and saved - * synchronous searches. For CSV, TSV, and TXT responses, this value is returned - * in the `Async-ID` HTTP header. + * Column headings for the search results. Each object is a column. */ - id?: Id + columns?: Column[] /** - * If `true`, the search is still running. If false, the search has finished. - * This value is only returned for async and saved synchronous searches. For - * CSV, TSV, and TXT responses, this value is returned in the `Async-partial` - * HTTP header. + * The cursor for the next set of paginated results. + * For CSV, TSV, and TXT responses, this value is returned in the `Cursor` HTTP header. */ - is_running?: boolean + cursor?: string /** - * 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. This value is only returned for async and saved synchronous searches. - * For CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header. + * The identifier for the search. + * This value is returned only for async and saved synchronous searches. + * For CSV, TSV, and TXT responses, this value is returned in the `Async-ID` HTTP header. */ - is_partial?: boolean + id?: Id /** - * Column headings for the search results. Each object is a column. + * If `true`, the search is still running. + * If `false`, the search has finished. + * This value is returned only for async and saved synchronous searches. + * For CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header. */ - columns?: Column[] + is_running?: boolean /** - * Cursor for the next set of paginated results. For CSV, TSV, and - * TXT responses, this value is returned in the `Cursor` HTTP header. + * 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. + * This value is returned only for async and saved synchronous searches. + * For CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header. */ - cursor?: string + is_partial?: boolean /** - * Values for the search results. + * The values for the search results. */ rows: Row[] } diff --git a/specification/sql/query/examples/request/QuerySqlRequestExample1.yaml b/specification/sql/query/examples/request/QuerySqlRequestExample1.yaml new file mode 100644 index 0000000000..64207d8ac5 --- /dev/null +++ b/specification/sql/query/examples/request/QuerySqlRequestExample1.yaml @@ -0,0 +1,7 @@ +# summary: +# method_request: POST _sql?format=txt +description: Run `POST _sql?format=txt` to get results for an SQL search. +# type: request +value: + "{\n \"query\": \"SELECT * FROM library ORDER BY page_count DESC LIMIT 5\"\ + \n}" diff --git a/specification/sql/translate/TranslateSqlRequest.ts b/specification/sql/translate/TranslateSqlRequest.ts index 418c8a2426..5ecf9632de 100644 --- a/specification/sql/translate/TranslateSqlRequest.ts +++ b/specification/sql/translate/TranslateSqlRequest.ts @@ -25,9 +25,12 @@ import { TimeZone } from '@_types/Time' /** * Translate SQL into Elasticsearch queries. * Translate an SQL search into a search API request containing Query DSL. + * It accepts the same request body parameters as the SQL search API, excluding `cursor`. * @rest_spec_name sql.translate * @availability stack since=6.3.0 stability=stable * @availability serverless stability=stable visibility=public + * @index_privileges read + * @doc_id sql-translate-api */ export interface Request extends RequestBase { body: { @@ -37,18 +40,18 @@ export interface Request extends RequestBase { */ fetch_size?: integer /** - * Elasticsearch query DSL for additional filtering. - * @doc_id sql-rest-filtering + * The Elasticsearch query DSL for additional filtering. + * @ext_doc_id sql-rest-filtering * @server_default none */ filter?: QueryContainer /** - * SQL query to run. + * The SQL query to run. */ query: string /** - * ISO-8601 time zone ID for the search. - * @doc_url https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html + * The ISO-8601 time zone ID for the search. + * @ext_doc_id time-zone-id * @server_default Z */ time_zone?: TimeZone diff --git a/specification/sql/translate/examples/request/TranslateSqlRequestExample1.yaml b/specification/sql/translate/examples/request/TranslateSqlRequestExample1.yaml new file mode 100644 index 0000000000..7579045f2c --- /dev/null +++ b/specification/sql/translate/examples/request/TranslateSqlRequestExample1.yaml @@ -0,0 +1,7 @@ +summary: sql/apis/sql-translate-api.asciidoc:12 +method_request: POST _sql/translate +description: '' +type: request +value: + "{\n \"query\": \"SELECT * FROM library ORDER BY page_count DESC\",\n \"\ + fetch_size\": 10\n}"