From 9a8a0c457f712d220dc81cf0c2d38cdee9d573f2 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 5 Dec 2024 12:06:00 -0800 Subject: [PATCH] [DOCS] Add SQL operation summaries (#3221) (#3230) (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 314555fec3..8140e4ce7f 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -32147,7 +32147,7 @@ "tags": [ "sql" ], - "summary": "Clears the SQL cursor", + "summary": "Clear an SQL search cursor", "operationId": "sql-clear-cursor", "requestBody": { "content": { @@ -32196,8 +32196,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": [ { @@ -32232,7 +32232,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": [ { @@ -32344,7 +32345,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": [ { @@ -32409,7 +32411,8 @@ "tags": [ "sql" ], - "summary": "Executes a SQL request", + "summary": "Get SQL search results", + "description": "Run an SQL request.", "operationId": "sql-query-1", "parameters": [ { @@ -32430,7 +32433,8 @@ "tags": [ "sql" ], - "summary": "Executes a SQL request", + "summary": "Get SQL search results", + "description": "Run an SQL request.", "operationId": "sql-query", "parameters": [ { @@ -32453,7 +32457,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" @@ -32469,7 +32474,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 b12af8b18a..8bb3a3f81a 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -17486,7 +17486,7 @@ "tags": [ "sql" ], - "summary": "Clears the SQL cursor", + "summary": "Clear an SQL search cursor", "operationId": "sql-clear-cursor", "requestBody": { "content": { @@ -17535,8 +17535,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": [ { @@ -17571,7 +17571,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": [ { @@ -17683,7 +17684,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": [ { @@ -17748,7 +17750,8 @@ "tags": [ "sql" ], - "summary": "Executes a SQL request", + "summary": "Get SQL search results", + "description": "Run an SQL request.", "operationId": "sql-query-1", "parameters": [ { @@ -17769,7 +17772,8 @@ "tags": [ "sql" ], - "summary": "Executes a SQL request", + "summary": "Get SQL search results", + "description": "Run an SQL request.", "operationId": "sql-query", "parameters": [ { @@ -17792,7 +17796,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" @@ -17808,7 +17813,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 78d82a1bb5..124c57f4f7 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -18489,7 +18489,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": { @@ -18527,7 +18527,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": { @@ -18562,7 +18562,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": { @@ -18597,7 +18597,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": { @@ -18632,7 +18632,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": { @@ -18671,7 +18671,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": { @@ -203544,7 +203544,7 @@ } ] }, - "description": "Clears the SQL cursor", + "description": "Clear an SQL search cursor.", "inherits": { "type": { "name": "RequestBase", @@ -203557,7 +203557,7 @@ }, "path": [], "query": [], - "specLocation": "sql/clear_cursor/ClearSqlCursorRequest.ts#L22-L34" + "specLocation": "sql/clear_cursor/ClearSqlCursorRequest.ts#L22-L35" }, { "kind": "response", @@ -203591,7 +203591,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", @@ -203617,7 +203617,7 @@ } ], "query": [], - "specLocation": "sql/delete_async/SqlDeleteAsyncRequest.ts#L23-L35" + "specLocation": "sql/delete_async/SqlDeleteAsyncRequest.ts#L23-L38" }, { "kind": "response", @@ -203645,7 +203645,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", @@ -203721,7 +203721,7 @@ } } ], - "specLocation": "sql/get_async/SqlGetAsyncRequest.ts#L24-L58" + "specLocation": "sql/get_async/SqlGetAsyncRequest.ts#L24-L60" }, { "kind": "response", @@ -203822,7 +203822,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", @@ -203848,7 +203848,7 @@ } ], "query": [], - "specLocation": "sql/get_async_status/SqlGetAsyncStatusRequest.ts#L23-L35" + "specLocation": "sql/get_async_status/SqlGetAsyncStatusRequest.ts#L23-L37" }, { "kind": "response", @@ -204175,7 +204175,7 @@ } ] }, - "description": "Executes a SQL request", + "description": "Get SQL search results.\nRun an SQL request.", "inherits": { "type": { "name": "RequestBase", @@ -204203,7 +204203,7 @@ } } ], - "specLocation": "sql/query/QuerySqlRequest.ts#L28-L122" + "specLocation": "sql/query/QuerySqlRequest.ts#L28-L124" }, { "kind": "response", @@ -204325,7 +204325,7 @@ "name": "SqlFormat", "namespace": "sql.query" }, - "specLocation": "sql/query/QuerySqlRequest.ts#L124-L132" + "specLocation": "sql/query/QuerySqlRequest.ts#L126-L134" }, { "kind": "request", @@ -204391,7 +204391,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", @@ -204404,7 +204404,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