diff --git a/docs/overlays/elasticsearch-openapi-overlays.yaml b/docs/overlays/elasticsearch-openapi-overlays.yaml index 90c707d8e7..7d73e1fc07 100644 --- a/docs/overlays/elasticsearch-openapi-overlays.yaml +++ b/docs/overlays/elasticsearch-openapi-overlays.yaml @@ -404,6 +404,16 @@ actions: examples: postBehavioralAnalyticsEventRequestExample1: $ref: "../../specification/search_application/post_behavioral_analytics_event/examples/request/BehavioralAnalyticsEventPostRequestExample1.yaml" +## Examples for esql + - target: "$.paths['/_query/async']['post']" + description: "Add examples for async esql query operation" + update: + requestBody: + content: + application/json: + examples: + esqlAsyncQueryRequestExample1: + $ref: "../../specification/esql/async_query/examples/request/AsyncQueryRequestExample1.yaml" ## Examples for indices - target: "$.paths['/_lifecycle/stats']['get']" description: "Add examples for get lifecycle stats operation" diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index dc8b7beb04..dfb614e536 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -8630,6 +8630,278 @@ "x-state": "Added in 7.9.0" } }, + "/_query/async": { + "post": { + "tags": [ + "esql" + ], + "summary": "Run an async ES|QL query", + "description": "Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available.\n\nThe API accepts the same parameters and request body as the synchronous query API, along with additional async related properties.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html" + }, + "operationId": "esql-async-query", + "parameters": [ + { + "in": "query", + "name": "delimiter", + "description": "The character to use between values within a CSV row.\nIt is valid only for the CSV format.", + "deprecated": false, + "schema": { + "type": "string" + }, + "style": "form" + }, + { + "in": "query", + "name": "drop_null_columns", + "description": "Indicates whether columns that are entirely `null` will be removed from the `columns` and `values` portion of the results.\nIf `true`, the response will include an extra section under the name `all_columns` which has the name of all the columns.", + "deprecated": false, + "schema": { + "type": "boolean" + }, + "style": "form" + }, + { + "in": "query", + "name": "format", + "description": "A short version of the Accept header, for example `json` or `yaml`.", + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/esql._types:EsqlFormat" + }, + "style": "form" + }, + { + "in": "query", + "name": "keep_alive", + "description": "The period for which the query and its results are stored in the cluster.\nThe default period is five days.\nWhen this period expires, the query and its results are deleted, even if the query is still ongoing.\nIf the `keep_on_completion` parameter is false, Elasticsearch only stores async queries that do not complete within the period set by the `wait_for_completion_timeout` parameter, regardless of this value.", + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types:Duration" + }, + "style": "form" + }, + { + "in": "query", + "name": "keep_on_completion", + "description": "Indicates whether the query and its results are stored in the cluster.\nIf false, the query and its results are stored in the cluster only if the request does not complete during the period set by the `wait_for_completion_timeout` parameter.", + "deprecated": false, + "schema": { + "type": "boolean" + }, + "style": "form" + }, + { + "in": "query", + "name": "wait_for_completion_timeout", + "description": "The period to wait for the request to finish.\nBy default, the request waits for 1 second for the query results.\nIf the query completes during this period, results are returned\nOtherwise, a query ID is returned that can later be used to retrieve the results.", + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types:Duration" + }, + "style": "form" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "columnar": { + "description": "By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.", + "type": "boolean" + }, + "filter": { + "$ref": "#/components/schemas/_types.query_dsl:QueryContainer" + }, + "locale": { + "type": "string" + }, + "params": { + "description": "To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.", + "type": "array", + "items": { + "$ref": "#/components/schemas/_types:FieldValue" + } + }, + "profile": { + "description": "If provided and `true` the response will include an extra `profile` object\nwith information on how the query was executed. This information is for human debugging\nand its format can change at any time but it can give some insight into the performance\nof each part of the query.", + "type": "boolean" + }, + "query": { + "description": "The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.", + "type": "string" + }, + "tables": { + "description": "Tables to use with the LOOKUP operation. The top level key is the table\nname and the next level key is the column name.", + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/esql._types:TableValuesContainer" + } + } + } + }, + "required": [ + "query" + ] + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "columns": { + "$ref": "#/components/schemas/_types:EsqlColumns" + }, + "id": { + "description": "A query identifier that is provided only when one of the following conditions is met:\n\n* A query request does not return complete results during the period specified in the `wait_for_completion_timeout` parameter.\n* The `keep_on_completion` parameter value is true.\n\nYou can use this ID with the `GET /_query/async/` API to get the current status and available results for the query.", + "type": "string" + }, + "is_running": { + "description": "Indicates whether the query is still running.\nIf the value is false, the async query has finished and the results are returned.", + "type": "boolean" + } + }, + "required": [ + "is_running" + ] + } + } + } + } + }, + "x-state": "Added in 8.13.0" + } + }, + "/_query/async/{id}": { + "get": { + "tags": [ + "esql" + ], + "summary": "Get async ES|QL query results", + "description": "Get the current status and available results or stored results for an ES|QL asynchronous query.\nIf the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can retrieve the results using this API.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html" + }, + "operationId": "esql-async-query-get", + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The unique identifier of the query.\nA query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time.\nA query ID is also provided when the request was submitted with the `keep_on_completion` parameter set to `true`.", + "required": true, + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types:Id" + }, + "style": "simple" + }, + { + "in": "query", + "name": "drop_null_columns", + "description": "Indicates whether columns that are entirely `null` will be removed from the `columns` and `values` portion of the results.\nIf `true`, the response will include an extra section under the name `all_columns` which has the name of all the columns.", + "deprecated": false, + "schema": { + "type": "boolean" + }, + "style": "form" + }, + { + "in": "query", + "name": "keep_alive", + "description": "The period for which the query and its results are stored in the cluster.\nWhen this period expires, the query and its results are deleted, even if the query is still ongoing.", + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types:Duration" + }, + "style": "form" + }, + { + "in": "query", + "name": "wait_for_completion_timeout", + "description": "The period to wait for the request to finish.\nBy default, the request waits for complete query results.\nIf the request completes during the period specified in this parameter, complete query results are returned.\nOtherwise, the response returns an `is_running` value of `true` and no results.", + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types:Duration" + }, + "style": "form" + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "columns": { + "$ref": "#/components/schemas/_types:EsqlColumns" + }, + "is_running": { + "description": "Indicates whether the query is still running.\nIf the value is false, the async query has finished and the results are returned.", + "type": "boolean" + } + }, + "required": [ + "is_running" + ] + } + } + } + } + }, + "x-state": "Added in 8.13.0" + }, + "delete": { + "tags": [ + "esql" + ], + "summary": "Delete an async ES|QL query", + "description": "If the query is still running, it is cancelled.\nOtherwise, the stored results are deleted.\n\nIf the Elasticsearch security features are enabled, only the following users can use this API to delete a query:\n\n* The authenticated user that submitted the original query request\n* Users with the `cancel_task` cluster privilege", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html" + }, + "operationId": "esql-async-query-delete", + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The unique identifier of the query.\nA query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time.\nA query ID is also provided when the request was submitted with the `keep_on_completion` parameter set to `true`.", + "required": true, + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types:Id" + }, + "style": "simple" + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/_types:AcknowledgedResponseBase" + } + } + } + } + }, + "x-state": "Added in 8.13.0" + } + }, "/_query": { "post": { "tags": [ @@ -8648,7 +8920,7 @@ "description": "A short version of the Accept header, e.g. json, yaml.", "deprecated": false, "schema": { - "$ref": "#/components/schemas/esql.query:EsqlFormat" + "$ref": "#/components/schemas/esql._types:EsqlFormat" }, "style": "form" }, @@ -68445,7 +68717,7 @@ "head" ] }, - "esql.query:EsqlFormat": { + "esql._types:EsqlFormat": { "type": "string", "enum": [ "csv", diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index 15f1dd3317..189e532711 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -5098,7 +5098,7 @@ "description": "A short version of the Accept header, e.g. json, yaml.", "deprecated": false, "schema": { - "$ref": "#/components/schemas/esql.query:EsqlFormat" + "$ref": "#/components/schemas/esql._types:EsqlFormat" }, "style": "form" }, @@ -44633,7 +44633,7 @@ "head" ] }, - "esql.query:EsqlFormat": { + "esql._types:EsqlFormat": { "type": "string", "enum": [ "csv", diff --git a/output/schema/schema.json b/output/schema/schema.json index 805c365ece..9c14cfaf05 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -4831,19 +4831,34 @@ { "availability": { "stack": { + "since": "8.13.0", "stability": "stable", "visibility": "public" } }, - "description": "Executes an ESQL request asynchronously", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/esql-async-query-api.html", + "description": "Run an async ES|QL query.\nAsynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available.\n\nThe API accepts the same parameters and request body as the synchronous query API, along with additional async related properties.", + "docId": "esql-async-query", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-async-query-api.html", + "extDocId": "esql", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql.html", "name": "esql.async_query", - "request": null, + "privileges": { + "index": [ + "read" + ] + }, + "request": { + "name": "Request", + "namespace": "esql.async_query" + }, "requestBodyRequired": true, "requestMediaType": [ "application/json" ], - "response": null, + "response": { + "name": "Response", + "namespace": "esql.async_query" + }, "responseMediaType": [ "application/json" ], @@ -4859,16 +4874,61 @@ { "availability": { "stack": { + "since": "8.13.0", "stability": "stable", "visibility": "public" } }, - "description": "Retrieves the results of a previously submitted async query request given its ID.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/esql-async-query-get-api.html", + "description": "Delete an async ES|QL query.\nIf the query is still running, it is cancelled.\nOtherwise, the stored results are deleted.\n\nIf the Elasticsearch security features are enabled, only the following users can use this API to delete a query:\n\n* The authenticated user that submitted the original query request\n* Users with the `cancel_task` cluster privilege", + "docId": "esql-async-query-delete", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-async-query-delete-api.html", + "extDocId": "esql", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql.html", + "name": "esql.async_query_delete", + "request": { + "name": "Request", + "namespace": "esql.async_query_delete" + }, + "requestBodyRequired": false, + "response": { + "name": "Response", + "namespace": "esql.async_query_delete" + }, + "responseMediaType": [ + "application/json" + ], + "urls": [ + { + "methods": [ + "DELETE" + ], + "path": "/_query/async/{id}" + } + ] + }, + { + "availability": { + "stack": { + "since": "8.13.0", + "stability": "stable", + "visibility": "public" + } + }, + "description": "Get async ES|QL query results.\nGet the current status and available results or stored results for an ES|QL asynchronous query.\nIf the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can retrieve the results using this API.", + "docId": "esql-async-query-get", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-async-query-get-api.html", + "extDocId": "esql", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql.html", "name": "esql.async_query_get", - "request": null, + "request": { + "name": "Request", + "namespace": "esql.async_query_get" + }, "requestBodyRequired": false, - "response": null, + "response": { + "name": "Response", + "namespace": "esql.async_query_get" + }, "responseMediaType": [ "application/json" ], @@ -120750,6 +120810,40 @@ }, "specLocation": "eql/search/types.ts#L20-L32" }, + { + "kind": "enum", + "members": [ + { + "name": "csv" + }, + { + "name": "json" + }, + { + "name": "tsv" + }, + { + "name": "txt" + }, + { + "name": "yaml" + }, + { + "name": "cbor" + }, + { + "name": "smile" + }, + { + "name": "arrow" + } + ], + "name": { + "name": "EsqlFormat", + "namespace": "esql._types" + }, + "specLocation": "esql/_types/QueryParameters.ts#L20-L29" + }, { "kind": "interface", "name": { @@ -120940,38 +121034,428 @@ } }, { - "kind": "enum", - "members": [ + "kind": "request", + "attachedBehaviors": [ + "CommonQueryParameters" + ], + "body": { + "kind": "properties", + "properties": [ + { + "description": "By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.", + "name": "columnar", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } + }, + { + "description": "Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on.", + "name": "filter", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "QueryContainer", + "namespace": "_types.query_dsl" + } + } + }, + { + "name": "locale", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } + }, + { + "description": "To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.", + "docId": "esql-query-params", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-rest.html#esql-rest-params", + "name": "params", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "FieldValue", + "namespace": "_types" + } + } + } + }, + { + "description": "If provided and `true` the response will include an extra `profile` object\nwith information on how the query was executed. This information is for human debugging\nand its format can change at any time but it can give some insight into the performance\nof each part of the query.", + "name": "profile", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } + }, + { + "description": "The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.", + "name": "query", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } + }, + { + "description": "Tables to use with the LOOKUP operation. The top level key is the table\nname and the next level key is the column name.", + "name": "tables", + "required": false, + "type": { + "kind": "dictionary_of", + "key": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + }, + "singleKey": false, + "value": { + "kind": "dictionary_of", + "key": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + }, + "singleKey": false, + "value": { + "kind": "instance_of", + "type": { + "name": "TableValuesContainer", + "namespace": "esql._types" + } + } + } + } + } + ] + }, + "description": "Run an async ES|QL query.\nAsynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available.\n\nThe API accepts the same parameters and request body as the synchronous query API, along with additional async related properties.", + "inherits": { + "type": { + "name": "RequestBase", + "namespace": "_types" + } + }, + "name": { + "name": "Request", + "namespace": "esql.async_query" + }, + "path": [], + "query": [ { - "name": "csv" + "description": "The character to use between values within a CSV row.\nIt is valid only for the CSV format.", + "name": "delimiter", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } }, { - "name": "json" + "description": "Indicates whether columns that are entirely `null` will be removed from the `columns` and `values` portion of the results.\nIf `true`, the response will include an extra section under the name `all_columns` which has the name of all the columns.", + "name": "drop_null_columns", + "required": false, + "serverDefault": false, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } }, { - "name": "tsv" + "description": "A short version of the Accept header, for example `json` or `yaml`.", + "name": "format", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "EsqlFormat", + "namespace": "esql._types" + } + } }, { - "name": "txt" + "description": "The period for which the query and its results are stored in the cluster.\nThe default period is five days.\nWhen this period expires, the query and its results are deleted, even if the query is still ongoing.\nIf the `keep_on_completion` parameter is false, Elasticsearch only stores async queries that do not complete within the period set by the `wait_for_completion_timeout` parameter, regardless of this value.", + "name": "keep_alive", + "required": false, + "serverDefault": "5d", + "type": { + "kind": "instance_of", + "type": { + "name": "Duration", + "namespace": "_types" + } + } }, { - "name": "yaml" + "description": "Indicates whether the query and its results are stored in the cluster.\nIf false, the query and its results are stored in the cluster only if the request does not complete during the period set by the `wait_for_completion_timeout` parameter.", + "name": "keep_on_completion", + "required": false, + "serverDefault": false, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } }, { - "name": "cbor" + "description": "The period to wait for the request to finish.\nBy default, the request waits for 1 second for the query results.\nIf the query completes during this period, results are returned\nOtherwise, a query ID is returned that can later be used to retrieve the results.", + "name": "wait_for_completion_timeout", + "required": false, + "serverDefault": "1s", + "type": { + "kind": "instance_of", + "type": { + "name": "Duration", + "namespace": "_types" + } + } + } + ], + "specLocation": "esql/async_query/AsyncQueryRequest.ts#L28-L118" + }, + { + "kind": "response", + "body": { + "kind": "properties", + "properties": [ + { + "name": "columns", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "EsqlColumns", + "namespace": "_types" + } + } + }, + { + "description": "A query identifier that is provided only when one of the following conditions is met:\n\n* A query request does not return complete results during the period specified in the `wait_for_completion_timeout` parameter.\n* The `keep_on_completion` parameter value is true.\n\nYou can use this ID with the `GET /_query/async/` API to get the current status and available results for the query.", + "name": "id", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } + }, + { + "description": "Indicates whether the query is still running.\nIf the value is false, the async query has finished and the results are returned.", + "name": "is_running", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } + } + ] + }, + "name": { + "name": "Response", + "namespace": "esql.async_query" + }, + "specLocation": "esql/async_query/AsyncQueryResponse.ts#L22-L40" + }, + { + "kind": "request", + "attachedBehaviors": [ + "CommonQueryParameters" + ], + "body": { + "kind": "no_body" + }, + "description": "Delete an async ES|QL query.\nIf the query is still running, it is cancelled.\nOtherwise, the stored results are deleted.\n\nIf the Elasticsearch security features are enabled, only the following users can use this API to delete a query:\n\n* The authenticated user that submitted the original query request\n* Users with the `cancel_task` cluster privilege", + "inherits": { + "type": { + "name": "RequestBase", + "namespace": "_types" + } + }, + "name": { + "name": "Request", + "namespace": "esql.async_query_delete" + }, + "path": [ + { + "description": "The unique identifier of the query.\nA query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time.\nA query ID is also provided when the request was submitted with the `keep_on_completion` parameter set to `true`.", + "name": "id", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "Id", + "namespace": "_types" + } + } + } + ], + "query": [], + "specLocation": "esql/async_query_delete/AsyncQueryDeleteRequest.ts#L23-L46" + }, + { + "kind": "response", + "body": { + "kind": "value", + "value": { + "kind": "instance_of", + "type": { + "name": "AcknowledgedResponseBase", + "namespace": "_types" + } + } + }, + "name": { + "name": "Response", + "namespace": "esql.async_query_delete" + }, + "specLocation": "esql/async_query_delete/AsyncQueryDeleteResponse.ts#L22-L24" + }, + { + "kind": "request", + "attachedBehaviors": [ + "CommonQueryParameters" + ], + "body": { + "kind": "no_body" + }, + "description": "Get async ES|QL query results.\nGet the current status and available results or stored results for an ES|QL asynchronous query.\nIf the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can retrieve the results using this API.", + "inherits": { + "type": { + "name": "RequestBase", + "namespace": "_types" + } + }, + "name": { + "name": "Request", + "namespace": "esql.async_query_get" + }, + "path": [ + { + "description": "The unique identifier of the query.\nA query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time.\nA query ID is also provided when the request was submitted with the `keep_on_completion` parameter set to `true`.", + "name": "id", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "Id", + "namespace": "_types" + } + } + } + ], + "query": [ + { + "description": "Indicates whether columns that are entirely `null` will be removed from the `columns` and `values` portion of the results.\nIf `true`, the response will include an extra section under the name `all_columns` which has the name of all the columns.", + "name": "drop_null_columns", + "required": false, + "serverDefault": false, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } }, { - "name": "smile" + "description": "The period for which the query and its results are stored in the cluster.\nWhen this period expires, the query and its results are deleted, even if the query is still ongoing.", + "name": "keep_alive", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "Duration", + "namespace": "_types" + } + } }, { - "name": "arrow" + "description": "The period to wait for the request to finish.\nBy default, the request waits for complete query results.\nIf the request completes during the period specified in this parameter, complete query results are returned.\nOtherwise, the response returns an `is_running` value of `true` and no results.", + "name": "wait_for_completion_timeout", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "Duration", + "namespace": "_types" + } + } } ], + "specLocation": "esql/async_query_get/AsyncQueryGetRequest.ts#L24-L62" + }, + { + "kind": "response", + "body": { + "kind": "properties", + "properties": [ + { + "name": "columns", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "EsqlColumns", + "namespace": "_types" + } + } + }, + { + "description": "Indicates whether the query is still running.\nIf the value is false, the async query has finished and the results are returned.", + "name": "is_running", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } + } + ] + }, "name": { - "name": "EsqlFormat", - "namespace": "esql.query" + "name": "Response", + "namespace": "esql.async_query_get" }, - "specLocation": "esql/query/QueryRequest.ts#L99-L108" + "specLocation": "esql/async_query_get/AsyncQueryGetResponse.ts#L22-L31" }, { "kind": "request", @@ -121114,7 +121598,7 @@ "kind": "instance_of", "type": { "name": "EsqlFormat", - "namespace": "esql.query" + "namespace": "esql._types" } } }, @@ -121144,7 +121628,7 @@ } } ], - "specLocation": "esql/query/QueryRequest.ts#L26-L97" + "specLocation": "esql/query/QueryRequest.ts#L27-L98" }, { "kind": "response", diff --git a/output/schema/validation-errors.json b/output/schema/validation-errors.json index 377bec7b49..3fa20882db 100644 --- a/output/schema/validation-errors.json +++ b/output/schema/validation-errors.json @@ -156,13 +156,9 @@ }, "esql.async_query": { "request": [ - "Missing request & response" - ], - "response": [] - }, - "esql.async_query_get": { - "request": [ - "Missing request & response" + "Request: query parameter 'keep_alive' does not exist in the json spec", + "Request: query parameter 'keep_on_completion' does not exist in the json spec", + "Request: query parameter 'wait_for_completion_timeout' does not exist in the json spec" ], "response": [] }, diff --git a/output/typescript/types.ts b/output/typescript/types.ts index 04b01383b7..679e2a2906 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -10491,6 +10491,8 @@ export type EqlSearchResponse = EqlEqlSearchResponseBase> + } +} + +export interface EsqlAsyncQueryResponse { + columns?: EsqlColumns + id?: string + is_running: boolean +} + +export interface EsqlAsyncQueryDeleteRequest extends RequestBase { + id: Id +} + +export type EsqlAsyncQueryDeleteResponse = AcknowledgedResponseBase + +export interface EsqlAsyncQueryGetRequest extends RequestBase { + id: Id + drop_null_columns?: boolean + keep_alive?: Duration + wait_for_completion_timeout?: Duration +} + +export interface EsqlAsyncQueryGetResponse { + columns?: EsqlColumns + is_running: boolean +} export interface EsqlQueryRequest extends RequestBase { - format?: EsqlQueryEsqlFormat + format?: EsqlEsqlFormat delimiter?: string drop_null_columns?: boolean body?: { diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index cd936f26a9..99c38a31c9 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -166,6 +166,9 @@ eql-missing-events,https://www.elastic.co/guide/en/elasticsearch/reference/{bran eql-syntax,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql-syntax.html eql,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql.html esql,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql.html +esql-async-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-async-query-api.html +esql-async-query-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-async-query-delete-api.html +esql-async-query-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-async-query-get-api.html esql-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-rest.html esql-query-params,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-rest.html#esql-rest-params esql-returning-localized-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-rest.html#esql-locale-param diff --git a/specification/_json_spec/esql.async_query_delete.json b/specification/_json_spec/esql.async_query_delete.json new file mode 100644 index 0000000000..a6339559af --- /dev/null +++ b/specification/_json_spec/esql.async_query_delete.json @@ -0,0 +1,27 @@ +{ + "esql.async_query_delete": { + "documentation": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/esql-async-query-delete-api.html", + "description": "Delete an async query request given its ID." + }, + "stability": "stable", + "visibility": "public", + "headers": { + "accept": ["application/json"] + }, + "url": { + "paths": [ + { + "path": "/_query/async/{id}", + "methods": ["DELETE"], + "parts": { + "id": { + "type": "string", + "description": "The async query ID" + } + } + } + ] + } + } +} diff --git a/specification/esql/_types/QueryParameters.ts b/specification/esql/_types/QueryParameters.ts new file mode 100644 index 0000000000..ec31f04e04 --- /dev/null +++ b/specification/esql/_types/QueryParameters.ts @@ -0,0 +1,29 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +export enum EsqlFormat { + csv, + json, + tsv, + txt, + yaml, + cbor, + smile, + arrow +} diff --git a/specification/esql/async_query/AsyncQueryRequest.ts b/specification/esql/async_query/AsyncQueryRequest.ts new file mode 100644 index 0000000000..0f2ed505ed --- /dev/null +++ b/specification/esql/async_query/AsyncQueryRequest.ts @@ -0,0 +1,118 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { EsqlFormat } from '@esql/_types/QueryParameters' +import { TableValuesContainer } from '@esql/_types/TableValuesContainer' +import { Dictionary } from '@spec_utils/Dictionary' +import { RequestBase } from '@_types/Base' +import { FieldValue } from '@_types/common' +import { QueryContainer } from '@_types/query_dsl/abstractions' +import { Duration } from '@_types/Time' + +/** + * Run an async ES|QL query. + * Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available. + * + * The API accepts the same parameters and request body as the synchronous query API, along with additional async related properties. + * @rest_spec_name esql.async_query + * @availability stack since=8.13.0 stability=stable visibility=public + * @doc_id esql-async-query + * @ext_doc_id esql + * @index_privileges read + */ +export interface Request extends RequestBase { + query_parameters: { + /** + * The character to use between values within a CSV row. + * It is valid only for the CSV format. + */ + delimiter?: string + /** + * Indicates whether columns that are entirely `null` will be removed from the `columns` and `values` portion of the results. + * If `true`, the response will include an extra section under the name `all_columns` which has the name of all the columns. + * @server_default false + */ + drop_null_columns?: boolean + /** + * A short version of the Accept header, for example `json` or `yaml`. + */ + format?: EsqlFormat + /** + * The period for which the query and its results are stored in the cluster. + * The default period is five days. + * When this period expires, the query and its results are deleted, even if the query is still ongoing. + * If the `keep_on_completion` parameter is false, Elasticsearch only stores async queries that do not complete within the period set by the `wait_for_completion_timeout` parameter, regardless of this value. + * @server_default 5d + */ + keep_alive?: Duration + /** + * Indicates whether the query and its results are stored in the cluster. + * If false, the query and its results are stored in the cluster only if the request does not complete during the period set by the `wait_for_completion_timeout` parameter. + * @server_default false + */ + keep_on_completion?: boolean + /** + * The period to wait for the request to finish. + * By default, the request waits for 1 second for the query results. + * If the query completes during this period, results are returned + * Otherwise, a query ID is returned that can later be used to retrieve the results. + * @server_default 1s + */ + wait_for_completion_timeout?: Duration + } + /** + * Use the `query` element to start a query. Use `time_zone` to specify an execution time zone and `columnar` to format the answer. + */ + body: { + /** + * By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results. + */ + columnar?: boolean + /** + * Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on. + */ + filter?: QueryContainer + /* + * Returns results (especially dates) formatted per the conventions of the locale. + * @doc_id esql-returning-localized-results + */ + locale?: string + /** + * To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters. + * @doc_id esql-query-params + */ + params?: Array + /** + * If provided and `true` the response will include an extra `profile` object + * with information on how the query was executed. This information is for human debugging + * and its format can change at any time but it can give some insight into the performance + * of each part of the query. + */ + profile?: boolean + /** + * The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results. + */ + query: string + /** + * Tables to use with the LOOKUP operation. The top level key is the table + * name and the next level key is the column name. + */ + tables?: Dictionary> + } +} diff --git a/specification/esql/async_query/AsyncQueryResponse.ts b/specification/esql/async_query/AsyncQueryResponse.ts new file mode 100644 index 0000000000..a824a8411b --- /dev/null +++ b/specification/esql/async_query/AsyncQueryResponse.ts @@ -0,0 +1,40 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { EsqlColumns } from '@_types/Binary' + +export class Response { + body: { + columns?: EsqlColumns + /** + * A query identifier that is provided only when one of the following conditions is met: + * + * * A query request does not return complete results during the period specified in the `wait_for_completion_timeout` parameter. + * * The `keep_on_completion` parameter value is true. + * + * You can use this ID with the `GET /_query/async/` API to get the current status and available results for the query. + */ + id?: string + /** + * Indicates whether the query is still running. + * If the value is false, the async query has finished and the results are returned. + */ + is_running: boolean + } +} diff --git a/specification/esql/async_query/examples/request/AsyncQueryRequestExample1.yaml b/specification/esql/async_query/examples/request/AsyncQueryRequestExample1.yaml new file mode 100644 index 0000000000..1cafcc7712 --- /dev/null +++ b/specification/esql/async_query/examples/request/AsyncQueryRequestExample1.yaml @@ -0,0 +1,5 @@ +# summary: Get results for an async ES|QL query. +# method_request: "POST /_query/async" +# description: +# type: request +value: "{\n \"query\": \"\"\"\n FROM library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n \"\"\",\n \"wait_for_completion_timeout\": \"2s\"\n}" diff --git a/specification/esql/async_query_delete/AsyncQueryDeleteRequest.ts b/specification/esql/async_query_delete/AsyncQueryDeleteRequest.ts new file mode 100644 index 0000000000..9a78be3a87 --- /dev/null +++ b/specification/esql/async_query_delete/AsyncQueryDeleteRequest.ts @@ -0,0 +1,46 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { RequestBase } from '@_types/Base' +import { Id } from '@_types/common' + +/** + * Delete an async ES|QL query. + * If the query is still running, it is cancelled. + * Otherwise, the stored results are deleted. + * + * If the Elasticsearch security features are enabled, only the following users can use this API to delete a query: + * + * * The authenticated user that submitted the original query request + * * Users with the `cancel_task` cluster privilege + * @rest_spec_name esql.async_query_delete + * @availability stack since=8.13.0 stability=stable visibility=public + * @doc_id esql-async-query-delete + * @ext_doc_id esql + */ +export interface Request extends RequestBase { + path_parts: { + /** + * The unique identifier of the query. + * A query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time. + * A query ID is also provided when the request was submitted with the `keep_on_completion` parameter set to `true`. + */ + id: Id + } +} diff --git a/specification/esql/async_query_delete/AsyncQueryDeleteResponse.ts b/specification/esql/async_query_delete/AsyncQueryDeleteResponse.ts new file mode 100644 index 0000000000..7374da4a4c --- /dev/null +++ b/specification/esql/async_query_delete/AsyncQueryDeleteResponse.ts @@ -0,0 +1,24 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { AcknowledgedResponseBase } from '@_types/Base' + +export class Response { + body: AcknowledgedResponseBase +} diff --git a/specification/esql/async_query_get/AsyncQueryGetRequest.ts b/specification/esql/async_query_get/AsyncQueryGetRequest.ts new file mode 100644 index 0000000000..62b301f724 --- /dev/null +++ b/specification/esql/async_query_get/AsyncQueryGetRequest.ts @@ -0,0 +1,62 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { RequestBase } from '@_types/Base' +import { Id } from '@_types/common' +import { Duration } from '@_types/Time' + +/** + * Get async ES|QL query results. + * Get the current status and available results or stored results for an ES|QL asynchronous query. + * If the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can retrieve the results using this API. + * @rest_spec_name esql.async_query_get + * @availability stack since=8.13.0 stability=stable visibility=public + * @doc_id esql-async-query-get + * @ext_doc_id esql + */ +export interface Request extends RequestBase { + path_parts: { + /** + * The unique identifier of the query. + * A query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time. + * A query ID is also provided when the request was submitted with the `keep_on_completion` parameter set to `true`. + */ + id: Id + } + query_parameters: { + /** + * Indicates whether columns that are entirely `null` will be removed from the `columns` and `values` portion of the results. + * If `true`, the response will include an extra section under the name `all_columns` which has the name of all the columns. + * @server_default false + */ + drop_null_columns?: boolean + /** + * The period for which the query and its results are stored in the cluster. + * When this period expires, the query and its results are deleted, even if the query is still ongoing. + */ + keep_alive?: Duration + /** + * The period to wait for the request to finish. + * By default, the request waits for complete query results. + * If the request completes during the period specified in this parameter, complete query results are returned. + * Otherwise, the response returns an `is_running` value of `true` and no results. + */ + wait_for_completion_timeout?: Duration + } +} diff --git a/specification/esql/async_query_get/AsyncQueryGetResponse.ts b/specification/esql/async_query_get/AsyncQueryGetResponse.ts new file mode 100644 index 0000000000..47f6dc2e3b --- /dev/null +++ b/specification/esql/async_query_get/AsyncQueryGetResponse.ts @@ -0,0 +1,31 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { EsqlColumns } from '@_types/Binary' + +export class Response { + body: { + columns?: EsqlColumns + /** + * Indicates whether the query is still running. + * If the value is false, the async query has finished and the results are returned. + */ + is_running: boolean + } +} diff --git a/specification/esql/query/QueryRequest.ts b/specification/esql/query/QueryRequest.ts index b9dfbd943d..a9097b29b0 100644 --- a/specification/esql/query/QueryRequest.ts +++ b/specification/esql/query/QueryRequest.ts @@ -17,6 +17,7 @@ * under the License. */ +import { EsqlFormat } from '@esql/_types/QueryParameters' import { TableValuesContainer } from '@esql/_types/TableValuesContainer' import { Dictionary } from '@spec_utils/Dictionary' import { RequestBase } from '@_types/Base' @@ -95,14 +96,3 @@ export interface Request extends RequestBase { tables?: Dictionary> } } - -export enum EsqlFormat { - csv, - json, - tsv, - txt, - yaml, - cbor, - smile, - arrow -}