Skip to content

Commit

Permalink
[DOCS] Reformat shrink index API docs (elastic#46711) (elastic#47587)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jrodewig
jrodewig authored Oct 4, 2019
1 parent cc0502f commit 29c1424
Showing 1 changed file with 91 additions and 39 deletions.
130 changes: 91 additions & 39 deletions docs/reference/indices/shrink-index.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,40 +4,36 @@
<titleabbrev>Shrink index</titleabbrev>
++++

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 /<index>/_shrink/<target-index>`

`PUT /<index>/_shrink/<target-index>`


[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 <<cluster-health,health>> `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 <<cluster-health, cluster health>> status must be green.

[source,js]
These three conditions can be achieved with the following request:

[source,console]
--------------------------------------------------
PUT /my_source_index/_settings
{
Expand All @@ -47,7 +43,6 @@ PUT /my_source_index/_settings
}
}
--------------------------------------------------
// CONSOLE
// TEST[s/^/PUT my_source_index\n{"settings":{"index.number_of_shards":2}}\n/]
<1> Forces the relocation of a copy of each shard to the node with name
`shrink_node_name`. See <<shard-allocation-filtering>> for more options.
Expand All @@ -60,23 +55,54 @@ with the <<cat-recovery,`_cat recovery` API>>, or the <<cluster-health,
`cluster health` API>> 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.


[[_shrinking_an_index]]
===== Shrink an index

To shrink `my_source_index` into a new index called `my_target_index`, issue
the following request:

[source,js]
[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>
"index.blocks.write": null <2>
}
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

<1> Clear the allocation requirement copied from the source index.
Expand Down Expand Up @@ -110,9 +136,9 @@ Indices can only be shrunk if they satisfy the following requirements:
The `_shrink` API is similar to the <<indices-create-index, `create index` API>>
and accepts `settings` and `aliases` parameters for the target index:

[source,js]
[source,console]
--------------------------------------------------
POST my_source_index/_shrink/my_target_index
POST /my_source_index/_shrink/my_target_index
{
"settings": {
"index.number_of_replicas": 1,
Expand All @@ -124,7 +150,6 @@ POST my_source_index/_shrink/my_target_index
}
}
--------------------------------------------------
// CONSOLE
// TEST[s/^/PUT my_source_index\n{"settings": {"index.number_of_shards":5,"index.blocks.write": true}}\n/]

<1> The number of shards in the target index. This must be a factor of the
Expand All @@ -136,8 +161,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 <<cat-recovery,`_cat recovery`
API>>, or the <<cluster-health, `cluster health` API>> can be used to wait
Expand All @@ -155,9 +181,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 <<create-index-wait-for-active-shards,wait for active shards>> setting
on index creation applies to the shrink index action as well.


[[shrink-index-api-path-params]]
==== {api-path-parms-title}

`<index>`::
(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]

0 comments on commit 29c1424

Please sign in to comment.