Generate output

lcawl · lcawl · commit aeeffa7b7b20 · 2025-01-03T19:47:08.000-08:00
diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json
diff --git a/output/schema/schema.json b/output/schema/schema.json
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
@@ -258,11 +258,13 @@ indices-put-mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{bra
 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-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
diff --git a/specification/indices/put_mapping/IndicesPutMappingRequest.ts b/specification/indices/put_mapping/IndicesPutMappingRequest.ts
@@ -40,12 +40,14 @@ import { Duration } from '@_types/Time'
 
 /**
  * Update field mappings.
- * Adds new fields to an existing data stream or index.
+ * Add new fields to an existing data stream or index.
  * You can also use this API to change the search settings of existing fields.
  * For data streams, these changes are applied to all backing indices by default.
  * @rest_spec_name indices.put_mapping
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
+ * @doc_id indices-put-mapping
+ * @index_privileges manage
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/indices/refresh/IndicesRefreshRequest.ts b/specification/indices/refresh/IndicesRefreshRequest.ts
@@ -24,9 +24,22 @@ import { ExpandWildcards, Indices } from '@_types/common'
  * Refresh an index.
  * A refresh makes recent operations performed on one or more indices available for search.
  * For data streams, the API runs the refresh operation on the stream’s backing indices.
+ *
+ * By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds.
+ * You can change this default interval with the `index.refresh_interval` setting.
+ *
+ * Refresh requests are synchronous and do not return a response until the refresh operation completes.
+ *
+ * Refreshes are resource-intensive.
+ * To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.
+ *
+ * If your application workflow indexes documents and then runs a search to retrieve the indexed document, it's recommended to use the index API's `refresh=wait_for` query parameter option.
+ * This option ensures the indexing operation waits for a periodic refresh before running the search.
  * @rest_spec_name indices.refresh
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
+ * @doc_id indices-refresh
+ * @index_privileges maintenance
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/indices/resolve_cluster/ResolveClusterRequest.ts b/specification/indices/resolve_cluster/ResolveClusterRequest.ts
@@ -38,8 +38,21 @@ import { ExpandWildcards, Names } from '@_types/common'
  * * Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).
  * * Cluster version information, including the Elasticsearch server version.
  *
+ * For example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.
+ * Each cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.
+ *
+ * **Advantages of using this endpoint before a cross-cluster search**
+ *
+ * You may want to exclude a cluster or index from a search when:
+ *
+ * * A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.
+ * * A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.
+ * * The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the "error" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)
+ * * A remote cluster is an older version that does not support the feature you want to use in your search.
  * @rest_spec_name indices.resolve_cluster
  * @availability stack since=8.13.0 stability=stable
+ * @doc_id indices-resolve-cluster-api
+ * @index_privileges view_index_metadata
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/indices/resolve_cluster/ResolveClusterResponse.ts b/specification/indices/resolve_cluster/ResolveClusterResponse.ts
@@ -35,7 +35,7 @@ export class ResolveClusterInfo {
    */
   connected: boolean
   /**
-   * The skip_unavailable setting for a remote cluster.
+   * The `skip_unavailable` setting for a remote cluster.
    */
   skip_unavailable: boolean
   /**
@@ -45,7 +45,7 @@ export class ResolveClusterInfo {
   matching_indices?: boolean
   /**
    * Provides error messages that are likely to occur if you do a search with this index expression
-   * on the specified cluster (e.g., lack of security privileges to query an index).
+   * on the specified cluster (for example, lack of security privileges to query an index).
    */
   error?: string
   /**
diff --git a/specification/indices/resolve_cluster/ResolveClusterResponseExample1.yaml b/specification/indices/resolve_cluster/ResolveClusterResponseExample1.yaml
@@ -1,5 +1,7 @@
-# summary:
-description: A successful response for resolving a specified index expression to return information about each cluster.
+summary: Resolve with wildcards
+description: >
+  A successful response from `GET /_resolve/cluster/my-index*,clust*:my-index*`.
+  Each cluster has its own response section. The cluster you sent the request to is labelled as "(local)".
 # type: response
 # response_code: 200
 value:
diff --git a/specification/indices/resolve_cluster/ResolveClusterResponseExample2.yaml b/specification/indices/resolve_cluster/ResolveClusterResponseExample2.yaml
@@ -0,0 +1,25 @@
+summary: Identify search problems
+# indices/resolve-cluster.asciidoc:213
+description: >
+  A successful response from `GET /_resolve/cluster/not-present,clust*:my-index*,oldcluster:*?ignore_unavailable=false`.
+  This type of request can be used to identify potential problems with your cross-cluster search.
+  The local cluster has no index called `not_present`. Searching with `ignore_unavailable=false` would return a "no such index" error.
+  The `cluster_one` remote cluster has no indices that match the pattern `my-index*`.
+  There may be no indices that match the pattern or the index could be closed.
+  The `cluster_two` remote cluster is not connected (the attempt to connect failed). Since this cluster is marked as `skip_unavailable=false`, you should probably exclude this cluster from the search by adding `-cluster_two:*` to the search index expression.
+  The `oldcluster` remote cluster shows that it has matching indices, but no version information is included. This indicates that the cluster version predates the introduction of the `_resolve/cluster` API, so you may want to exclude it from your cross-cluster search.
+# type: response
+# response_code: 200
+value:
+  "{\n  \"(local)\": {\n    \"connected\": true,\n    \"skip_unavailable\": false,\n\
+  \    \"error\": \"no such index [not_present]\"\n  },\n  \"cluster_one\": {\n  \
+  \  \"connected\": true,\n    \"skip_unavailable\": true,\n    \"matching_indices\"\
+  : false,\n    \"version\": {\n      \"number\": \"8.13.0\",\n      \"build_flavor\"\
+  : \"default\",\n      \"minimum_wire_compatibility_version\": \"7.17.0\",\n    \
+  \  \"minimum_index_compatibility_version\": \"7.0.0\"\n    }\n  },\n  \"cluster_two\"\
+  : {\n    \"connected\": false,\n    \"skip_unavailable\": false,\n    \"matching_indices\"\
+  : true,\n    \"version\": {\n      \"number\": \"8.13.0\",\n      \"build_flavor\"\
+  : \"default\",\n      \"minimum_wire_compatibility_version\": \"7.17.0\",\n    \
+  \  \"minimum_index_compatibility_version\": \"7.0.0\"\n    }\n  },\n  \"oldcluster\"\
+  : {\n    \"connected\": true,\n    \"skip_unavailable\": false,\n    \"matching_indices\"\
+  : true\n  }\n}"
diff --git a/specification/indices/resolve_index/ResolveIndexRequest.ts b/specification/indices/resolve_index/ResolveIndexRequest.ts
@@ -27,6 +27,8 @@ import { ExpandWildcards, Names } from '@_types/common'
  * @rest_spec_name indices.resolve_index
  * @availability stack since=7.9.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @doc_id indices-resolve-index-api
+ * @index_privileges view_index_metadata
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/indices/resolve_index/ResolveIndexResponseExample1.yaml b/specification/indices/resolve_index/ResolveIndexResponseExample1.yaml
@@ -1,5 +1,5 @@
 # summary:
-description: A successful response for resolving the specified name for an index.
+description: A successful response from `GET /_resolve/index/f*,remoteCluster1:bar*?expand_wildcards=all`.
 # type: response
 # response_code: 200
 value:
diff --git a/specification/indices/rollover/IndicesRolloverRequest.ts b/specification/indices/rollover/IndicesRolloverRequest.ts
@@ -28,11 +28,48 @@ import { RolloverConditions } from './types'
 
 /**
  * Roll over to a new index.
- * Creates a new index for a data stream or index alias.
+ * TIP: It is recommended to use the index lifecycle rollover action to automate rollovers.
+ *
+ * The rollover API creates a new index for a data stream or index alias.
+ * The API behavior depends on the rollover target.
+ *
+ * **Roll over a data stream**
+ *
+ * If you roll over a data stream, the API creates a new write index for the stream.
+ * The stream's previous write index becomes a regular backing index.
+ * A rollover also increments the data stream's generation.
+ *
+ * **Roll over an index alias with a write index**
+ *
+ * TIP: Prior to Elasticsearch 7.9, you'd typically use an index alias with a write index to manage time series data.
+ * Data streams replace this functionality, require less maintenance, and automatically integrate with data tiers.
+ *
+ * If an index alias points to multiple indices, one of the indices must be a write index.
+ * The rollover API creates a new write index for the alias with `is_write_index` set to `true`.
+ * The API also `sets is_write_index` to `false` for the previous write index.
+ *
+ * **Roll over an index alias with one index**
+ *
+ * If you roll over an index alias that points to only one index, the API creates a new index for the alias and removes the original index from the alias.
+ *
+ * NOTE: A rollover creates a new index and is subject to the `wait_for_active_shards` setting.
+ *
+ * **Increment index names for an alias**
+ *
+ * When you roll over an index alias, you can specify a name for the new index.
+ * If you don't specify a name and the current index ends with `-` and a number, such as `my-index-000001` or `my-index-3`, the new index name increments that number.
+ * For example, if you roll over an alias with a current index of `my-index-000001`, the rollover creates a new index named `my-index-000002`.
+ * This number is always six characters and zero-padded, regardless of the previous index's name.
+ *
+ * If you use an index alias for time series data, you can use date math in the index name to track the rollover date.
+ * For example, you can create an alias that points to an index named `<my-index-{now/d}-000001>`.
+ * If you create the index on May 6, 2099, the index's name is `my-index-2099.05.06-000001`.
+ * If you roll over the alias on May 7, 2099, the new index's name is `my-index-2099.05.07-000002`.
  * @doc_id indices-rollover-index
  * @rest_spec_name indices.rollover
  * @availability stack since=5.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @index_privileges manage
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/indices/simulate_index_template/IndicesSimulateIndexTemplateRequest.ts b/specification/indices/simulate_index_template/IndicesSimulateIndexTemplateRequest.ts
@@ -23,10 +23,12 @@ import { Duration } from '@_types/Time'
 
 /**
  * Simulate an index.
- * Returns the index configuration that would be applied to the specified index from an existing index template.
+ * Get the index configuration that would be applied to the specified index from an existing index template.
  * @rest_spec_name indices.simulate_index_template
  * @availability stack since=7.9.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @doc_id indices-simulate-template
+ * @cluster_privileges manage_index_templates
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/indices/split/indicesSplitRequestExample1.yaml b/specification/indices/split/indicesSplitRequestExample1.yaml
@@ -1,5 +1,5 @@
-summary: Split an existing index into a new index with more primary shards.
+# summary:
+description: Split an existing index into a new index with more primary shards.
 # method_request: POST /my-index-000001/_split/split-my-index-000001
-# description: ''
 # type: request
 value: "{\n  \"settings\": {\n    \"index.number_of_shards\": 2\n  }\n}"
diff --git a/specification/indices/unfreeze/IndicesUnfreezeRequest.ts b/specification/indices/unfreeze/IndicesUnfreezeRequest.ts
@@ -27,6 +27,7 @@ import { Duration } from '@_types/Time'
  * @rest_spec_name indices.unfreeze
  * @availability stack since=6.6.0 stability=stable
  * @index_privileges manage
+ * @doc_id unfreeze-index-api
  */
 export interface Request extends RequestBase {
   path_parts: {
