[DOCS] Reformat clone index API docs (#46762)
This commit is contained in:
James Rodewig
parent
365aa30b7f
commit
9ddc99de23
|
|
@ -1,12 +1,60 @@
|
|||
[[indices-clone-index]]
|
||||
=== Clone Index
|
||||
=== Clone index API
|
||||
++++
|
||||
<titleabbrev>Clone index</titleabbrev>
|
||||
++++
|
||||
|
||||
The clone index API allows you to clone an existing index into a new index,
|
||||
where each original primary shard is cloned into a new primary shard in
|
||||
the new index.
|
||||
Clones an existing index.
|
||||
|
||||
[float]
|
||||
==== How does cloning work?
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
POST /twitter/_clone/cloned-twitter-index
|
||||
--------------------------------------------------
|
||||
// TEST[s/^/PUT twitter\n{"settings":{"index.number_of_shards" : 5,"blocks.write":true}}\n/]
|
||||
|
||||
|
||||
[[clone-index-api-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /<index>/_clone/<target-index>`
|
||||
|
||||
`PUT /<index>/_clone/<target-index>`
|
||||
|
||||
|
||||
[[clone-index-api-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
To clone an index,
|
||||
the index must be marked as read-only
|
||||
and have a <<cluster-health,cluster health>> status of `green`.
|
||||
|
||||
For example,
|
||||
the following request prevents write operations on `my_source_index`
|
||||
so it can be cloned.
|
||||
Metadata changes like deleting the index are still allowed.
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
PUT /my_source_index/_settings
|
||||
{
|
||||
"settings": {
|
||||
"index.blocks.write": true
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TEST[s/^/PUT my_source_index\n/]
|
||||
|
||||
|
||||
[[clone-index-api-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
Use the clone index API
|
||||
to clone an existing index into a new index,
|
||||
where each original primary shard is cloned
|
||||
into a new primary shard in the new index.
|
||||
|
||||
[[cloning-works]]
|
||||
===== How cloning works
|
||||
|
||||
Cloning works as follows:
|
||||
|
||||
|
|
@ -20,49 +68,15 @@ Cloning works as follows:
|
|||
* Finally, it recovers the target index as though it were a closed index which
|
||||
had just been re-opened.
|
||||
|
||||
[float]
|
||||
==== Preparing an index for cloning
|
||||
|
||||
Create a new index:
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
PUT my_source_index
|
||||
{
|
||||
"settings": {
|
||||
"index.number_of_shards" : 5
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
In order to clone 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]
|
||||
==== Cloning an index
|
||||
[[clone-index]]
|
||||
===== Clone an index
|
||||
|
||||
To clone `my_source_index` into a new index called `my_target_index`, issue
|
||||
the following request:
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
POST my_source_index/_clone/my_target_index
|
||||
POST /my_source_index/_clone/my_target_index
|
||||
--------------------------------------------------
|
||||
// TEST[continued]
|
||||
|
||||
|
|
@ -72,9 +86,9 @@ the cluster state -- it doesn't wait for the clone operation to start.
|
|||
[IMPORTANT]
|
||||
=====================================
|
||||
|
||||
Indices can only be cloned if they satisfy the following requirements:
|
||||
Indices can only be cloned if they meet the following requirements:
|
||||
|
||||
* the target index must not exist
|
||||
* The target index must not exist.
|
||||
|
||||
* The source index must have the same number of primary shards as the target index.
|
||||
|
||||
|
|
@ -88,7 +102,7 @@ and accepts `settings` and `aliases` parameters for the target index:
|
|||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
POST my_source_index/_clone/my_target_index
|
||||
POST /my_source_index/_clone/my_target_index
|
||||
{
|
||||
"settings": {
|
||||
"index.number_of_shards": 5 <1>
|
||||
|
|
@ -107,10 +121,10 @@ POST my_source_index/_clone/my_target_index
|
|||
NOTE: Mappings may not be specified in the `_clone` request. The mappings of
|
||||
the source index will be used for the target index.
|
||||
|
||||
[float]
|
||||
==== Monitoring the clone process
|
||||
[[monitor-cloning]]
|
||||
===== Monitor the cloning process
|
||||
|
||||
The clone process can be monitored with the <<cat-recovery,`_cat recovery`
|
||||
The cloning process can be monitored with the <<cat-recovery,`_cat recovery`
|
||||
API>>, or the <<cluster-health, `cluster health` API>> can be used to wait
|
||||
until all primary shards have been allocated by setting the `wait_for_status`
|
||||
parameter to `yellow`.
|
||||
|
|
@ -123,12 +137,38 @@ can be allocated on that node.
|
|||
|
||||
Once the primary shard is allocated, it moves to state `initializing`, and the
|
||||
clone process begins. When the clone operation completes, the shard will
|
||||
become `active`. At that point, Elasticsearch will try to allocate any
|
||||
become `active`. At that point, {es} will try to allocate any
|
||||
replicas and may decide to relocate the primary shard to another node.
|
||||
|
||||
[float]
|
||||
==== Wait For Active Shards
|
||||
[[clone-wait-active-shards]]
|
||||
===== Wait for active shards
|
||||
|
||||
Because the clone operation creates a new index to clone the shards to,
|
||||
the <<create-index-wait-for-active-shards,wait for active shards>> setting
|
||||
on index creation applies to the clone index action as well.
|
||||
|
||||
|
||||
[[clone-index-api-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`<index>`::
|
||||
(Required, string)
|
||||
Name of the source index to clone.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index]
|
||||
|
||||
|
||||
[[clone-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]
|
||||
|
||||
|
||||
[[clone-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]
|
||||
|
|
|
|||
|
|
@ -18,6 +18,13 @@ If specified,
|
|||
the index alias only applies to documents returned by the filter.
|
||||
end::index-alias-filter[]
|
||||
|
||||
tag::target-index-aliases[]
|
||||
`aliases`::
|
||||
(Optional, <<indices-aliases,alias object>>)
|
||||
Index aliases which include the target index.
|
||||
See <<indices-aliases>>.
|
||||
end::target-index-aliases[]
|
||||
|
||||
tag::allow-no-indices[]
|
||||
`allow_no_indices`::
|
||||
(Optional, boolean) If `true`,
|
||||
|
|
@ -489,15 +496,22 @@ the segment has most likely been written to disk
|
|||
but needs a <<indices-refresh,refresh>> to be searchable.
|
||||
end::segment-search[]
|
||||
|
||||
tag::segment-size[]
|
||||
Disk space used by the segment, such as `50kb`.
|
||||
end::segment-size[]
|
||||
|
||||
tag::settings[]
|
||||
`settings`::
|
||||
(Optional, <<index-modules-settings,index setting object>>) Configuration
|
||||
options for the index. See <<index-modules-settings>>.
|
||||
end::settings[]
|
||||
|
||||
tag::segment-size[]
|
||||
Disk space used by the segment, such as `50kb`.
|
||||
end::segment-size[]
|
||||
tag::target-index-settings[]
|
||||
`settings`::
|
||||
(Optional, <<index-modules-settings,index setting object>>)
|
||||
Configuration options for the target index.
|
||||
See <<index-modules-settings>>.
|
||||
end::target-index-settings[]
|
||||
|
||||
tag::slices[]
|
||||
`slices`::
|
||||
|
|
@ -534,6 +548,17 @@ tag::stats[]
|
|||
purposes.
|
||||
end::stats[]
|
||||
|
||||
tag::target-index[]
|
||||
`<target-index>`::
|
||||
+
|
||||
--
|
||||
(Required, string)
|
||||
Name of the target index to create.
|
||||
|
||||
include::{docdir}/indices/create-index.asciidoc[tag=index-name-reqs]
|
||||
--
|
||||
end::target-index[]
|
||||
|
||||
tag::terminate_after[]
|
||||
`terminate_after`::
|
||||
(Optional, integer) The maximum number of documents to collect for each shard,
|
||||
|
|
|
|||
Loading…
Reference in New Issue