Add SQL API examples (#3479) (#3503)

Co-authored-by: Marci W <[email protected]>
(cherry picked from commit 28adc40)

Co-authored-by: Lisa Cawley <[email protected]>

specification/_doc_ids/table.csv

@@ -67,7 +67,6 @@ ccs-network-delays,https://www.elastic.co/guide/en/elasticsearch/reference/{bran
 clean-up-snapshot-repo,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html#snapshots-repository-cleanup
 clear-repositories-metering-archive-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-repositories-metering-archive-api.html
 clear-scroll-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-scroll-api.html
-clear-sql-cursor-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-sql-cursor-api.html
 cluster-allocation-explain,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-allocation-explain.html
 cluster-get-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-get-settings.html
 cluster-health,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-health.html
@@ -130,7 +129,6 @@ data-streams,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/da
 date-index-name-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/date-index-name-processor.html
 dcg,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html#_discounted_cumulative_gain_dcg
 defining-roles,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/defining-roles.html
-delete-async-sql-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-async-sql-search-api.html
 delete-enrich-policy-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-enrich-policy-api.html
 delete-license,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-license.html
 delete-pipeline-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-pipeline-api.html
@@ -188,8 +186,6 @@ geo-shape,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/geo-s
 geo-grid-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ingest-geo-grid-processor.html
 geoip-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/geoip-processor.html
 geoip-stats-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/geoip-stats-api.html
-get-async-sql-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-api.html
-get-async-sql-search-status-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-status-api.html
 get-basic-status,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-basic-status.html
 get-dfanalytics-stats,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-dfanalytics-stats.html
 get-dfanalytics,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-dfanalytics.html
@@ -478,6 +474,8 @@ reroute-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branc
 render-search-template-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/render-search-template-api.html
 reset-transform,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/reset-transform.html
 restore-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-restore-snapshot.html
+sql-delete-async-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-async-sql-search-api.html
+sql-clear-cursor-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-sql-cursor-api.html
 rollup-agg-limitations,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-agg-limitations.html
 rollup-delete-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-delete-job.html
 rollup-get-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-get-job.html
@@ -680,9 +678,13 @@ sort-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{bra
 sort-tiebreaker,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql.html#eql-search-specify-a-sort-tiebreaker
 query-dsl-sparse-vector-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-sparse-vector-query.html
 split-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/split-processor.html
+sql-async-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-api.html
+sql-async-status-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-status-api.html
+sql-rest-columnar,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-columnar.html
 sql-rest-filtering,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-filtering.html
 sql-rest-format,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-format.html
 sql-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-search-api.html
+sql-spec,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-spec.html
 sql-translate-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-translate-api.html
 start-basic,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/start-basic.html
 start-dfanalytics,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/start-dfanalytics.html
@@ -705,6 +707,7 @@ tasks,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/tasks.htm
 templating-role-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/field-and-document-access-control.html#templating-role-query
 terminate-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/terminate-processor.html
 time-value,https://github.com/elastic/elasticsearch/blob/{branch}/libs/core/src/main/java/org/elasticsearch/core/TimeValue.java
+time-zone-id,https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html
 trim-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/trim-processor.html
 unfreeze-index-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/unfreeze-index-api.html
 update-dfanalytics,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/update-dfanalytics.html

specification/sql/clear_cursor/ClearSqlCursorRequest.ts

@@ -24,6 +24,7 @@ import { RequestBase } from '@_types/Base'
  * @rest_spec_name sql.clear_cursor
  * @availability stack since=6.3.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @doc_id sql-clear-cursor-api
  */
 export interface Request extends RequestBase {
   body: {

specification/sql/clear_cursor/examples/request/ClearSqlCursorRequestExample1.yaml

@@ -0,0 +1,7 @@
+# summary:
+# method_request: POST _sql/close
+description: Run `POST _sql/close` to clear an SQL search cursor.
+# type: request
+value:
+  "{\n  \"cursor\": \"sDXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAEWYUpOYklQMHhRUEtld3RsNnFtYU1hQQ==:BAFmBGRhdGUBZgVsaWtlcwFzB21lc3NhZ2UBZgR1c2Vy9f///w8=\"\
+  \n}"

specification/sql/delete_async/SqlDeleteAsyncRequest.ts

@@ -24,14 +24,21 @@ 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.
+ *
+ * If the Elasticsearch security features are enabled, only the following users can use this API to delete a search:
+ *
+ * * Users with the `cancel_task` cluster privilege.
+ * * The user who first submitted the search.
  * @rest_spec_name sql.delete_async
  * @availability stack since=7.15.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges cancel_task
+ * @doc_id sql-delete-async-api
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * Identifier for the search.
+     * The identifier for the search.
      */
     id: Id
   }

specification/sql/get_async/SqlGetAsyncRequest.ts

@@ -24,36 +24,41 @@ 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.
+ *
+ * If the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API.
  * @rest_spec_name sql.get_async
  * @availability stack since=7.15.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @doc_id sql-async-search-api
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * Identifier for the search.
+     * The identifier for the search.
      */
     id: Id
   }
   query_parameters: {
     /**
-     * Separator for CSV results. The API only supports this parameter for CSV responses.
+     * The separator for CSV results.
+     * The API supports this parameter only for CSV responses.
      * @server_default ,
      */
     delimiter?: string
     /**
-     * Format for the response. You must specify a format using this parameter or the
-     * Accept HTTP header. If you specify both, the API uses this parameter.
+     * The format for the response.
+     * You must specify a format using this parameter or the `Accept` HTTP header.
+     * If you specify both, the API uses this parameter.
      */
     format?: string
     /**
-     * Retention period for the search and its results. Defaults
-     * to the `keep_alive` period for the original SQL search.
+     * The retention period for the search and its results.
+     * It defaults to the `keep_alive` period for the original SQL search.
      */
     keep_alive?: Duration
     /**
-     * Period to wait for complete results. Defaults to no timeout,
-     * meaning the request waits for complete search results.
+     * The period to wait for complete results.
+     * It defaults to no timeout, meaning the request waits for complete search results.
      */
     wait_for_completion_timeout?: Duration
   }

specification/sql/get_async/SqlGetAsyncResponse.ts

@@ -23,23 +23,23 @@ import { Column, Row } from '../types'
 export class Response {
   body: {
     /**
-     * Identifier for the search. This value is only returned for async and saved
-     * synchronous searches. For CSV, TSV, and TXT responses, this value is returned
-     * in the `Async-ID` HTTP header.
+     * Identifier for the search.
+     * This value is returned only for async and saved synchronous searches.
+     * For CSV, TSV, and TXT responses, this value is returned in the `Async-ID` HTTP header.
      */
     id: Id
     /**
-     * If `true`, the search is still running. If false, the search has finished.
-     * This value is only returned for async and saved synchronous searches. For
-     * CSV, TSV, and TXT responses, this value is returned in the `Async-partial`
-     * HTTP header.
+     * If `true`, the search is still running.
+     * If `false`, the search has finished.
+     * This value is returned only for async and saved synchronous searches.
+     * For CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.
      */
     is_running: boolean
     /**
-     * If `true`, the response does not contain complete search results. If `is_partial`
-     * is `true` and `is_running` is `true`, the search is still running. If `is_partial`
-     * is `true` but `is_running` is `false`, the results are partial due to a failure or
-     * timeout. This value is only returned for async and saved synchronous searches.
+     * If `true`, the response does not contain complete search results.
+     * If `is_partial` is `true` and `is_running` is `true`, the search is still running.
+     * If `is_partial` is `true` but `is_running` is `false`, the results are partial due to a failure or timeout.
+     * This value is returned only for async and saved synchronous searches.
      * For CSV, TSV, and TXT responses, this value is returned in the `Async-partial` HTTP header.
      */
     is_partial: boolean
@@ -48,12 +48,12 @@ export class Response {
      */
     columns?: Column[]
     /**
-     * Cursor for the next set of paginated results. For CSV, TSV, and
-     * TXT responses, this value is returned in the `Cursor` HTTP header.
+     * The cursor for the next set of paginated results.
+     * For CSV, TSV, and TXT responses, this value is returned in the `Cursor` HTTP header.
      */
     cursor?: string
     /**
-     * Values for the search results.
+     * The values for the search results.
      */
     rows: Row[]
   }

specification/sql/get_async_status/SqlGetAsyncStatusRequest.ts

@@ -26,11 +26,13 @@ import { Id } from '@_types/common'
  * @rest_spec_name sql.get_async_status
  * @availability stack since=7.15.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges monitor
+ * @doc_id sql-async-status-api
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * Identifier for the search.
+     * The identifier for the search.
      */
     id: Id
   }

specification/sql/get_async_status/SqlGetAsyncStatusResponse.ts

@@ -23,32 +23,32 @@ import { EpochTime, UnitMillis } from '@_types/Time'
 export class Response {
   body: {
     /**
-     * Identifier for the search.
+     * The timestamp, in milliseconds since the Unix epoch, when Elasticsearch will delete the search and its results, even if the search is still running.
+     */
+    expiration_time_in_millis: EpochTime<UnitMillis>
+    /**
+     * The identifier for the search.
      */
     id: string
     /**
-     * If `true`, the search is still running. If `false`, the search has finished.
+     * If `true`, the search is still running.
+     * If `false`, the search has finished.
      */
     is_running: boolean
     /**
-     * If `true`, the response does not contain complete search results. If `is_partial`
-     * is `true` and `is_running` is `true`, the search is still running. If `is_partial`
-     * is `true` but `is_running` is `false`, the results are partial due to a failure or
-     * timeout.
+     * If `true`, the response does not contain complete search results.
+     * If `is_partial` is `true` and `is_running` is `true`, the search is still running.
+     * If `is_partial` is `true` but `is_running` is `false`, the results are partial due to a failure or timeout.
      */
     is_partial: boolean
     /**
-     * Timestamp, in milliseconds since the Unix epoch, when the search started.
-     * The API only returns this property for running searches.
+     * The timestamp, in milliseconds since the Unix epoch, when the search started.
+     * The API returns this property only for running searches.
      */
     start_time_in_millis: EpochTime<UnitMillis>
     /**
-     * Timestamp, in milliseconds since the Unix epoch, when Elasticsearch will delete
-     * the search and its results, even if the search is still running.
-     */
-    expiration_time_in_millis: EpochTime<UnitMillis>
-    /**
-     * HTTP status code for the search. The API only returns this property for completed searches.
+     * The HTTP status code for the search.
+     * The API returns this property only for completed searches.
      */
     completion_status?: uint
   }