[DOCS] Edit index operation summaries (#3268) (#3281)

(cherry picked from commit 7d436a0)

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -213,6 +213,8 @@ index-modules-slowlog-slowlog,https://www.elastic.co/guide/en/elasticsearch/refe
 index-modules,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/index-modules.html
 index,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/index.html
 indexing-buffer,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indexing-buffer.html
+index-modules-merge,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/index-modules-merge.html
+index-templates,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/index-templates.html
 indices-aliases,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-aliases.html
 indices-analyze,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-analyze.html
 indices-clearcache,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-clearcache.html
@@ -524,6 +526,7 @@ search-aggregations-metrics-top-metrics,https://www.elastic.co/guide/en/elastics
 search-aggregations-metrics-valuecount-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-metrics-valuecount-aggregation.html
 search-aggregations-metrics-weight-avg-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-metrics-weight-avg-aggregation.html
 search-aggregations-bucket-variablewidthhistogram-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-variablewidthhistogram-aggregation.html
+search-analyzer,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-analyzer.html
 search-count,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-count.html
 search-explain,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-explain.html
 search-field-caps,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-field-caps.html

output/openapi/elasticsearch-serverless-openapi.json

@@ -21,8 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { ExpandWildcards, Fields, Indices } from '@_types/common'
 
 /**
- * Clears the caches of one or more indices.
- * For data streams, the API clears the caches of the stream’s backing indices.
+ * Clear the cache.
+ * Clear the cache of one or more indices.
+ * For data streams, the API clears the caches of the stream's backing indices.
  * @rest_spec_name indices.clear_cache
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private

output/schema/schema.json

@@ -25,7 +25,30 @@ import { IndexName, Name, WaitForActiveShards } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
- * Clones an existing index.
+ * Clone an index.
+ * Clone an existing index into a new index.
+ * Each original primary shard is cloned into a new primary shard in the new index.
+ *
+ * IMPORTANT: Elasticsearch does not apply index templates to the resulting index.
+ * The API also does not copy index metadata from the original index.
+ * Index metadata includes aliases, index lifecycle management phase definitions, and cross-cluster replication (CCR) follower information.
+ * For example, if you clone a CCR follower index, the resulting clone will not be a follower index.
+ *
+ * The clone API copies most index settings from the source index to the resulting index, with the exception of `index.number_of_replicas` and `index.auto_expand_replicas`.
+ * To set the number of replicas in the resulting index, configure these settings in the clone request.
+ *
+ * Cloning works as follows:
+ *
+ * * First, it creates a new target index with the same definition as the source index.
+ * * Then it hard-links segments from the source index into the target index. If the file system does not support hard-linking, all segments are copied into the new index, which is a much more time consuming process.
+ * * Finally, it recovers the target index as though it were a closed index which had just been re-opened.
+ *
+ * IMPORTANT: Indices can only be cloned if they meet the following requirements:
+ *
+ * * The target index must not exist.
+ * * The source index must have the same number of primary shards as the target index.
+ * * The node handling the clone process must have sufficient free disk space to accommodate a second copy of the existing index.
+ *
  * @rest_spec_name indices.clone
  * @availability stack since=7.4.0 stability=stable
  */

specification/_doc_ids/table.csv

@@ -22,7 +22,24 @@ import { ExpandWildcards, Indices, WaitForActiveShards } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
- * Closes an index.
+ * Close an index.
+ * A closed index is blocked for read or write operations and does not allow all operations that opened indices allow.
+ * It is not possible to index documents or to search for documents in a closed index.
+ * Closed indices do not have to maintain internal data structures for indexing or searching documents, which results in a smaller overhead on the cluster.
+ *
+ * When opening or closing an index, the master node is responsible for restarting the index shards to reflect the new state of the index.
+ * The shards will then go through the normal recovery process.
+ * The data of opened and closed indices is automatically replicated by the cluster to ensure that enough shard copies are safely kept around at all times.
+ *
+ * You can open and close multiple indices.
+ * An error is thrown if the request explicitly refers to a missing index.
+ * This behaviour can be turned off using the `ignore_unavailable=true` parameter.
+ *
+ * By default, you must explicitly name the indices you are opening or closing.
+ * To open or close indices with `_all`, `*`, or other wildcard expressions, change the` action.destructive_requires_name` setting to `false`. This setting can also be changed with the cluster update settings API.
+ *
+ * Closed indices consume a significant amount of disk-space which can cause problems in managed environments.
+ * Closing indices can be turned off with the cluster settings API by setting `cluster.indices.close.enable` to `false`.
  * @doc_id indices-close
  * @rest_spec_name indices.close
  * @availability stack stability=stable

specification/indices/clear_cache/IndicesIndicesClearCacheRequest.ts

@@ -21,7 +21,10 @@ import { RequestBase } from '@_types/Base'
 import { ExpandWildcards, Indices } from '@_types/common'
 
 /**
- * Analyzes the disk usage of each field of an index or data stream.
+ * Analyze the index disk usage.
+ * Analyze the disk usage of each field of an index or data stream.
+ * This API might not support indices created in previous Elasticsearch versions.
+ * The result of a small index can be inaccurate as some parts of an index might not be analyzed by the API.
  * @doc_id indices-disk-usage
  * @rest_spec_name indices.disk_usage
  * @availability stack since=7.15.0 stability=experimental

specification/indices/clone/IndicesCloneRequest.ts

@@ -22,7 +22,14 @@ import { RequestBase } from '@_types/Base'
 import { IndexName } from '@_types/common'
 
 /**
- * Aggregates a time series (TSDS) index and stores pre-computed statistical summaries (`min`, `max`, `sum`, `value_count` and `avg`) for each metric field grouped by a configured time interval.
+ * Downsample an index.
+ * Aggregate a time series (TSDS) index and store pre-computed statistical summaries (`min`, `max`, `sum`, `value_count` and `avg`) for each metric field grouped by a configured time interval.
+ * For example, a TSDS index that contains metrics sampled every 10 seconds can be downsampled to an hourly index.
+ * All documents within an hour interval are summarized and stored as a single document in the downsample index.
+ *
+ * NOTE: Only indices in a time series data stream are supported.
+ * Neither field nor document level security can be defined on the source index.
+ * The source index must be read only (`index.blocks.write: true`).
  * @doc_id indices-downsample-data-stream
  * @rest_spec_name indices.downsample
  * @availability stack since=8.5.0 stability=experimental

specification/indices/close/CloseIndexRequest.ts

@@ -27,7 +27,10 @@ import {
 import { Duration } from '@_types/Time'
 
 /**
- * Returns field usage information for each shard and field of an index.
+ * Get field usage stats.
+ * Get field usage information for each shard and field of an index.
+ * Field usage statistics are automatically captured when queries are running on a cluster.
+ * A shard-level search request that accesses a given field, even if multiple times during that request, is counted as a single use.
  * @rest_spec_name indices.field_usage_stats
  * @availability stack since=7.15.0 stability=experimental
  * @availability serverless stability=experimental visibility=private