Docs: Updated the upgrade API docs to explain that the reindex API should be used instead
This commit is contained in:
Clinton Gormley
parent
6b00b4b8dc
commit
637da86e5f
|
|
@ -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 <<docs-reindex,reindex API>>.
|
||||
|
||||
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
|
||||
<<indices-get-index,get-index>> 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
|
||||
<<docs-reindex,reindex API>>.
|
||||
|
||||
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
|
||||
<<alias-retrieving,get-alias API>>.
|
||||
|
||||
These ancient indices must either be deleted or upgraded before migrating to
|
||||
Elasticsearch 2.0. Upgrading will:
|
||||
4. Delete the `old_index` using the <<indices-delete-index,delete index API>>.
|
||||
|
||||
* 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 <<indices-aliases,update aliases API>>.
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue