[DOCS] Descriptions for SQL APIs (#2264)

* [DOCS] Descriptions for SQL APIs

* Update specification/sql/translate/TranslateSqlRequest.ts

Co-authored-by: István Zoltán Szabó <[email protected]>

* Regenerate output

---------

Co-authored-by: István Zoltán Szabó <[email protected]>

Author: abdonpijpelink

output/schema/schema.json

@@ -25,6 +25,9 @@ import { RequestBase } from '@_types/Base'
  */
 export interface Request extends RequestBase {
   body: {
+    /**
+     * Cursor to clear.
+     */
     cursor: string
   }
 }

specification/sql/clear_cursor/ClearSqlCursorRequest.ts

@@ -26,6 +26,9 @@ import { Id } from '@_types/common'
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Identifier for the search.
+     */
     id: Id
   }
 }

specification/sql/delete_async/SqlDeleteAsyncRequest.ts

@@ -27,6 +27,9 @@ import { Id } from '@_types/common'
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Identifier for the search.
+     */
     id: Id
   }
   query_parameters: {

specification/sql/get_async/SqlGetAsyncRequest.ts

@@ -27,6 +27,9 @@ import { Id } from '@_types/common'
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Identifier for the search.
+     */
     id: Id
   }
 }

specification/sql/get_async_status/SqlGetAsyncStatusRequest.ts

@@ -32,6 +32,7 @@ import { Duration, TimeZone } from '@_types/Time'
 export interface Request extends RequestBase {
   query_parameters: {
     /**
+     * Format for the response.
      * @doc_id sql-rest-format
      */
     format?: string
@@ -46,20 +47,25 @@ export interface Request extends RequestBase {
      * @server_default false
      */
     columnar?: boolean
+    /**
+     * Cursor used to retrieve a set of paginated results.
+     * If you specify a cursor, the API only uses the `columnar` and `time_zone` request body parameters.
+     * It ignores other request body parameters.
+     */
     cursor?: string
     /**
      * The maximum number of rows (or entries) to return in one response
      * @server_default 1000
      */
     fetch_size?: integer
     /**
-     * Optional Elasticsearch query DSL for additional filtering.
+     * Elasticsearch query DSL for additional filtering.
      * @doc_id sql-rest-filtering
      * @server_default none
      */
     filter?: QueryContainer
     /**
-     * SQL query to execute
+     * SQL query to run.
      */
     query?: string
     /**
@@ -73,8 +79,9 @@ export interface Request extends RequestBase {
      */
     page_timeout?: Duration
     /**
-     * Time-zone in ISO 8601 used for executing the query on the server. More information available here.
+     * ISO-8601 time zone ID for the search.
      * @doc_url https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html
+     * @server_default Z
      */
     time_zone?: TimeZone
     /**

specification/sql/query/QuerySqlRequest.ts

@@ -28,9 +28,26 @@ import { TimeZone } from '@_types/Time'
  */
 export interface Request extends RequestBase {
   body: {
+    /**
+     * The maximum number of rows (or entries) to return in one response.
+     * @server_default 1000
+     */
     fetch_size?: integer
+    /**
+     * Elasticsearch query DSL for additional filtering.
+     * @doc_id sql-rest-filtering
+     * @server_default none
+     */
     filter?: QueryContainer
+    /**
+     * SQL query to run.
+     */
     query: string
+    /**
+     * ISO-8601 time zone ID for the search.
+     * @doc_url https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html
+     * @server_default Z
+     */
     time_zone?: TimeZone
   }
 }