[DOCS] Extends API source code docs based on specification

Author: picandocodigo

lib/elasticsearch-serverless/api/async_search/delete.rb

@@ -22,7 +22,10 @@ module ElasticsearchServerless
   module API
     module AsyncSearch
       module Actions
-        # Deletes an async search by ID. If the search is still running, the search request will be cancelled. Otherwise, the saved search results are deleted.
+        # 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.
         #
         # @option arguments [String] :id A unique identifier for the async search. (*Required*)
         # @option arguments [Hash] :headers Custom HTTP headers

lib/elasticsearch-serverless/api/async_search/get.rb

@@ -22,7 +22,8 @@ module ElasticsearchServerless
   module API
     module AsyncSearch
       module Actions
-        # Retrieves the results of a previously submitted async search request given its ID.
+        # 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.
         #
         # @option arguments [String] :id A unique identifier for the async search. (*Required*)
         # @option arguments [Time] :keep_alive 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.

lib/elasticsearch-serverless/api/async_search/status.rb

@@ -22,7 +22,9 @@ module ElasticsearchServerless
   module API
     module AsyncSearch
       module Actions
-        # Retrieves the status of a previously submitted async search request given its ID.
+        # Get async search status
+        # Retrieves 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.
         #
         # @option arguments [String] :id A unique identifier for the async search. (*Required*)
         # @option arguments [Hash] :headers Custom HTTP headers

lib/elasticsearch-serverless/api/async_search/submit.rb

@@ -22,7 +22,11 @@ module ElasticsearchServerless
   module API
     module AsyncSearch
       module Actions
-        # Executes a search request asynchronously.
+        # 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.
         #
         # @option arguments [String, Array] :index A comma-separated list of index names to search; use +_all+ or empty string to perform the operation on all indices
         # @option arguments [Time] :wait_for_completion_timeout 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.

lib/elasticsearch-serverless/api/bulk.rb

@@ -21,7 +21,8 @@
 module ElasticsearchServerless
   module API
     module Actions
-      # Allows to perform multiple index/update/delete operations in a single request.
+      # Performs multiple indexing or delete operations in a single API call.
+      # This reduces overhead and can greatly increase indexing speed.
       #
       # @option arguments [String] :index Name of the data stream, index, or index alias to perform bulk actions on.
       # @option arguments [String] :pipeline 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.

lib/elasticsearch-serverless/api/cat/aliases.rb

@@ -22,7 +22,9 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Shows information about currently configured aliases to indices including filter and routing infos.
+        # Retrieves the cluster’s index aliases, including filter and routing information.
+        # The API does not return data stream aliases.
+        # IMPORTANT: cat APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.
         #
         # @option arguments [String, Array<String>] :name A comma-separated list of aliases to retrieve. Supports wildcards (+*+).  To retrieve all aliases, omit this parameter or use +*+ or +_all+.
         # @option arguments [String, Array<String>] :expand_wildcards Whether to expand wildcard expression to concrete indices that are open, closed or both.

lib/elasticsearch-serverless/api/cat/component_templates.rb

@@ -22,7 +22,10 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Returns information about existing component_templates templates.
+        # Returns information about component templates in a cluster.
+        # Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
+        # IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
+        # They are not intended for use by applications. For application consumption, use the get component template API.
         #
         # @option arguments [String] :name The name of the component template. Accepts wildcard expressions. If omitted, all component templates are returned.
         # @option arguments [String] :format Specifies the format to return the columnar data in, can be set to +text+, +json+, +cbor+, +yaml+, or +smile+. Server default: text.

lib/elasticsearch-serverless/api/cat/count.rb

@@ -22,7 +22,10 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Provides quick access to the document count of the entire cluster, or individual indices.
+        # Provides quick access to a document count for a data stream, an index, or an entire cluster.
+        # NOTE: The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.
+        # IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
+        # They are not intended for use by applications. For application consumption, use the count API.
         #
         # @option arguments [String, Array] :index Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (+*+). To target all data streams and indices, omit this parameter or use +*+ or +_all+.
         # @option arguments [String] :format Specifies the format to return the columnar data in, can be set to +text+, +json+, +cbor+, +yaml+, or +smile+. Server default: text.

lib/elasticsearch-serverless/api/cat/indices.rb

