Merge branch 'main' into issue-2275-frequent-items

specification/_global/bulk/BulkRequest.ts

@@ -30,6 +30,8 @@ import { OperationContainer, UpdateAction } from './types'
 import { SourceConfigParam } from '@global/search/_types/SourceFilter'
 
 /**
+ * Performs multiple indexing or delete operations in a single API call.
+ * This reduces overhead and can greatly increase indexing speed.
  * @rest_spec_name bulk
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
@@ -38,23 +40,62 @@ import { SourceConfigParam } from '@global/search/_types/SourceFilter'
  */
 export interface Request<TDocument, TPartialDocument> extends RequestBase {
   path_parts: {
+    /**
+     * Name of the data stream, index, or index alias to perform bulk actions on.
+     */
     index?: IndexName
   }
   query_parameters: {
+    /**
+     * ID of the pipeline to use to preprocess incoming documents.
+     * If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.
+     * If a final pipeline is configured it will always run, regardless of the value of this parameter.
+     */
     pipeline?: string
+    /**
+     * If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.
+     * Valid values: `true`, `false`, `wait_for`.
+     * @server_default false
+     */
     refresh?: Refresh
+    /**
+     * Custom value used to route operations to a specific shard.
+     */
     routing?: Routing
+    /**
+     * `true` or `false` to return the `_source` field or not, or a list of fields to return.
+     */
     _source?: SourceConfigParam
+    /**
+     * A comma-separated list of source fields to exclude from the response.
+     */
     _source_excludes?: Fields
+    /**
+     * A comma-separated list of source fields to include in the response.
+     */
     _source_includes?: Fields
+    /**
+     * Period each action waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.
+     * @server_default 1m
+     */
     timeout?: Duration
+    /**
+     * The number of shard copies that must be active before proceeding with the operation.
+     * Set to all or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).
+     * @server_default 1
+     */
     wait_for_active_shards?: WaitForActiveShards
+    /**
+     * If `true`, the request’s actions must target an index alias.
+     * @server_default false
+     */
     require_alias?: boolean
   }
-  /** @codegen_name operations */
+  /**
+   * The request body contains a newline-delimited list of `create`, `delete`, `index`, and `update` actions and their associated source data.
+   * @codegen_name operations */
   // This declaration captures action_and_meta_data (OperationContainer) and the two kinds of sources
   // that can follow: an update action for update operations and anything for index or create operations.
-  //
   // /!\ must be kept in sync with BulkMonitoringRequest
   body?: Array<
     OperationContainer | UpdateAction<TDocument, TPartialDocument> | TDocument

specification/_global/bulk/types.ts

@@ -35,14 +35,46 @@ import { Script } from '@_types/Scripting'
 import { SourceConfig } from '@global/search/_types/SourceFilter'
 
 export class ResponseItem {
+  /**
+   * The document ID associated with the operation.
+   */
   _id?: string | null
+  /**
+   * Name of the index associated with the operation.
+   * If the operation targeted a data stream, this is the backing index into which the document was written.
+   */
   _index: string
+  /**
+   * HTTP status code returned for the operation.
+   */
   status: integer
+  /**
+   * Contains additional information about the failed operation.
+   * The parameter is only returned for failed operations.
+   */
   error?: ErrorCause
+  /**
+   * The primary term assigned to the document for the operation.
+   */
   _primary_term?: long
+  /**
+   * Result of the operation.
+   * Successful values are `created`, `deleted`, and `updated`.
+   */
   result?: string
+  /**
+   * The sequence number assigned to the document for the operation.
+   * Sequence numbers are used to ensure an older version of a document doesn’t overwrite a newer version.
+   */
   _seq_no?: SequenceNumber
+  /**
+   * Contains shard information for the operation.
+   */
   _shards?: ShardStatistics
+  /**
+   * The document version associated with the operation.
+   * The document version is incremented each time the document is updated.
+   */
   _version?: VersionNumber
   forced_refresh?: boolean
   get?: InlineGet<Dictionary<string, UserDefinedValue>>
@@ -56,8 +88,17 @@ export enum OperationType {
 }
 
 export class OperationBase {
+  /**
+   * The document ID.
+   */
   _id?: Id
+  /**
+   * Name of the index or index alias to perform the action on.
+   */
   _index?: IndexName
+  /**
+   * Custom value used to route operations to a specific shard.
+   */
   routing?: Routing
   if_primary_term?: long
   if_seq_no?: SequenceNumber
@@ -66,8 +107,23 @@ export class OperationBase {
 }
 
 export class WriteOperation extends OperationBase {
+  /**
+   * A map from the full name of fields to the name of dynamic templates.
+   * Defaults to an empty map.
+   * If a name matches a dynamic template, then that template will be applied regardless of other match predicates defined in the template.
+   * If a field is already defined in the mapping, then this parameter won’t be used.
+   */
   dynamic_templates?: Dictionary<string, string>
+  /**
+   * ID of the pipeline to use to preprocess incoming documents.
+   * If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.
+   * If a final pipeline is configured it will always run, regardless of the value of this parameter.
+   */
   pipeline?: string
+  /**
+   * If `true`, the request’s actions must target an index alias.
+   * @server_default false
+   */
   require_alias?: boolean
 }
 
@@ -78,15 +134,35 @@ export class IndexOperation extends WriteOperation {}
 export class DeleteOperation extends OperationBase {}
 
 export class UpdateOperation extends OperationBase {
+  /**
+   * If `true`, the request’s actions must target an index alias.
+   * @server_default false
+   */
   require_alias?: boolean
   retry_on_conflict?: integer
 }
 
 /** @variants container */
 export class OperationContainer {
+  /**
+   * Indexes the specified document.
+   * If the document exists, replaces the document and increments the version.
+   * The following line must contain the source data to be indexed.
+   */
   index?: IndexOperation
+  /**
+   * Indexes the specified document if it does not already exist.
+   * The following line must contain the source data to be indexed.
+   */
   create?: CreateOperation
+  /**
+   * Performs a partial document update.
+   * The following line must contain the partial document and update options.
+   */
   update?: UpdateOperation
+  /**
+   * Removes the specified document from the index.
+   */
   delete?: DeleteOperation
 }
 

specification/_global/clear_scroll/ClearScrollRequest.ts

@@ -21,16 +21,25 @@ import { RequestBase } from '@_types/Base'
 import { Ids, ScrollIds } from '@_types/common'
 
 /**
+ * Clears the search context and results for a scrolling search.
  * @rest_spec_name clear_scroll
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @doc_id clear-scroll-api
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Comma-separated list of scroll IDs to clear.
+     * To clear all scroll IDs, use `_all`.
+     */
     scroll_id?: ScrollIds
   }
   body: {
+    /**
+     * Scroll IDs to clear.
+     * To clear all scroll IDs, use `_all`.
+     */
     scroll_id?: ScrollIds
   }
 }

specification/_global/close_point_in_time/ClosePointInTimeRequest.ts

@@ -21,13 +21,17 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
+ * Closes a point-in-time.
  * @rest_spec_name close_point_in_time
  * @availability stack since=7.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @doc_id point-in-time-api
  */
 export interface Request extends RequestBase {
   body: {
+    /**
+     * The ID of the point-in-time.
+     */
     id: Id
   }
 }

specification/_global/create/CreateRequest.ts

@@ -30,25 +30,66 @@ import {
 import { Duration } from '@_types/Time'
 
 /**
+ * Adds a JSON document to the specified data stream or index and makes it searchable.
+ * If the target is an index and the document already exists, the request updates the document and increments its version.
  * @rest_spec_name create
  * @availability stack since=5.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  *
  */
 export interface Request<TDocument> extends RequestBase {
   path_parts: {
+    /**
+     * Unique identifier for the document.
+     */
     id: Id
+    /**
+     * Name of the data stream or index to target.
+     * If the target doesn’t exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream.
+     * If the target doesn’t exist and doesn’t match a data stream template, this request creates the index.
+     */
     index: IndexName
   }
   query_parameters: {
+    /**
+     * ID of the pipeline to use to preprocess incoming documents.
+     * If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.
+     * If a final pipeline is configured it will always run, regardless of the value of this parameter.
+     */
     pipeline?: string
+    /**
+     * If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.
+     * Valid values: `true`, `false`, `wait_for`.
+     * @server_default false
+     */
     refresh?: Refresh
+    /**
+     * Custom value used to route operations to a specific shard.
+     */
     routing?: Routing
+    /**
+     * Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.
+     * @server_default 1m
+     */
     timeout?: Duration
+    /**
+     * Explicit version number for concurrency control.
+     * The specified version must match the current version of the document for the request to succeed.
+     */
     version?: VersionNumber
+    /**
+     * Specific version type: `external`, `external_gte`.
+     */
     version_type?: VersionType
+    /**
+     * The number of shard copies that must be active before proceeding with the operation.
+     * Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).
+     * @server_default 1
+     */
     wait_for_active_shards?: WaitForActiveShards
   }
-  /** @codegen_name document */
+  /**
+   * Request body contains the JSON source for the document data.
+   * @codegen_name document */
   body?: TDocument
 }

specification/_global/delete/DeleteRequest.ts

@@ -32,23 +32,60 @@ import { long } from '@_types/Numeric'
 import { Duration } from '@_types/Time'
 
 /**
+ * Removes a JSON document from the specified index.
  * @rest_spec_name delete
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Unique identifier for the document.
+     */
     id: Id
+    /**
+     * Name of the target index.
+     */
     index: IndexName
   }
   query_parameters: {
+    /**
+     * Only perform the operation if the document has this primary term.
+     */
     if_primary_term?: long
+    /**
+     * Only perform the operation if the document has this sequence number.
+     */
     if_seq_no?: SequenceNumber
+    /**
+     * If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.
+     * Valid values: `true`, `false`, `wait_for`.
+     * @server_default false
+     */
     refresh?: Refresh
+    /**
+     * Custom value used to route operations to a specific shard.
+     */
     routing?: Routing
+    /**
+     * Period to wait for active shards.
+     * @server_default 1m
+     */
     timeout?: Duration
+    /**
+     * Explicit version number for concurrency control.
+     * The specified version must match the current version of the document for the request to succeed.
+     */
     version?: VersionNumber
+    /**
+     * Specific version type: `external`, `external_gte`.
+     */
     version_type?: VersionType
+    /**
+     * The number of shard copies that must be active before proceeding with the operation.
+     * Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).
+     * @server_default 1
+     */
     wait_for_active_shards?: WaitForActiveShards
   }
 }