Add SQL API examples

Author: lcawl

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
@@ -129,7 +128,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
@@ -477,6 +475,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

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/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
   }