Add descriptions for async search

specification/_types/Stats.ts

@@ -32,7 +32,13 @@ export class ClusterStatistics {
 
 export class ShardStatistics {
   failed: uint
+  /**
+   * Indicates how many shards have successfully run the search.
+   */
   successful: uint
+  /**
+   * Indicates how many shards the search will run on overall.
+   */
   total: uint
   failures?: ShardFailure[]
   skipped?: uint

specification/async_search/_types/AsyncSearch.ts

@@ -28,15 +28,26 @@ import { double, long } from '@_types/Numeric'
 import { ClusterStatistics, ShardStatistics } from '@_types/Stats'
 
 export class AsyncSearch<TDocument> {
+  /**
+   * Partial aggregations results, coming from the shards that have already completed the execution of the query.
+   */
   aggregations?: Dictionary<AggregateName, Aggregate>
   _clusters?: ClusterStatistics
   fields?: Dictionary<string, UserDefinedValue>
   hits: HitsMetadata<TDocument>
   max_score?: double
+  /**
+   * Indicates how many reductions of the results have been performed.
+   * If this number increases compared to the last retrieved results for a get asynch search request, you can expect additional results included in the search response.
+   */
   num_reduce_phases?: long
   profile?: Profile
   pit_id?: Id
   _scroll_id?: ScrollId
+  /**
+   * Indicates how many shards have run the query.
+   * Note that in order for shard results to be included in the search response, they need to be reduced first.
+   */
   _shards: ShardStatistics
   suggest?: Dictionary<SuggestionName, Suggest<TDocument>[]>
   terminated_early?: boolean

specification/async_search/_types/AsyncSearchResponseBase.ts

@@ -23,8 +23,19 @@ import { AsyncSearch } from './AsyncSearch'
 
 export class AsyncSearchResponseBase {
   id?: Id
+  /**
+   * When the query is no longer running, this property indicates whether the search failed or was successfully completed on all shards.
+   * While the query is running, `is_partial` is always set to `true`.
+   */
   is_partial: boolean
+  /**
+   * Indicates whether the search is still running or has completed.
+   * NOTE: If the search failed after some shards returned their results or the node that is coordinating the async search dies, results may be partial even though `is_running` is `false`.
+   */
   is_running: boolean
+  /**
+   * Indicates when the async search will expire.
+   */
   expiration_time?: DateTime
   expiration_time_in_millis: EpochTime<UnitMillis>
   start_time?: DateTime

specification/async_search/delete/AsyncSearchDeleteRequest.ts

@@ -21,13 +21,18 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
+ * Deletes an async search by identifier.
+ * If the search is still running, the search request will be cancelled.
+ * Otherwise, the saved search results are deleted.
+ * If the Elasticsearch security features are enabled, the deletion of a specific async search is restricted to: the authenticated user that submitted the original search request; users that have the `cancel_task` cluster privilege.
  * @rest_spec_name async_search.delete
  * @since 7.7.0
  * @stability stable
  * @doc_id async-search
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /** A unique identifier for the async search. */
     id: Id
   }
 }

specification/async_search/get/AsyncSearchGetRequest.ts

@@ -22,18 +22,33 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
+ * Retrieves the results of a previously submitted async search request given its identifier.
+ * If the Elasticsearch security features are enabled, access to the results of a specific async search is restricted to the user or API key that submitted it.
  * @rest_spec_name async_search.get
  * @since 7.7.0
  * @stability stable
  * @doc_id async-search
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /** A unique identifier for the async search. */
     id: Id
   }
   query_parameters: {
+    /**
+     * Specifies how long the async search should be available in the cluster.
+     * When not specified, the `keep_alive` set with the corresponding submit async request will be used.
+     * Otherwise, it is possible to override the value and extend the validity of the request.
+     * When this period expires, the search, if still running, is cancelled.
+     * If the search is completed, its saved results are deleted.
+     */
     keep_alive?: Duration
     typed_keys?: boolean
+    /**
+     * Specifies to wait for the search to be completed up until the provided timeout.
+     * Final results will be returned if available before the timeout expires, otherwise the currently available results will be returned once the timeout expires.
+     * By default no timeout is set meaning that the currently available results will be returned without any additional wait.
+     */
     wait_for_completion_timeout?: Duration
   }
 }

