diff --git a/docs/reference/indices/shrink-index.asciidoc b/docs/reference/indices/shrink-index.asciidoc index 21511cbc2f482..762d7bc0bf253 100644 --- a/docs/reference/indices/shrink-index.asciidoc +++ b/docs/reference/indices/shrink-index.asciidoc @@ -4,38 +4,34 @@ Shrink index ++++ -The shrink index API allows you to shrink an existing index into a new index -with fewer primary shards. The requested number of primary shards in the target index -must be a factor of the number of shards in the source index. For example an index with -`8` primary shards can be shrunk into `4`, `2` or `1` primary shards or an index -with `15` primary shards can be shrunk into `5`, `3` or `1`. If the number -of shards in the index is a prime number it can only be shrunk into a single -primary shard. Before shrinking, a (primary or replica) copy of every shard -in the index must be present on the same node. +Shrinks an existing index into a new index with fewer primary shards. -Shrinking works as follows: -* First, it creates a new target index with the same definition as the source - index, but with a smaller number of primary shards. +[source,console] +---- +POST /twitter/_shrink/shrunk-twitter-index +---- +// TEST[s/^/PUT twitter\n{"settings":{"index.number_of_shards":2,"blocks.write":true}}\n/] -* Then it hard-links segments from the source index into the target index. (If - the file system doesn't support hard-linking, then all segments are copied - into the new index, which is a much more time consuming process. Also if using - multiple data paths, shards on different data paths require a full copy of - segment files if they are not on the same disk since hardlinks don’t work across - disks) -* Finally, it recovers the target index as though it were a closed index which - had just been re-opened. +[[shrink-index-api-request]] +==== {api-request-title} + +`POST //_shrink/` + +`PUT //_shrink/` + -[float] -==== Preparing an index for shrinking +[[shrink-index-api-prereqs]] +==== {api-prereq-title} -In order to shrink an index, the index must be marked as read-only, and a -(primary or replica) copy of every shard in the index must be relocated to the -same node and have <> `green`. +Before you can shrink an index: -These two conditions can be achieved with the following request: +* The index must be read-only. +* A copy of every shard in the index must reside on the same node. +* The <> status must be green. + +These three conditions can be achieved with the following request: [source,console] -------------------------------------------------- @@ -60,15 +56,47 @@ with the <>, or the <> can be used to wait until all shards have relocated with the `wait_for_no_relocating_shards` parameter. -[float] -==== Shrinking an index + +[[shrink-index-api-desc]] +==== {api-description-title} + +The shrink index API allows you to shrink an existing index into a new index +with fewer primary shards. The requested number of primary shards in the target index +must be a factor of the number of shards in the source index. For example an index with +`8` primary shards can be shrunk into `4`, `2` or `1` primary shards or an index +with `15` primary shards can be shrunk into `5`, `3` or `1`. If the number +of shards in the index is a prime number it can only be shrunk into a single +primary shard. Before shrinking, a (primary or replica) copy of every shard +in the index must be present on the same node. + +[[how-shrink-works]] +===== How shrinking works + +A shrink operation: + +. Creates a new target index with the same definition as the source + index, but with a smaller number of primary shards. + +. Hard-links segments from the source index into the target index. (If + the file system doesn't support hard-linking, then all segments are copied + into the new index, which is a much more time consuming process. Also if using + multiple data paths, shards on different data paths require a full copy of + segment files if they are not on the same disk since hardlinks don’t work across + disks) + +. Recovers the target index as though it were a closed index which + had just been re-opened. + + +[[shrink-index]] +===== Shrink an index To shrink `my_source_index` into a new index called `my_target_index`, issue the following request: [source,console] -------------------------------------------------- -POST my_source_index/_shrink/my_target_index +POST /my_source_index/_shrink/my_target_index { "settings": { "index.routing.allocation.require._name": null, <1> @@ -111,7 +139,7 @@ and accepts `settings` and `aliases` parameters for the target index: [source,console] -------------------------------------------------- -POST my_source_index/_shrink/my_target_index +POST /my_source_index/_shrink/my_target_index { "settings": { "index.number_of_replicas": 1, @@ -134,8 +162,9 @@ POST my_source_index/_shrink/my_target_index NOTE: Mappings may not be specified in the `_shrink` request. -[float] -==== Monitoring the shrink process + +[[monitor-shrink]] +===== Monitor the shrink process The shrink process can be monitored with the <>, or the <> can be used to wait @@ -153,9 +182,35 @@ shrink process begins. When the shrink 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. -[float] -==== Wait For Active Shards + +[[shrink-wait-active-shards]] +===== Wait for active shards Because the shrink operation creates a new index to shrink the shards to, the <> setting on index creation applies to the shrink index action as well. + + +[[shrink-index-api-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +Name of the source index to shrink. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index] + +[[shrink-index-api-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + + +[[shrink-index-api-request-body]] +==== {api-request-body-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index-aliases] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index-settings]