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.x] [DOCS] Reformat split index API docs (#46713) #47578

Merged
merged 1 commit into from
Oct 4, 2019
Merged

[7.x] [DOCS] Reformat split index API docs (#46713) #47578

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
148 changes: 98 additions & 50 deletions docs/reference/indices/split-index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,58 @@
<titleabbrev>Split index</titleabbrev>
++++

Splits an existing index into a new index with more primary shards.

[source,console]
----
POST /twitter/_split/split-twitter-index
{
"settings": {
"index.number_of_shards": 2
}
}
----
// TEST[s/^/PUT twitter\n{"settings":{"blocks.write":true}}\n/]


[[split-index-api-request]]
==== {api-request-title}

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

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


[[split-index-api-prereqs]]
==== {api-prereq-title}


Before you can split an index:

* The index must be read-only.
* The <<cluster-health, cluster health>> status must be green.

You can do make an index read-only
with the following request:

[source,console]
--------------------------------------------------
PUT /my_source_index/_settings
{
"settings": {
"index.blocks.write": true <1>
}
}
--------------------------------------------------
// TEST[s/^/PUT my_source_index\n/]

<1> Prevents write operations to this index while still allowing metadata
changes like deleting the index.


[[split-index-api-desc]]
==== {api-description-title}

The split index API allows you to split an existing index into a new index,
where each original primary shard is split into two or more primary shards in
the new index.
Expand Down Expand Up @@ -34,27 +86,28 @@ index may by split into an arbitrary number of shards greater than 1. The
properties of the default number of routing shards will then apply to the
newly split index.

[float]
==== How does splitting work?

Splitting works as follows:
[[how-split-works]]
===== How splitting works

* First, it creates a new target index with the same definition as the source
A split operation:

. Creates a new target index with the same definition as the source
index, but with a larger number of primary shards.

* Then it hard-links segments from the source index into the target index. (If
. 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.)

* Once the low level files are created all documents will be `hashed` again to delete
. Hashes all documents again, after low level files are created, to delete
documents that belong to a different shard.

* Finally, it recovers the target index as though it were a closed index which
. Recovers the target index as though it were a closed index which
had just been re-opened.

[float]

[[incremental-resharding]]
==== Why doesn't Elasticsearch support incremental resharding?
===== Why doesn't Elasticsearch support incremental resharding?

Going from `N` shards to `N+1` shards, aka. incremental resharding, is indeed a
feature that is supported by many key-value stores. Adding a new shard and
Expand Down Expand Up @@ -83,49 +136,16 @@ covers both the old and the new index for read operations. Assuming that the
old and new indices have respectively +M+ and +N+ shards, this has no overhead
compared to searching an index that would have +M+N+ shards.

[float]
==== Preparing an index for splitting

Create a new index:

[source,console]
--------------------------------------------------
PUT my_source_index
{
"settings": {
"index.number_of_shards" : 1
}
}
--------------------------------------------------

In order to split an index, the index must be marked as read-only,
and have <<cluster-health,health>> `green`.

This can be achieved with the following request:

[source,console]
--------------------------------------------------
PUT /my_source_index/_settings
{
"settings": {
"index.blocks.write": true <1>
}
}
--------------------------------------------------
// TEST[continued]

<1> Prevents write operations to this index while still allowing metadata
changes like deleting the index.

[float]
==== Splitting an index
[[split-index]]
===== Split an index

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

[source,console]
--------------------------------------------------
POST my_source_index/_split/my_target_index
POST /my_source_index/_split/my_target_index
{
"settings": {
"index.number_of_shards": 2
Expand Down Expand Up @@ -159,7 +179,7 @@ and accepts `settings` and `aliases` parameters for the target index:

[source,console]
--------------------------------------------------
POST my_source_index/_split/my_target_index
POST /my_source_index/_split/my_target_index
{
"settings": {
"index.number_of_shards": 5 <1>
Expand All @@ -177,8 +197,9 @@ POST my_source_index/_split/my_target_index

NOTE: Mappings may not be specified in the `_split` request.

[float]
==== Monitoring the split process

[[monitor-split]]
==== Monitor the split process

The split 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 @@ -196,9 +217,36 @@ split process begins. When the split 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

[[split-wait-active-shards]]
==== Wait for active shards

Because the split operation creates a new index to split the shards to,
the <<create-index-wait-for-active-shards,wait for active shards>> setting
on index creation applies to the split index action as well.


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

`<index>`::
(Required, string)
Name of the source index to split.

include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index]


[[split-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]


[[split-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]