179 lines
5.4 KiB
Plaintext
179 lines
5.4 KiB
Plaintext
[[indices-clone-index]]
|
|
=== Clone index API
|
|
++++
|
|
<titleabbrev>Clone index</titleabbrev>
|
|
++++
|
|
|
|
Clones an existing index.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /my-index-000001/_clone/cloned-my-index-000001
|
|
--------------------------------------------------
|
|
// TEST[s/^/PUT my-index-000001\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/]
|
|
|
|
The current write index on a data stream cannot be cloned. In order to clone
|
|
the current write index, the data stream must first be
|
|
<<rollover-data-stream-ex,rolled over>> so that a new write index is created
|
|
and then the previous write index can be cloned.
|
|
|
|
[[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:
|
|
|
|
* First, it creates a new target index with the same definition as the source
|
|
index.
|
|
|
|
* 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.)
|
|
|
|
* Finally, it recovers the target index as though it were a closed index which
|
|
had just been re-opened.
|
|
|
|
[[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
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
The above request returns immediately once the target index has been added to
|
|
the cluster state -- it doesn't wait for the clone operation to start.
|
|
|
|
[IMPORTANT]
|
|
=====================================
|
|
|
|
Indices can only be cloned if they meet the following requirements:
|
|
|
|
* The target index must not exist.
|
|
|
|
* The source index must have the same number of primary shards as the target index.
|
|
|
|
* The node handling the clone process must have sufficient free disk space to
|
|
accommodate a second copy of the existing index.
|
|
|
|
=====================================
|
|
|
|
The `_clone` API is similar to the <<indices-create-index, `create index` API>>
|
|
and accepts `settings` and `aliases` parameters for the target index:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /my_source_index/_clone/my_target_index
|
|
{
|
|
"settings": {
|
|
"index.number_of_shards": 5 <1>
|
|
},
|
|
"aliases": {
|
|
"my_search_indices": {}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[s/^/PUT my_source_index\n{"settings": {"index.blocks.write": true, "index.number_of_shards": "5"}}\n/]
|
|
|
|
<1> The number of shards in the target index. This must be equal to the
|
|
number of shards in the source index.
|
|
|
|
|
|
NOTE: Mappings may not be specified in the `_clone` request. The mappings of
|
|
the source index will be used for the target index.
|
|
|
|
[[monitor-cloning]]
|
|
===== Monitor the cloning process
|
|
|
|
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`.
|
|
|
|
The `_clone` API returns as soon as the target index has been added to the
|
|
cluster state, before any shards have been allocated. At this point, all
|
|
shards are in the state `unassigned`. If, for any reason, the target index
|
|
can't be allocated, its primary shard will remain `unassigned` until it
|
|
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, {es} will try to allocate any
|
|
replicas and may decide to relocate the primary shard to another node.
|
|
|
|
[[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::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=target-index]
|
|
|
|
|
|
[[clone-index-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
|
|
|
|
|
[[clone-index-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=target-index-aliases]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=target-index-settings]
|