From 9f841b15e48df831b607d52c2452f755905d21be Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 4 Dec 2024 14:55:24 -0800 Subject: [PATCH] [DOCS] Add SQL operation summaries (#3221) (cherry picked from commit 17a69645543e5566fcdcd4ad82e4da94d60a826c) --- 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 3e158f92a4..99d74e3f25 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -32137,7 +32137,7 @@ "tags": [ "sql" ], - "summary": "Clears the SQL cursor", + "summary": "Clear an SQL search cursor", "operationId": "sql-clear-cursor", "requestBody": { "content": { @@ -32186,8 +32186,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": [ { @@ -32222,7 +32222,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": [ { @@ -32334,7 +32335,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": [ { @@ -32399,7 +32401,8 @@ "tags": [ "sql" ], - "summary": "Executes a SQL request", + "summary": "Get SQL search results", + "description": "Run an SQL request.", "operationId": "sql-query-1", "parameters": [ { @@ -32420,7 +32423,8 @@ "tags": [ "sql" ], - "summary": "Executes a SQL request", + "summary": "Get SQL search results", + "description": "Run an SQL request.", "operationId": "sql-query", "parameters": [ { @@ -32443,7 +32447,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" @@ -32459,7 +32464,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 c8ef4cfb0b..c169c7ebd1 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -17476,7 +17476,7 @@ "tags": [ "sql" ], - "summary": "Clears the SQL cursor", + "summary": "Clear an SQL search cursor", "operationId": "sql-clear-cursor", "requestBody": { "content": { @@ -17525,8 +17525,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": [ { @@ -17561,7 +17561,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": [ { @@ -17673,7 +17674,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": [ { @@ -17738,7 +17740,8 @@ "tags": [ "sql" ], - "summary": "Executes a SQL request", + "summary": "Get SQL search results", + "description": "Run an SQL request.", "operationId": "sql-query-1", "parameters": [ { @@ -17759,7 +17762,8 @@ "tags": [ "sql" ], - "summary": "Executes a SQL request", + "summary": "Get SQL search results", + "description": "Run an SQL request.", "operationId": "sql-query", "parameters": [ { @@ -17782,7 +17786,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" @@ -17798,7 +17803,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 2939998cb2..f6cd6094f8 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": { @@ -203542,7 +203542,7 @@ } ] }, - "description": "Clears the SQL cursor", + "description": "Clear an SQL search cursor.", "inherits": { "type": { "name": "RequestBase", @@ -203555,7 +203555,7 @@ }, "path": [], "query": [], - "specLocation": "sql/clear_cursor/ClearSqlCursorRequest.ts#L22-L34" + "specLocation": "sql/clear_cursor/ClearSqlCursorRequest.ts#L22-L35" }, { "kind": "response", @@ -203589,7 +203589,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", @@ -203615,7 +203615,7 @@ } ], "query": [], - "specLocation": "sql/delete_async/SqlDeleteAsyncRequest.ts#L23-L35" + "specLocation": "sql/delete_async/SqlDeleteAsyncRequest.ts#L23-L38" }, { "kind": "response", @@ -203643,7 +203643,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", @@ -203719,7 +203719,7 @@ } } ], - "specLocation": "sql/get_async/SqlGetAsyncRequest.ts#L24-L58" + "specLocation": "sql/get_async/SqlGetAsyncRequest.ts#L24-L60" }, { "kind": "response", @@ -203820,7 +203820,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", @@ -203846,7 +203846,7 @@ } ], "query": [], - "specLocation": "sql/get_async_status/SqlGetAsyncStatusRequest.ts#L23-L35" + "specLocation": "sql/get_async_status/SqlGetAsyncStatusRequest.ts#L23-L37" }, { "kind": "response", @@ -204173,7 +204173,7 @@ } ] }, - "description": "Executes a SQL request", + "description": "Get SQL search results.\nRun an SQL request.", "inherits": { "type": { "name": "RequestBase", @@ -204201,7 +204201,7 @@ } } ], - "specLocation": "sql/query/QuerySqlRequest.ts#L28-L122" + "specLocation": "sql/query/QuerySqlRequest.ts#L28-L124" }, { "kind": "response", @@ -204323,7 +204323,7 @@ "name": "SqlFormat", "namespace": "sql.query" }, - "specLocation": "sql/query/QuerySqlRequest.ts#L124-L132" + "specLocation": "sql/query/QuerySqlRequest.ts#L126-L134" }, { "kind": "request", @@ -204389,7 +204389,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", @@ -204402,7 +204402,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