From 637da86e5f1ed6abb12639a9b3350d330c71898a Mon Sep 17 00:00:00 2001 From: Clinton Gormley Date: Thu, 31 Mar 2016 14:34:31 +0200 Subject: [PATCH] Docs: Updated the upgrade API docs to explain that the reindex API should be used instead --- docs/reference/indices/upgrade.asciidoc | 71 +++++++++++-------------- 1 file changed, 30 insertions(+), 41 deletions(-) diff --git a/docs/reference/indices/upgrade.asciidoc b/docs/reference/indices/upgrade.asciidoc index c9d371bd8ca..1b8e99f2125 100644 --- a/docs/reference/indices/upgrade.asciidoc +++ b/docs/reference/indices/upgrade.asciidoc @@ -5,60 +5,49 @@ The upgrade API allows to upgrade one or more indices to the latest Lucene format through an API. The upgrade process converts any segments written with older formats. -.When to use the `upgrade` API -************************************************** +[IMPORTANT] +=================================================== -Newer versions of Lucene often come with a new index format which provides bug -fixes and performance improvements. In order to take advantage of these -improvements, the segments in each shard need to be rewritten using the latest -Lucene format. +**The upgrade API in its current form will not help you to migrate indices +created in Elasticsearch 1.x to 5.x.** -.Automatic upgrading +The upgrade API rewrites an index in the latest Lucene format, but it still +retains the original data structures that were used when the index was first +created. For instance: -Indices that are actively being written to will automatically write new -segments in the latest format. The background merge process which combines -multiple small segments into a single bigger segment will also write the new -merged segment in the latest format. +* Doc-values on numeric fields used to use BinaryDocValues, but now use dedicated NumericDocValues. +* The parent-child feature has been completely rewritten to use a new data structure. +* Geo-point fields now require doc values and the Lucene index where, previously, they relied on in-memory calculations. -.Optional manual upgrades +**Migrating 1.x indices to 5.x** -Some old segments may never be merged away because they are already too big to -be worth merging, and indices that no longer receive changes will not be -upgraded automatically. Upgrading segments is not required for most -Elasticsearch upgrades because it can read older formats from the current and -previous major version of Lucene. +The only way to prepare an index created in 1.x for use in 5.x is to **reindex +your data** in a cluster running Elasticsearch 2.3.x, which you can do with +the new <>. -You can, however, choose to upgrade old segments manually to take advantage of -the latest format. The `upgrade` API will rewrite any old segments in the -latest Lucene format. It can be run on one index, multiple or all indices, so -you can control when it is run and how many indices it should upgrade. +The steps to do this are as follows: -.When you must use the `upgrade` API +1. Create a new index (e.g. `new_index`) with the correct settings and + mappings. These can be retrieved from the old index with the + <> API. -Elasticsearch can only read formats from the current and previous major -version of Lucene. For instance, Elasticsearch 2.x (Lucene 5) can read disk -formats from Elasticsearch 0.90 and 1.x (Lucene 4), but not from Elasticsearch -0.20 and before (Lucene 3). +2. Reindex from `old_index` to `new_index` with the + <>. -In fact, an Elasticsearch 2.0 cluster will refuse to start if any indices -created before Elasticsearch 0.90 are present, and it will refuse to open them -if they are imported as dangling indices later on. It will not be possible to -restore an index created with Elasticsearch 0.20.x and before into a 2.0 -cluster. +3. Retrieve a list of any aliases associated with the `old_index` using the + <>. -These ancient indices must either be deleted or upgraded before migrating to -Elasticsearch 2.0. Upgrading will: +4. Delete the `old_index` using the <>. -* Rewrite old segments in the latest Lucene format. -* Add the `index.version.minimum_compatible` setting to the index, to mark it as - 2.0 compatible +5. Add an alias called `old_index` to the `new_index` along with any aliases + returned in step 3, using the <>. -Instead of upgrading all segments that weren't written with the most recent -version of Lucene, you can choose to do the minimum work required before -moving to Elasticsearch 2.0, by specifying the `only_ancient_segments` option, -which will only rewrite segments written by Lucene 3. +In the future, we plan to change the upgrade API to perform a reindex-in- +place. In other words, it would reindex data from `old_index` to `.old_index` +then atomically delete `old_index` and rename `.old_index` to `old_index`. + +=================================================== -************************************************** [float] === Start an upgrade