Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[7.3] [DOCS] Reformat shrink index API docs (#46711) #47588

Merged
merged 2 commits into from
Oct 4, 2019
Merged

[7.3] [DOCS] Reformat shrink index API docs (#46711) #47588

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0e813e8
[DOCS] Reformat shrink index API docs (#46711)
jrodewig Oct 4, 2019
cdbf079
iter
jrodewig Oct 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 89 additions & 33 deletions docs/reference/indices/shrink-index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,38 +4,35 @@
<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,js]
----
POST /twitter/_shrink/shrunk-twitter-index
----
// CONSOLE
// 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

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`.
[[shrink-index-api-prereqs]]
==== {api-prereq-title}

These two conditions can be achieved with the following request:
Before you can shrink an index:

* 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.

These three conditions can be achieved with the following request:

[source,js]
--------------------------------------------------
Expand All @@ -60,15 +57,47 @@ 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]
--------------------------------------------------
POST my_source_index/_shrink/my_target_index
POST /my_source_index/_shrink/my_target_index
{
"settings": {
"index.routing.allocation.require._name": null, <1>
Expand Down Expand Up @@ -112,7 +141,7 @@ and accepts `settings` and `aliases` parameters for the target index:

[source,js]
--------------------------------------------------
POST my_source_index/_shrink/my_target_index
POST /my_source_index/_shrink/my_target_index
{
"settings": {
"index.number_of_replicas": 1,
Expand All @@ -136,8 +165,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 +185,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]