|
| 1 | +[[archive-indices]] |
| 2 | +== Reading indices from older {es} versions |
| 3 | + |
| 4 | +{es} has full query and write support for indices created in the previous major |
| 5 | +version. If you have indices created in {es} versions 5 or 6, you can now use |
| 6 | +the archive functionality to import them into newer {es} versions as well. |
| 7 | + |
| 8 | +The archive functionality provides slower read-only access to older {es} data, |
| 9 | +for compliance or regulatory reasons, the occasional lookback or investigation, |
| 10 | +or to rehydrate parts of it. Access to the data is expected to be infrequent, |
| 11 | +and can therefore happen with limited performance and query capabilities. |
| 12 | + |
| 13 | +For this, {es} has the ability to access older snapshot repositories |
| 14 | +(going back to version 5). The legacy indices in the <<snapshot-restore,snapshot repository>> |
| 15 | +can either be <<restore-snapshot-api,restored>>, or can be directly accessed |
| 16 | +via <<searchable-snapshots,searchable snapshots>> so that the archived data |
| 17 | +won't even need to fully reside on local disks for access. |
| 18 | + |
| 19 | +[discrete] |
| 20 | +[[archive-indices-supported-field-types]] |
| 21 | +=== Supported field types |
| 22 | + |
| 23 | +Old mappings are imported as much "as-is" as possible into {es} 8, but only |
| 24 | +provide regular query capabilities on a select subset of fields: |
| 25 | + |
| 26 | +- <<number,Numeric types>> |
| 27 | +- <<boolean,`boolean` type>> |
| 28 | +- <<ip,`ip` type>> |
| 29 | +- <<geo-point,`geo_point` type>> |
| 30 | +- <<date,`date` types>>: the date `format` setting on date fields is supported |
| 31 | + as long as it behaves similarly across these versions. In case it is not, |
| 32 | + for example {ref-7x}/migrate-to-java-time.html[when using custom date formats], |
| 33 | + this field can be updated on legacy indices so that it can be changed by a |
| 34 | + user if need be. |
| 35 | +- <<keyword-field-type,`keyword` type>>: the `normalizer` setting on keyword |
| 36 | + fields is supported as long as it behaves similarly across these versions. |
| 37 | + In case it is not, this field can be updated on legacy indices if need be. |
| 38 | +- <<text-field-type,`text` type>>: scoring capabilities are limited, and all |
| 39 | + queries return constant scores that are equal to 1.0. The `analyzer` |
| 40 | + settings on text fields are supported as long as they behave similarly |
| 41 | + across these versions. In case they do not, they can be updated on legacy |
| 42 | + indices if need be. |
| 43 | +- <<multi-fields,Multi-fields>> |
| 44 | +- <<field-alias,Field aliases>> |
| 45 | +- <<object,`object`>> fields |
| 46 | +- some basic metadata fields, e.g. `_type` for querying {es} 5 indices |
| 47 | +- <<runtime-mapping-fields,runtime fields>> |
| 48 | +- <<mapping-source-field,`_source` field>> |
| 49 | + |
| 50 | +{es} 5 indices with mappings that have {ref-7x}/removal-of-types.html[multiple mapping types] |
| 51 | +are collapsed together on a best-effort basis before they are imported. |
| 52 | + |
| 53 | +In case the auto-import of mappings does not work, or the new {es} version |
| 54 | +can't make sense of the mapping, it falls back to importing the index without |
| 55 | +the mapping, but stores the original mapping in the <<mapping-meta-field,_meta>> |
| 56 | +section of the imported index. The legacy mapping can then be introspected |
| 57 | +using the <<indices-get-mapping,GET mapping>> API and an updated mapping can |
| 58 | +be manually put in place using the <<indices-put-mapping,update mapping>> API, |
| 59 | +copying and adapting relevant sections of the legacy mapping to work with the |
| 60 | +current {es} version. While auto-import is expected to work in most cases, |
| 61 | +failures of doing so should be https://github.com/elastic/elasticsearch/issues/new/choose[raised] |
| 62 | +with the Elastic team for future improvements. |
| 63 | + |
| 64 | +[discrete] |
| 65 | +=== Supported APIs |
| 66 | + |
| 67 | +Archive indices are read-only, and provide data access via the |
| 68 | +<<search-search,search>> and <<search-field-caps,field capabilities>> APIs. |
| 69 | +They do not support the <<docs-get,Get API>> nor any write APIs. |
| 70 | + |
| 71 | +Archive indices allow running queries as well as aggregations in so far as |
| 72 | +they are <<archive-indices-supported-field-types,supported by the given field type>>. |
| 73 | + |
| 74 | +Due to `_source` access the data can also be <<docs-reindex,reindexed>> |
| 75 | +to a new index that has full compatibility with the current {es} version. |
| 76 | + |
| 77 | +[discrete] |
| 78 | +=== How to upgrade older {es} 5 or 6 clusters? |
| 79 | + |
| 80 | +Take a snapshot of the indices in the old cluster, delete indices that are not |
| 81 | +directly supported by ES 8 (i.e. indices older than 7.0), upgrade the cluster |
| 82 | +without the old indices, and then <<restore-snapshot-api,restore>> the legacy |
| 83 | +indices from the snapshot or <<searchable-snapshots-api-mount-snapshot,mount>> |
| 84 | +them via searchable snapshots. |
| 85 | + |
| 86 | +In the future, we plan on streamlining the upgrade process going forward, |
| 87 | +making it easier to take legacy indices along when going to future major |
| 88 | +{es} versions. |
0 commit comments