From dd3cc6a3831669da5b22c630cb1c2d0e05b9cf59 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 4 Dec 2024 16:59:49 -0800 Subject: [PATCH] [DOCS] Add SQL operation summaries (#3221) (#3229) (cherry picked from commit 17a69645543e5566fcdcd4ad82e4da94d60a826c) Co-authored-by: Lisa Cawley --- output/openapi/elasticsearch-openapi.json | 24 +++++++----- .../elasticsearch-serverless-openapi.json | 24 +++++++----- output/schema/schema.json | 38 +++++++++---------- .../sql/clear_cursor/ClearSqlCursorRequest.ts | 1 + .../sql/delete_async/SqlDeleteAsyncRequest.ts | 3 ++ .../sql/get_async/SqlGetAsyncRequest.ts | 2 + .../SqlGetAsyncStatusRequest.ts | 2 + specification/sql/query/QuerySqlRequest.ts | 2 + .../sql/translate/TranslateSqlRequest.ts | 2 + 9 files changed, 61 insertions(+), 37 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index bce163a970..9e44615a60 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -32132,7 +32132,7 @@ "tags": [ "sql" ], - "summary": "Clears the SQL cursor", + "summary": "Clear an SQL search cursor", "operationId": "sql-clear-cursor", "requestBody": { "content": { @@ -32181,8 +32181,8 @@ "tags": [ "sql" ], - "summary": "Deletes an async SQL search or a stored synchronous SQL search", - "description": "If the search is still running, the API cancels it.", + "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.", "operationId": "sql-delete-async", "parameters": [ { @@ -32217,7 +32217,8 @@ "tags": [ "sql" ], - "summary": "Returns the current status and available results for an async SQL search or stored synchronous SQL search", + "summary": "Get async SQL search results", + "description": "Get the current status and available results for an async SQL search or stored synchronous SQL search.", "operationId": "sql-get-async", "parameters": [ { @@ -32329,7 +32330,8 @@ "tags": [ "sql" ], - "summary": "Returns the current status of an async SQL search or a stored synchronous SQL search", + "summary": "Get the async SQL search status", + "description": "Get the current status of an async SQL search or a stored synchronous SQL search.", "operationId": "sql-get-async-status", "parameters": [ { @@ -32394,7 +32396,8 @@ "tags": [ "sql" ], - "summary": "Executes a SQL request", + "summary": "Get SQL search results", + "description": "Run an SQL request.", "operationId": "sql-query-1", "parameters": [ { @@ -32415,7 +32418,8 @@ "tags": [ "sql" ], - "summary": "Executes a SQL request", + "summary": "Get SQL search results", + "description": "Run an SQL request.", "operationId": "sql-query", "parameters": [ { @@ -32438,7 +32442,8 @@ "tags": [ "sql" ], - "summary": "Translates SQL into Elasticsearch queries", + "summary": "Translate SQL into Elasticsearch queries", + "description": "Translate an SQL search into a search API request containing Query DSL.", "operationId": "sql-translate-1", "requestBody": { "$ref": "#/components/requestBodies/sql.translate" @@ -32454,7 +32459,8 @@ "tags": [ "sql" ], - "summary": "Translates SQL into Elasticsearch queries", + "summary": "Translate SQL into Elasticsearch queries", + "description": "Translate an SQL search into a search API request containing Query DSL.", "operationId": "sql-translate", "requestBody": { "$ref": "#/components/requestBodies/sql.translate" diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index cca4e875b2..9946a4ae6f 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -17464,7 +17464,7 @@ "tags": [ "sql" ], - "summary": "Clears the SQL cursor", + "summary": "Clear an SQL search cursor", "operationId": "sql-clear-cursor", "requestBody": { "content": { @@ -17513,8 +17513,8 @@ "tags": [ "sql" ], - "summary": "Deletes an async SQL search or a stored synchronous SQL search", - "description": "If the search is still running, the API cancels it.", + "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.", "operationId": "sql-delete-async", "parameters": [ { @@ -17549,7 +17549,8 @@ "tags": [ "sql" ], - "summary": "Returns the current status and available results for an async SQL search or stored synchronous SQL search", + "summary": "Get async SQL search results", + "description": "Get the current status and available results for an async SQL search or stored synchronous SQL search.", "operationId": "sql-get-async", "parameters": [ { @@ -17661,7 +17662,8 @@ "tags": [ "sql" ], - "summary": "Returns the current status of an async SQL search or a stored synchronous SQL search", + "summary": "Get the async SQL search status", + "description": "Get the current status of an async SQL search or a stored synchronous SQL search.", "operationId": "sql-get-async-status", "parameters": [ { @@ -17726,7 +17728,8 @@ "tags": [ "sql" ], - "summary": "Executes a SQL request", + "summary": "Get SQL search results", + "description": "Run an SQL request.", "operationId": "sql-query-1", "parameters": [ { @@ -17747,7 +17750,8 @@ "tags": [ "sql" ], - "summary": "Executes a SQL request", + "summary": "Get SQL search results", + "description": "Run an SQL request.", "operationId": "sql-query", "parameters": [ { @@ -17770,7 +17774,8 @@ "tags": [ "sql" ], - "summary": "Translates SQL into Elasticsearch queries", + "summary": "Translate SQL into Elasticsearch queries", + "description": "Translate an SQL search into a search API request containing Query DSL.", "operationId": "sql-translate-1", "requestBody": { "$ref": "#/components/requestBodies/sql.translate" @@ -17786,7 +17791,8 @@ "tags": [ "sql" ], - "summary": "Translates SQL into Elasticsearch queries", + "summary": "Translate SQL into Elasticsearch queries", + "description": "Translate an SQL search into a search API request containing Query DSL.", "operationId": "sql-translate", "requestBody": { "$ref": "#/components/requestBodies/sql.translate" diff --git a/output/schema/schema.json b/output/schema/schema.json index af5719be61..e5b792ac0a 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -18487,7 +18487,7 @@ "stability": "stable" } }, - "description": "Clears the SQL cursor", + "description": "Clear an SQL search cursor.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/clear-sql-cursor-api.html", "name": "sql.clear_cursor", "request": { @@ -18525,7 +18525,7 @@ "stability": "stable" } }, - "description": "Deletes an async SQL search or a stored synchronous SQL search. If 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.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/delete-async-sql-search-api.html", "name": "sql.delete_async", "request": { @@ -18560,7 +18560,7 @@ "stability": "stable" } }, - "description": "Returns 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.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/get-async-sql-search-api.html", "name": "sql.get_async", "request": { @@ -18595,7 +18595,7 @@ "stability": "stable" } }, - "description": "Returns the current status of an async SQL search or a stored synchronous SQL search", + "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", "name": "sql.get_async_status", "request": { @@ -18630,7 +18630,7 @@ "stability": "stable" } }, - "description": "Executes a SQL request", + "description": "Get SQL search results.\nRun an SQL request.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-search-api.html", "name": "sql.query", "request": { @@ -18669,7 +18669,7 @@ "stability": "stable" } }, - "description": "Translates SQL into Elasticsearch queries", + "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", "name": "sql.translate", "request": { @@ -203973,7 +203973,7 @@ } ] }, - "description": "Clears the SQL cursor", + "description": "Clear an SQL search cursor.", "inherits": { "type": { "name": "RequestBase", @@ -203986,7 +203986,7 @@ }, "path": [], "query": [], - "specLocation": "sql/clear_cursor/ClearSqlCursorRequest.ts#L22-L34" + "specLocation": "sql/clear_cursor/ClearSqlCursorRequest.ts#L22-L35" }, { "kind": "response", @@ -204020,7 +204020,7 @@ "body": { "kind": "no_body" }, - "description": "Deletes an async SQL search or a stored synchronous SQL search. If 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.", "inherits": { "type": { "name": "RequestBase", @@ -204046,7 +204046,7 @@ } ], "query": [], - "specLocation": "sql/delete_async/SqlDeleteAsyncRequest.ts#L23-L35" + "specLocation": "sql/delete_async/SqlDeleteAsyncRequest.ts#L23-L38" }, { "kind": "response", @@ -204074,7 +204074,7 @@ "body": { "kind": "no_body" }, - "description": "Returns 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.", "inherits": { "type": { "name": "RequestBase", @@ -204150,7 +204150,7 @@ } } ], - "specLocation": "sql/get_async/SqlGetAsyncRequest.ts#L24-L58" + "specLocation": "sql/get_async/SqlGetAsyncRequest.ts#L24-L60" }, { "kind": "response", @@ -204251,7 +204251,7 @@ "body": { "kind": "no_body" }, - "description": "Returns the current status of an async SQL search or a stored synchronous SQL search", + "description": "Get the async SQL search status.\nGet the current status of an async SQL search or a stored synchronous SQL search.", "inherits": { "type": { "name": "RequestBase", @@ -204277,7 +204277,7 @@ } ], "query": [], - "specLocation": "sql/get_async_status/SqlGetAsyncStatusRequest.ts#L23-L35" + "specLocation": "sql/get_async_status/SqlGetAsyncStatusRequest.ts#L23-L37" }, { "kind": "response", @@ -204604,7 +204604,7 @@ } ] }, - "description": "Executes a SQL request", + "description": "Get SQL search results.\nRun an SQL request.", "inherits": { "type": { "name": "RequestBase", @@ -204632,7 +204632,7 @@ } } ], - "specLocation": "sql/query/QuerySqlRequest.ts#L28-L122" + "specLocation": "sql/query/QuerySqlRequest.ts#L28-L124" }, { "kind": "response", @@ -204754,7 +204754,7 @@ "name": "SqlFormat", "namespace": "sql.query" }, - "specLocation": "sql/query/QuerySqlRequest.ts#L124-L132" + "specLocation": "sql/query/QuerySqlRequest.ts#L126-L134" }, { "kind": "request", @@ -204820,7 +204820,7 @@ } ] }, - "description": "Translates SQL into Elasticsearch queries", + "description": "Translate SQL into Elasticsearch queries.\nTranslate an SQL search into a search API request containing Query DSL.", "inherits": { "type": { "name": "RequestBase", @@ -204833,7 +204833,7 @@ }, "path": [], "query": [], - "specLocation": "sql/translate/TranslateSqlRequest.ts#L25-L54" + "specLocation": "sql/translate/TranslateSqlRequest.ts#L25-L56" }, { "kind": "response", diff --git a/specification/sql/clear_cursor/ClearSqlCursorRequest.ts b/specification/sql/clear_cursor/ClearSqlCursorRequest.ts index 08ac50c85d..1961b1a53d 100644 --- a/specification/sql/clear_cursor/ClearSqlCursorRequest.ts +++ b/specification/sql/clear_cursor/ClearSqlCursorRequest.ts @@ -20,6 +20,7 @@ import { RequestBase } from '@_types/Base' /** + * Clear an SQL search cursor. * @rest_spec_name sql.clear_cursor * @availability stack since=6.3.0 stability=stable * @availability serverless stability=stable visibility=public diff --git a/specification/sql/delete_async/SqlDeleteAsyncRequest.ts b/specification/sql/delete_async/SqlDeleteAsyncRequest.ts index ad71d9e959..b4ef516e60 100644 --- a/specification/sql/delete_async/SqlDeleteAsyncRequest.ts +++ b/specification/sql/delete_async/SqlDeleteAsyncRequest.ts @@ -21,6 +21,9 @@ import { RequestBase } from '@_types/Base' 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. * @rest_spec_name sql.delete_async * @availability stack since=7.15.0 stability=stable * @availability serverless stability=stable visibility=public diff --git a/specification/sql/get_async/SqlGetAsyncRequest.ts b/specification/sql/get_async/SqlGetAsyncRequest.ts index e4f0d12baf..4159eba4ed 100644 --- a/specification/sql/get_async/SqlGetAsyncRequest.ts +++ b/specification/sql/get_async/SqlGetAsyncRequest.ts @@ -22,6 +22,8 @@ import { Id } from '@_types/common' 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. * @rest_spec_name sql.get_async * @availability stack since=7.15.0 stability=stable * @availability serverless stability=stable visibility=public diff --git a/specification/sql/get_async_status/SqlGetAsyncStatusRequest.ts b/specification/sql/get_async_status/SqlGetAsyncStatusRequest.ts index a66076b6d7..ed6be9c7cc 100644 --- a/specification/sql/get_async_status/SqlGetAsyncStatusRequest.ts +++ b/specification/sql/get_async_status/SqlGetAsyncStatusRequest.ts @@ -21,6 +21,8 @@ import { RequestBase } from '@_types/Base' import { Id } from '@_types/common' /** + * Get the async SQL search status. + * Get the current status of an async SQL search or a stored synchronous SQL search. * @rest_spec_name sql.get_async_status * @availability stack since=7.15.0 stability=stable * @availability serverless stability=stable visibility=public diff --git a/specification/sql/query/QuerySqlRequest.ts b/specification/sql/query/QuerySqlRequest.ts index 3c07272135..11625631d9 100644 --- a/specification/sql/query/QuerySqlRequest.ts +++ b/specification/sql/query/QuerySqlRequest.ts @@ -26,6 +26,8 @@ import { QueryContainer } from '@_types/query_dsl/abstractions' import { Duration, TimeZone } from '@_types/Time' /** + * Get SQL search results. + * Run an SQL request. * @rest_spec_name sql.query * @availability stack since=6.3.0 stability=stable * @availability serverless stability=stable visibility=public diff --git a/specification/sql/translate/TranslateSqlRequest.ts b/specification/sql/translate/TranslateSqlRequest.ts index ead27ce70b..418c8a2426 100644 --- a/specification/sql/translate/TranslateSqlRequest.ts +++ b/specification/sql/translate/TranslateSqlRequest.ts @@ -23,6 +23,8 @@ import { QueryContainer } from '@_types/query_dsl/abstractions' import { TimeZone } from '@_types/Time' /** + * Translate SQL into Elasticsearch queries. + * Translate an SQL search into a search API request containing Query DSL. * @rest_spec_name sql.translate * @availability stack since=6.3.0 stability=stable * @availability serverless stability=stable visibility=public