123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138 |
- [[indices-clone-index]]
- === Clone Index
- 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.
- [float]
- ==== How does cloning work?
- 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.
- [float]
- ==== Preparing an index for cloning
- Create a new index:
- [source,js]
- --------------------------------------------------
- PUT my_source_index
- {
- "settings": {
- "index.number_of_shards" : 5
- }
- }
- --------------------------------------------------
- // CONSOLE
- 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,js]
- --------------------------------------------------
- PUT /my_source_index/_settings
- {
- "settings": {
- "index.blocks.write": true <1>
- }
- }
- --------------------------------------------------
- // CONSOLE
- // TEST[continued]
- <1> Prevents write operations to this index while still allowing metadata
- changes like deleting the index.
- [float]
- ==== Cloning an index
- To clone `my_source_index` into a new index called `my_target_index`, issue
- the following request:
- [source,js]
- --------------------------------------------------
- POST my_source_index/_clone/my_target_index
- --------------------------------------------------
- // CONSOLE
- // 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 satisfy 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,js]
- --------------------------------------------------
- POST my_source_index/_clone/my_target_index
- {
- "settings": {
- "index.number_of_shards": 5 <1>
- },
- "aliases": {
- "my_search_indices": {}
- }
- }
- --------------------------------------------------
- // CONSOLE
- // 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.
- [float]
- ==== Monitoring the clone process
- The clone 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, Elasticsearch will try to allocate any
- replicas and may decide to relocate the primary shard to another node.
- [float]
- ==== 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.
|