specification/async_search/status/AsyncSearchStatusRequest.ts

@@ -21,13 +21,16 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
+ * Retreives the status of a previously submitted async search request given its identifier, without retrieving search results.
+ * If the Elasticsearch security features are enabled, use of this API is restricted to the `monitoring_user` role.
  * @rest_spec_name async_search.status
  * @since 7.11.0
  * @stability stable
  * @doc_id async-search
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /** A unique identifier for the async search. */
     id: Id
   }
 }

specification/async_search/status/AsyncSearchStatusResponse.ts

@@ -22,7 +22,13 @@ import { integer } from '@_types/Numeric'
 import { ShardStatistics } from '@_types/Stats'
 
 export class StatusResponseBase extends AsyncSearchResponseBase {
+  /** Indicates how many shards have run the query so far. */
   _shards: ShardStatistics
+  /**
+   * If the async search completed, this field shows the status code of the search.
+   * For example, 200 indicates that the async search was successfully completed.
+   * 503 indicates that the async search was completed with an error.
+   */
   completion_status?: integer
 }
 export class Response {

specification/async_search/submit/AsyncSearchSubmitRequest.ts

@@ -53,6 +53,11 @@ import { KnnQuery } from '@_types/Knn'
 import { UserDefinedValue } from '@spec_utils/UserDefinedValue'
 
 /**
+ * Runs a search request asynchronously.
+ * When the primary sort of the results is an indexed field, shards get sorted based on minimum and maximum value that they hold for that field, hence partial results become available following the sort criteria that was requested.
+ * Warning: Async search does not support scroll nor search requests that only include the suggest section.
+ * By default, Elasticsearch doesn’t allow you to store an async search response larger than 10Mb and an attempt to do this results in an error.
+ * The maximum allowed size for a stored async search response can be set by changing the `search.max_async_search_response_size` cluster level setting.
  * @rest_spec_name async_search.submit
  * @since 7.7.0
  * @stability stable
@@ -64,17 +69,37 @@ export interface Request extends RequestBase {
     index?: Indices
   }
   query_parameters: {
-    /** @server_default 1s */
+    /**
+     * Blocks and waits until the search is completed up to a certain timeout.
+     * When the async search completes within the timeout, the response won’t include the ID as the results are not stored in the cluster.
+     * @server_default 1s
+     */
     wait_for_completion_timeout?: Duration
-    /** @server_default false */
+    /**
+     * If `true`, results are stored for later retrieval when the search completes within the `wait_for_completion_timeout`.
+     * @server_default false
+     */
     keep_on_completion?: boolean
-    /** @server_default 5d */
+    /**
+     * Specifies how long the async search needs to be available.
+     * Ongoing async searches and any saved search results are deleted after this period.
+     * @server_default 5d
+     */
     keep_alive?: Duration
     allow_no_indices?: boolean
     allow_partial_search_results?: boolean
     analyzer?: string
     analyze_wildcard?: boolean
+    /**
+     * Affects how often partial results become available, which happens whenever shard results are reduced.
+     * A partial reduction is performed every time the coordinating node has received a certain number of new shard responses (5 by default).
+     * @server_default 5
+     */
     batched_reduce_size?: long
+    /**
+     * The default value is the only supported value.
+     * @server_default false
+     */
     ccs_minimize_roundtrips?: boolean
     default_operator?: Operator
     df?: string
@@ -87,7 +112,12 @@ export interface Request extends RequestBase {
     max_concurrent_shard_requests?: long
     min_compatible_shard_node?: VersionString
     preference?: string
+    /**
+     * The default value cannot be changed, which enforces the execution of a pre-filter roundtrip to retrieve statistics from each shard so that the ones that surely don’t hold any document matching the query get skipped.
+     * @server_default 1
+     */
     pre_filter_shard_size?: long
+    /** @server_default true */
     request_cache?: boolean
     routing?: Routing
     scroll?: Duration