@@ -22,7 +22,12 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Returns information about indices: number of primaries and replicas, document counts, disk size, ...
+        # Returns high-level information about indices in a cluster, including backing indices for data streams.
+        # IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
+        # They are not intended for use by applications. For application consumption, use the get index API.
+        # Use the cat indices API to get the following information for each index in a cluster: shard count; document count; deleted document count; primary store size; total store size of all shards, including shard replicas.
+        # These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents.
+        # To get an accurate count of Elasticsearch documents, use the cat count or count APIs.
         #
         # @option arguments [String, Array] :index Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (+*+). To target all data streams and indices, omit this parameter or use +*+ or +_all+.
         # @option arguments [String] :bytes The unit used to display byte values.

lib/elasticsearch-serverless/api/cat/ml_data_frame_analytics.rb

@@ -22,7 +22,11 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Gets configuration and usage information about data frame analytics jobs.
+        # Returns configuration and usage information about data frame analytics jobs.
+        #
+        # IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+        # console or command line. They are not intended for use by applications. For
+        # application consumption, use the get data frame analytics jobs statistics API.
         #
         # @option arguments [String] :id The ID of the data frame analytics to fetch
         # @option arguments [Boolean] :allow_no_match Whether to ignore if a wildcard expression matches no configs. (This includes +_all+ string or when no configs have been specified)

lib/elasticsearch-serverless/api/cat/ml_datafeeds.rb

@@ -22,7 +22,14 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Gets configuration and usage information about datafeeds.
+        # Returns configuration and usage information about datafeeds.
+        # This API returns a maximum of 10,000 datafeeds.
+        # If the Elasticsearch security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage`
+        # cluster privileges to use this API.
+        #
+        # IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+        # console or command line. They are not intended for use by applications. For
+        # application consumption, use the get datafeed statistics API.
         #
         # @option arguments [String] :datafeed_id A numerical character string that uniquely identifies the datafeed.
         # @option arguments [Boolean] :allow_no_match Specifies what to do when the request:  * Contains wildcard expressions and there are no datafeeds that match. * Contains the +_all+ string or no identifiers and there are no matches. * Contains wildcard expressions and there are only partial matches.  If +true+, the API returns an empty datafeeds array when there are no matches and the subset of results when there are partial matches. If +false+, the API returns a 404 status code when there are no matches or only partial matches. Server default: true.

lib/elasticsearch-serverless/api/cat/ml_jobs.rb

@@ -22,7 +22,14 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Gets configuration and usage information about anomaly detection jobs.
+        # Returns configuration and usage information for anomaly detection jobs.
+        # This API returns a maximum of 10,000 jobs.
+        # If the Elasticsearch security features are enabled, you must have `monitor_ml`,
+        # `monitor`, `manage_ml`, or `manage` cluster privileges to use this API.
+        #
+        # IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+        # console or command line. They are not intended for use by applications. For
+        # application consumption, use the get anomaly detection job statistics API.
         #
         # @option arguments [String] :job_id Identifier for the anomaly detection job.
         # @option arguments [Boolean] :allow_no_match Specifies what to do when the request:  * Contains wildcard expressions and there are no jobs that match. * Contains the +_all+ string or no identifiers and there are no matches. * Contains wildcard expressions and there are only partial matches.  If +true+, the API returns an empty jobs array when there are no matches and the subset of results when there are partial matches. If +false+, the API returns a 404 status code when there are no matches or only partial matches. Server default: true.

lib/elasticsearch-serverless/api/cat/ml_trained_models.rb

@@ -22,7 +22,11 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Gets configuration and usage information about inference trained models.
+        # Returns configuration and usage information about inference trained models.
+        #
+        # IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+        # console or command line. They are not intended for use by applications. For
+        # application consumption, use the get trained models statistics API.
         #
         # @option arguments [String] :model_id A unique identifier for the trained model.
         # @option arguments [Boolean] :allow_no_match Specifies what to do when the request: contains wildcard expressions and there are no models that match; contains the +_all+ string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches. If +true+, the API returns an empty array when there are no matches and the subset of results when there are partial matches. If +false+, the API returns a 404 status code when there are no matches or only partial matches. Server default: true.

lib/elasticsearch-serverless/api/cat/transforms.rb

