Add more index API examples (#3430)

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -119,6 +119,9 @@ connector-update-status,https://www.elastic.co/guide/en/elasticsearch/reference/
 convert-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/convert-processor.html
 cron-expressions,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/api-conventions.html#api-cron-expressions
 csv-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/csv-processor.html
+dangling-index-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/dangling-index-delete.html
+dangling-index-import,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/dangling-index-import.html
+dangling-indices-list,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/dangling-indices-list.html
 data-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/date-processor.html
 data-stream-path-param,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-create-data-stream.html#indices-create-data-stream-api-path-params
 data-streams,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/data-streams.html
@@ -226,6 +229,7 @@ index,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/index.htm
 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
+index-templates-v1,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-templates-v1.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
@@ -234,28 +238,39 @@ indices-close,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/i
 indices-component-template,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-component-template.html
 indices-create-data-stream,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-create-data-stream.html
 indices-create-index,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-create-index.html
+indices-delete-alias,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-delete-alias.html
 indices-delete-index,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-delete-index.html
+indices-delete-template,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-delete-template.html
+indices-delete-template-v1,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-delete-template-v1.html
 indices-disk-usage,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-disk-usage.html
 indices-downsample-data-stream,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-downsample-data-stream.html
 indices-exists,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-exists.html
 indices-flush,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-flush.html
 indices-forcemerge,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-forcemerge.html
+indices-get-alias,
+https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-alias.html
 indices-get-field-mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-field-mapping.html
 indices-get-index,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-index.html
 indices-get-mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-mapping.html
 indices-get-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-settings.html
+indices-get-template,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-template.html
+indices-get-template-v1,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-get-template-v1.html
 indices-open-close,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-open-close.html
 indices-put-mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-put-mapping.html
 indices-recovery,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-recovery.html
 indices-refresh,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-refresh.html
 indices-reload-analyzers,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-reload-analyzers.html
+indices-resolve-cluster-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-resolve-cluster-api.html
 indices-resolve-index-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-resolve-index-api.html
 indices-rollover-index,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-rollover-index.html
 indices-segments,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-segments.html
 indices-shards-stores,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-shards-stores.html
 indices-shrink-index,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-shrink-index.html
+indices-simulate,https://www.elastic.co/guide/en/elasticsearch/reference/{master}/indices-simulate-index.html
+indices-simulate-template,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-simulate-template.html
 indices-split-index,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-split-index.html
 indices-stats,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-stats.html
+indices-template-exists-v1,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-template-exists-v1.html
 indices-templates,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-templates.html
 indices-update-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-update-settings.html
 infer-trained-model-deployment,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/infer-trained-model-deployment.html
@@ -281,6 +296,7 @@ logstash-logstash-settings-file,https://www.elastic.co/guide/en/logstash/{branch
 lowercase-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/lowercase-processor.html
 mapping-date-format,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-date-format.html
 mapping-meta-field,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-meta-field.html
+mapping-params,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-params.html
 mapping-metadata,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-fields.html
 mapping-roles,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-roles.html
 mapping-settings-limit,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-settings-limit.html

output/openapi/elasticsearch-serverless-openapi.json

@@ -33,7 +33,7 @@ import { QueryContainer } from '@_types/query_dsl/abstractions'
  * @rest_spec_name field_caps
  * @availability stack since=5.4.0 stability=stable
  * @availability serverless stability=stable visibility=public
- * @index_privileges view_index_metadata,read,manage
+ * @index_privileges view_index_metadata,read
  * @doc_tag search
  */
 export interface Request extends RequestBase {

output/schema/schema.json

@@ -23,7 +23,6 @@ import { Duration } from '@_types/Time'
 
 /**
  * Delete component templates.
- * Deletes component templates.
  * Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
  * @rest_spec_name cluster.delete_component_template
  * @availability stack since=7.8.0 stability=stable

specification/_doc_ids/table.csv

@@ -23,7 +23,7 @@ import { Duration } from '@_types/Time'
 
 /**
  * Get component templates.
- * Retrieves information about component templates.
+ * Get information about component templates.
  * @rest_spec_name cluster.get_component_template
  * @availability stack since=7.8.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/_global/field_caps/FieldCapabilitiesRequest.ts

@@ -24,7 +24,6 @@ import { Duration } from '@_types/Time'
 
 /**
  * Create or update 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.
@@ -39,6 +38,11 @@ import { Duration } from '@_types/Time'
  *
  * 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.
+ *
+ * **Applying component templates**
+ *
+ * You cannot directly apply a component template to a data stream or index.
+ * To be applied, a component template must be included in an index template's `composed_of` list.
  * @rest_spec_name cluster.put_component_template
  * @availability stack since=7.8.0 stability=stable
  * @availability serverless stability=stable visibility=public
@@ -81,7 +85,7 @@ export interface Request extends RequestBase {
     version?: VersionNumber
     /**
      * Optional user metadata about the component template.
-     * May have any contents. This map is not automatically generated by Elasticsearch.
+     * It may have any contents. This map is not automatically generated by Elasticsearch.
      * This information is stored in the cluster state, so keeping it short is preferable.
      * To unset `_meta`, replace the template without specifying this information.
      */

specification/cluster/delete_component_template/ClusterDeleteComponentTemplateRequest.ts

@@ -0,0 +1,17 @@
+summary: Create a template
+# method_request: PUT _component_template/template_1
+# description:
+# type: request
+value:
+  template:
+  settings:
+    number_of_shards: 1
+  mappings:
+    _source:
+      enabled: false
+    properties:
+      host_name:
+        type: keyword
+      created_at:
+        type: date
+        format: 'EEE MMM dd HH:mm:ss Z yyyy'

specification/cluster/get_component_template/ClusterGetComponentTemplateRequest.ts

@@ -0,0 +1,18 @@
+summary: Create a template with aliases
+# method_request: PUT _component_template/template_1
+description: >
+  You can include index aliases in a component template.
+  During index creation, the `{index}` placeholder in the alias name will be replaced with the actual index name that the template gets applied to.
+# type: request
+value:
+  template:
+  settings:
+    number_of_shards: 1
+  aliases:
+    alias1: {}
+    alias2:
+      filter:
+        term:
+          user.id: kimchy
+      routing: shard-1
+    '{index}-alias': {}

specification/cluster/put_component_template/ClusterPutComponentTemplateRequest.ts

@@ -23,12 +23,13 @@ import { Duration } from '@_types/Time'
 
 /**
  * Delete a dangling index.
- *
  * If Elasticsearch encounters index data that is absent from the current cluster state, those indices are considered to be dangling.
  * For example, this can happen if you delete more than `cluster.indices.tombstones.size` indices while an Elasticsearch node is offline.
  * @rest_spec_name dangling_indices.delete_dangling_index
  * @availability stack since=7.9.0 stability=stable
  * @doc_tag indices
+ * @doc_id dangling-index-delete
+ * @cluster_privileges manage
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/cluster/put_component_template/ClusterPutComponentTemplateRequestExample1.yaml

@@ -29,6 +29,8 @@ import { Duration } from '@_types/Time'
  * @rest_spec_name dangling_indices.import_dangling_index
  * @availability stack since=7.9.0 stability=stable
  * @doc_tag indices
+ * @doc_id dangling-index-import
+ * @cluster_privileges manage
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/cluster/put_component_template/ClusterPutComponentTemplateRequestExample2.yaml

@@ -0,0 +1,7 @@
+# summary: ''
+description: >
+  A successful response from `POST /_dangling/zmM4e0JtBkeUjiHD-MihPQ?accept_data_loss=true`.
+# type: response
+# response_code: 200
+value:
+  acknowledged: true

specification/dangling_indices/delete_dangling_index/DeleteDanglingIndexRequest.ts

@@ -29,5 +29,7 @@ import { RequestBase } from '@_types/Base'
  * @rest_spec_name dangling_indices.list_dangling_indices
  * @availability stack since=7.9.0 stability=stable
  * @doc_tag indices
+ * @doc_id dangling-indices-list
+ * @cluster_privileges manage
  */
 export interface Request extends RequestBase {}

specification/dangling_indices/import_dangling_index/ImportDanglingIndexRequest.ts

@@ -0,0 +1,9 @@
+# summary:
+# description: ''
+# type: response
+# response_code: 200
+value:
+  "{\n  \"dangling_indices\": [\n   {\n    \"index_name\": \"my-index-000001\"\
+  ,\n    \"index_uuid\": \"zmM4e0JtBkeUjiHD-MihPQ\",\n    \"creation_date_millis\"\
+  : 1589414451372,\n    \"node_ids\": [\n      \"pL47UN3dAb2d5RCWP6lQ3e\"\n    ]\n\
+  \   }\n  ]\n}"

specification/dangling_indices/import_dangling_index/ImportDanglingIndexResponseExample1.yaml

@@ -26,11 +26,18 @@ import { TextToAnalyze } from './types'
 
 /**
  * Get tokens from text analysis.
- * The analyze API performs [analysis](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis.html) on a text string and returns the resulting tokens.
+ * The analyze API performs analysis on a text string and returns the resulting tokens.
+ *
+ * Generating excessive amount of tokens may cause a node to run out of memory.
+ * The `index.analyze.max_token_count` setting enables you to limit the number of tokens that can be produced.
+ * If more than this limit of tokens gets generated, an error occurs.
+ * The `_analyze` endpoint without a specified index will always use `10000` as its limit.
  * @doc_id indices-analyze
+ * @ext_doc_id analysis
  * @rest_spec_name indices.analyze
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
+ * @index_privileges index
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/dangling_indices/list_dangling_indices/ListDanglingIndicesRequest.ts

@@ -1,5 +1,7 @@
-summary: Perform analysis on a text string and returns the resulting tokens.
-method_request: GET /_analyze
-# description: ''
+summary: No index specified
+# method_request: GET /_analyze
+description: You can apply any of the built-in analyzers to the text string without specifying an index.
 # type: request
-value: "{\n  \"analyzer\" : \"standard\",\n  \"text\" : \"Quick Brown Foxes!\"\n}"
+value:
+  analyzer: standard
+  text: this is a test

specification/dangling_indices/list_dangling_indices/ListDanglingIndicesResponseExample1.yaml

@@ -0,0 +1,9 @@
+summary: An array of text strings
+# method_request: GET /_analyze
+description: If the text parameter is provided as array of strings, it is analyzed as a multi-value field.
+# type: request
+value:
+  analyzer: standard
+  text:
+    - this is a test
+    - the second text

specification/indices/analyze/IndicesAnalyzeRequest.ts

@@ -0,0 +1,11 @@
+summary: Custom analyzer example 1
+# method_request: GET /_analyze
+description: You can test a custom transient analyzer built from tokenizers, token filters, and char filters. Token filters use the filter parameter.
+# type: request
+value:
+  tokenizer: keyword
+  filter:
+    - lowercase
+  char_filter:
+    - html_strip
+  text: 'this is a <b>test</b>'

specification/indices/analyze/indicesAnalyzeRequestExample1.yaml

@@ -0,0 +1,14 @@
+summary: Custom analyzer example 2
+# method_request: GET /_analyze
+description: Custom tokenizers, token filters, and character filters can be specified in the request body.
+# type: request
+value:
+  tokenizer: whitespace
+  filter:
+    - lowercase
+    - type: stop
+      stopwords:
+        - a
+        - is
+        - this
+  text: this is a test

specification/indices/analyze/indicesAnalyzeRequestExample2.yaml

@@ -0,0 +1,7 @@
+summary: Derive analyzer from field mapping
+# method_request: GET /analyze_sample/_analyze
+description: Run `GET /analyze_sample/_analyze` to run an analysis on the text using the default index analyzer associated with the `analyze_sample` index. Alternatively, the analyzer can be derived based on a field mapping.
+# type: request
+value:
+  field: obj1.field1
+  text: this is a test

specification/indices/analyze/indicesAnalyzeRequestExample3.yaml

@@ -0,0 +1,7 @@
+summary: Normalizer
+# method_request: GET /analyze_sample/_analyze
+description: Run `GET /analyze_sample/_analyze` and supply a normalizer for a keyword field if there is a normalizer associated with the specified index.
+# type: request
+value:
+  normalizer: my_normalizer
+  text: BaR

specification/indices/analyze/indicesAnalyzeRequestExample4.yaml

@@ -0,0 +1,13 @@
+summary: Explain analysis
+# method_request: GET /_analyze
+description: >
+  If you want to get more advanced details, set `explain` to `true`. It will output all token attributes for each token. You can filter token attributes you want to output by setting the `attributes` option. NOTE: The format of the additional detail information is labelled as experimental in Lucene and it may change in the future.
+# type: request
+value:
+  tokenizer: standard
+  filter:
+    - snowball
+  text: detailed output
+  explain: true
+  attributes:
+    - keyword

specification/indices/analyze/indicesAnalyzeRequestExample5.yaml

@@ -0,0 +1,36 @@
+# summary: ''
+description: A successful response for an analysis with `explain` set to `true`.
+# type: response
+# response_code: 200
+value:
+  detail:
+    custom_analyzer: true
+    charfilters: []
+    tokenizer:
+      name: standard
+      tokens:
+        - token: detailed
+          start_offset: 0
+          end_offset: 8
+          type: <ALPHANUM>
+          position: 0
+        - token: output
+          start_offset: 9
+          end_offset: 15
+          type: <ALPHANUM>
+          position: 1
+    tokenfilters:
+      - name: snowball
+        tokens:
+          - token: detail
+            start_offset: 0
+            end_offset: 8
+            type: <ALPHANUM>
+            position: 0
+            keyword: false
+          - token: output
+            start_offset: 9
+            end_offset: 15
+            type: <ALPHANUM>
+            position: 1
+            keyword: false

specification/indices/analyze/indicesAnalyzeRequestExample6.yaml

@@ -24,9 +24,14 @@ import { ExpandWildcards, Fields, Indices } from '@_types/common'
  * 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.
+ *
+ * By default, the clear cache API clears all caches.
+ * To clear only specific caches, use the `fielddata`, `query`, or `request` parameters.
+ * To clear the cache only of specific fields, use the `fields` parameter.
  * @rest_spec_name indices.clear_cache
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private
+ * @index_privileges manage
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/indices/analyze/indicesAnalyzeRequestExample7.yaml

@@ -45,12 +45,34 @@ import { Duration } from '@_types/Time'
  *
  * IMPORTANT: Indices can only be cloned if they meet the following requirements:
  *
+ * * The index must be marked as read-only and have a cluster health status of green.
  * * 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.
  *
+ * The current write index on a data stream cannot be cloned.
+ * In order to clone the current write index, the data stream must first be rolled over so that a new write index is created and then the previous write index can be cloned.
+ *
+ * NOTE: Mappings cannot be specified in the `_clone` request. The mappings of the source index will be used for the target index.
+ *
+ * **Monitor the cloning process**
+ *
+ * The cloning process can be monitored with the cat recovery API or the cluster health API can be used to wait until all primary shards have been allocated by setting the `wait_for_status` parameter to `yellow`.
+ *
+ * The `_clone` API returns as soon as the target index has been added to the cluster state, before any shards have been allocated.
+ * At this point, all shards are in the state unassigned.
+ * If, for any reason, the target index can't be allocated, its primary shard will remain unassigned until it can be allocated on that node.
+ *
+ * Once the primary shard is allocated, it moves to state initializing, and the clone process begins.
+ * When the clone operation completes, the shard will become active.
+ * At that point, Elasticsearch will try to allocate any replicas and may decide to relocate the primary shard to another node.
+ *
+ * **Wait for active shards**
+ *
+ * Because the clone operation creates a new index to clone the shards to, the wait for active shards setting on index creation applies to the clone index action as well.
  * @rest_spec_name indices.clone
  * @availability stack since=7.4.0 stability=stable
+ * @index_privileges manage
  */
 export interface Request extends RequestBase {
   path_parts: {