@@ -22,7 +22,11 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Gets configuration and usage information about transforms.
+        # Returns configuration and usage information about transforms.
+        #
+        # IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+        # console or command line. They are not intended for use by applications. For
+        # application consumption, use the get transform statistics API.
         #
         # @option arguments [String] :transform_id A transform identifier or a wildcard expression. If you do not specify one of these options, the API returns information for all transforms.
         # @option arguments [Boolean] :allow_no_match Specifies what to do when the request: contains wildcard expressions and there are no transforms that match; contains the +_all+ string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches. If +true+, it returns an empty transforms array when there are no matches and the subset of results when there are partial matches. If +false+, the request returns a 404 status code when there are no matches or only partial matches. Server default: true.

lib/elasticsearch-serverless/api/clear_scroll.rb

@@ -21,7 +21,7 @@
 module ElasticsearchServerless
   module API
     module Actions
-      # Explicitly clears the search context for a scroll.
+      # Clears the search context and results for a scrolling search.
       #
       # @option arguments [String, Array] :scroll_id Comma-separated list of scroll IDs to clear. To clear all scroll IDs, use +_all+.
       # @option arguments [Hash] :headers Custom HTTP headers

lib/elasticsearch-serverless/api/close_point_in_time.rb

@@ -21,7 +21,7 @@
 module ElasticsearchServerless
   module API
     module Actions
-      # Close a point in time
+      # Closes a point-in-time.
       #
       # @option arguments [Hash] :headers Custom HTTP headers
       # @option arguments [Hash] :body request body

lib/elasticsearch-serverless/api/cluster/delete_component_template.rb

@@ -22,7 +22,8 @@ module ElasticsearchServerless
   module API
     module Cluster
       module Actions
-        # Deletes a component template
+        # Deletes component templates.
+        # Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
         #
         # @option arguments [String, Array<String>] :name Comma-separated list or wildcard expression of component template names used to limit the request. (*Required*)
         # @option arguments [Time] :master_timeout Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Server default: 30s.

lib/elasticsearch-serverless/api/cluster/get_component_template.rb

@@ -22,7 +22,7 @@ module ElasticsearchServerless
   module API
     module Cluster
       module Actions
-        # Returns one or more component templates
+        # Retrieves information about component templates.
         #
         # @option arguments [String] :name Comma-separated list of component template names used to limit the request. Wildcard (+*+) expressions are supported.
         # @option arguments [Boolean] :flat_settings If +true+, returns settings in flat format.

lib/elasticsearch-serverless/api/cluster/put_component_template.rb

@@ -22,7 +22,21 @@ module ElasticsearchServerless
   module API
     module Cluster
       module Actions
-        # Creates or updates a component template
+        # Creates or updates a component template.
+        # Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
+        #
+        # An index template can be composed of multiple component templates.
+        # To use a component template, specify it in an index template’s `composed_of` list.
+        # Component templates are only applied to new data streams and indices as part of a matching index template.
+        #
+        # Settings and mappings specified directly in the index template or the create index request override any settings or mappings specified in a component template.
+        #
+        # Component templates are only used during index creation.
+        # For data streams, this includes data stream creation and the creation of a stream’s backing indices.
+        # Changes to component templates do not affect existing indices, including a stream’s backing indices.
+        #
+        # You can use C-style `/* *\/` block comments in component templates.
+        # You can include comments anywhere in the request body except before the opening curly bracket.
         #
         # @option arguments [String] :name Name of the component template to create. Elasticsearch includes the following built-in component templates: +logs-mappings+; 'logs-settings+; +metrics-mappings+; +metrics-settings+;+synthetics-mapping+; +synthetics-settings+. Elastic Agent uses these templates to configure backing indices for its data streams. If you use Elastic Agent and want to overwrite one of these templates, set the +version+ for your replacement template higher than the current version. If you don’t use Elastic Agent and want to disable all built-in component and index templates, set +stack.templates.enabled+ to +false+ using the cluster update settings API. (*Required*)
         # @option arguments [Boolean] :create If +true+, this request cannot replace or update existing component templates.

lib/elasticsearch-serverless/api/create.rb

@@ -21,9 +21,8 @@
 module ElasticsearchServerless
   module API
     module Actions
-      # Creates a new document in the index.
-      #
-      # Returns a 409 response when a document with a same ID already exists in the index.
+      # 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.
       #
       # @option arguments [String] :id Unique identifier for the document. (*Required*)
       # @option arguments [String] :index 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. (*Required*)