|
|
@@ -4,6 +4,276 @@
|
|
|
This section discusses the changes that you need to be aware of when migrating
|
|
|
your application to Elasticsearch 2.0.
|
|
|
|
|
|
+[float]
|
|
|
+=== Indices created before 0.90
|
|
|
+
|
|
|
+Elasticsearch 2.0 can read indices created in version 0.90 and above. If any
|
|
|
+of your indices were created before 0.90 you will need to upgrade to the
|
|
|
+latest 1.x version of Elasticsearch first, in order to upgrade your indices or
|
|
|
+to delete the old indices. Elasticsearch will not start in the presence of old
|
|
|
+indices.
|
|
|
+
|
|
|
+[float]
|
|
|
+=== Elasticsearch migration plugin
|
|
|
+
|
|
|
+We have provided the https://github.com/elastic/elasticsearch-migration[Elasticsearch migration plugin]
|
|
|
+to help you detect any issues that you may have when upgrading to
|
|
|
+Elasticsearch 2.0. Please install and run the plugin *before* upgrading.
|
|
|
+
|
|
|
+=== Mapping
|
|
|
+
|
|
|
+
|
|
|
+Remove file based default mappings #10870 (issue: #10620)
|
|
|
+Validate dynamic mappings updates on the master node. #10634 (issues: #8650, #8688)
|
|
|
+Remove the ability to have custom per-field postings and doc values formats. #9741 (issue: #8746)
|
|
|
+Remove support for new indexes using path setting in object/nested fields or index_name in any field #9570 (issue: #6677)
|
|
|
+Remove index_analyzer setting to simplify analyzer logic #9451 (issue: #9371)
|
|
|
+Remove type level default analyzers #9430 (issues: #8874, #9365)
|
|
|
+Add doc values support to boolean fields. #7961 (issues: #4678, #7851)
|
|
|
+
|
|
|
+
|
|
|
+A number of changes have been made to mappings to remove ambiguity and to
|
|
|
+ensure that conflicting mappings cannot be created.
|
|
|
+
|
|
|
+==== Conflicting field mappings
|
|
|
+
|
|
|
+Fields with the same name, in the same index, in different types, must have
|
|
|
+the same mapping, with the exception of the <<copy-to>>, <<dynamic>>,
|
|
|
+<<enabled>>, <<ignore-above>>, <<include-in-all>>, and <<properties>>
|
|
|
+parameters, which may have different settings per field.
|
|
|
+
|
|
|
+[source,js]
|
|
|
+---------------
|
|
|
+PUT my_index
|
|
|
+{
|
|
|
+ "mappings": {
|
|
|
+ "type_one": {
|
|
|
+ "properties": {
|
|
|
+ "name": { <1>
|
|
|
+ "type": "string"
|
|
|
+ }
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "type_two": {
|
|
|
+ "properties": {
|
|
|
+ "name": { <1>
|
|
|
+ "type": "string",
|
|
|
+ "analyzer": "english"
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+---------------
|
|
|
+<1> The two `name` fields have conflicting mappings and will prevent Elasticsearch
|
|
|
+ from starting.
|
|
|
+
|
|
|
+Elasticsearch will not start in the presence of conflicting field mappings.
|
|
|
+These indices must be deleted or reindexed using a new mapping.
|
|
|
+
|
|
|
+The `ignore_conflicts` option of the put mappings API has been removed.
|
|
|
+Conflicts can't be ignored anymore.
|
|
|
+
|
|
|
+==== Fields cannot be referenced by short name
|
|
|
+
|
|
|
+A field can no longer be referenced using its short name. Instead, the full
|
|
|
+path to the field is required. For instance:
|
|
|
+
|
|
|
+[source,js]
|
|
|
+---------------
|
|
|
+PUT my_index
|
|
|
+{
|
|
|
+ "mappings": {
|
|
|
+ "my_type": {
|
|
|
+ "properties": {
|
|
|
+ "title": { "type": "string" }, <1>
|
|
|
+ "name": {
|
|
|
+ "properties": {
|
|
|
+ "title": { "type": "string" }, <2>
|
|
|
+ "first": { "type": "string" },
|
|
|
+ "last": { "type": "string" }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+---------------
|
|
|
+<1> This field is referred to as `title`.
|
|
|
+<2> This field is referred to as `name.title`.
|
|
|
+
|
|
|
+Previously, the two `title` fields in the example above could have been
|
|
|
+confused with each other when using the short name `title`.
|
|
|
+
|
|
|
+=== Type name prefix removed
|
|
|
+
|
|
|
+Previously, two fields with the same name in two different types could
|
|
|
+sometimes be disambiguated by prepending the type name. As a side effect, it
|
|
|
+would add a filter on the type name to the relevant query. This feature was
|
|
|
+ambiguous -- a type name could be confused with a field name -- and didn't
|
|
|
+work everywhere e.g. aggregations.
|
|
|
+
|
|
|
+Instead, fields should be specified with the full path, but without a type
|
|
|
+name prefix. If you wish to filter by the `_type` field, either specify the
|
|
|
+type in the URL or add an explicit filter.
|
|
|
+
|
|
|
+The following example query in 1.x:
|
|
|
+
|
|
|
+[source,js]
|
|
|
+----------------------------
|
|
|
+GET my_index/_search
|
|
|
+{
|
|
|
+ "query": {
|
|
|
+ "match": {
|
|
|
+ "my_type.some_field": "quick brown fox"
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+----------------------------
|
|
|
+
|
|
|
+would be rewritten in 2.0 as:
|
|
|
+
|
|
|
+[source,js]
|
|
|
+----------------------------
|
|
|
+GET my_index/my_type/_search <1>
|
|
|
+{
|
|
|
+ "query": {
|
|
|
+ "match": {
|
|
|
+ "some_field": "quick brown fox" <2>
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+----------------------------
|
|
|
+<1> The type name can be specified in the URL to act as a filter.
|
|
|
+<2> The field name should be specified without the type prefix.
|
|
|
+
|
|
|
+==== Field names may not contain dots
|
|
|
+
|
|
|
+In 1.x, it was possible to create fields with dots in their name, for
|
|
|
+instance:
|
|
|
+
|
|
|
+[source,js]
|
|
|
+----------------------------
|
|
|
+PUT my_index
|
|
|
+{
|
|
|
+ "mappings": {
|
|
|
+ "my_type": {
|
|
|
+ "properties": {
|
|
|
+ "foo.bar": { <1>
|
|
|
+ "type": "string"
|
|
|
+ },
|
|
|
+ "foo": {
|
|
|
+ "properties": {
|
|
|
+ "bar": { <1>
|
|
|
+ "type": "string"
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+----------------------------
|
|
|
+<1> These two fields cannot be distinguised as both are referred to as `foo.bar`.
|
|
|
+
|
|
|
+You can no longer create fields with dots in the name.
|
|
|
+
|
|
|
+==== Type names may not start with a dot
|
|
|
+
|
|
|
+In 1.x, Elasticsearch would issue a warning if a type name included a dot,
|
|
|
+e.g. `my.type`. Now that type names are no longer used to distinguish between
|
|
|
+fields in differnt types, this warning has been relaxed: type names may now
|
|
|
+contain dots, but they may not *begin* with a dot. The only exception to this
|
|
|
+is the special `.percolator` type.
|
|
|
+
|
|
|
+==== Types may no longer be deleted
|
|
|
+
|
|
|
+In 1.x it was possible to delete a type mapping, along with all of the
|
|
|
+documents of that type, using the delete mapping API. This is no longer
|
|
|
+supported, because remnants of the fields in the type could remain in the
|
|
|
+index, causing corruption later on.
|
|
|
+
|
|
|
+==== Type meta-fields
|
|
|
+
|
|
|
+The <<mapping-fields,meta-fields>> associated with had configuration options
|
|
|
+removed, to make them more reliable:
|
|
|
+
|
|
|
+* `_id` configuration can no longer be changed. If you need to sort, use the <<mapping-uid-field,`_uid`>> field instead.
|
|
|
+* `_type` configuration can no longer be changed.
|
|
|
+* `_index` configuration can no longer be changed.
|
|
|
+* `_routing` configuration is limited to marking routing as required.
|
|
|
+* `_field_names` configuration is limited to disabling the field.
|
|
|
+* `_size` configuration is limited to enabling the field.
|
|
|
+* `_timestamp` configuration is limited to enabling the field, setting format and default value.
|
|
|
+* `_boost` has been removed.
|
|
|
+* `_analyzer` has been removed.
|
|
|
+
|
|
|
+Importantly, *meta-fields can no longer be specified as part of the document
|
|
|
+body.* Instead, they must be specified in the query string parameters. For
|
|
|
+instance, in 1.x, the `routing` could be specified as follows:
|
|
|
+
|
|
|
+[source,json]
|
|
|
+-----------------------------
|
|
|
+PUT my_index
|
|
|
+{
|
|
|
+ "mappings": {
|
|
|
+ "my_type": {
|
|
|
+ "_routing": {
|
|
|
+ "path": "group" <1>
|
|
|
+ },
|
|
|
+ "properties": {
|
|
|
+ "group": { <1>
|
|
|
+ "type": "string"
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+PUT my_index/my_type/1 <2>
|
|
|
+{
|
|
|
+ "group": "foo"
|
|
|
+}
|
|
|
+-----------------------------
|
|
|
+<1> This 1.x mapping tells Elasticsearch to extract the `routing` value from the `group` field in the document body.
|
|
|
+<2> This indexing request uses a `routing` value of `foo`.
|
|
|
+
|
|
|
+In 2.0, the routing must be specified explicitly:
|
|
|
+
|
|
|
+[source,json]
|
|
|
+-----------------------------
|
|
|
+PUT my_index
|
|
|
+{
|
|
|
+ "mappings": {
|
|
|
+ "my_type": {
|
|
|
+ "_routing": {
|
|
|
+ "required": true <1>
|
|
|
+ },
|
|
|
+ "properties": {
|
|
|
+ "group": {
|
|
|
+ "type": "string"
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+PUT my_index/my_type/1?routing=bar <2>
|
|
|
+{
|
|
|
+ "group": "foo"
|
|
|
+}
|
|
|
+-----------------------------
|
|
|
+<1> Routing can be marked as required to ensure it is not forgotten during indexing.
|
|
|
+<2> This indexing request uses a `routing` value of `bar`.
|
|
|
+
|
|
|
+==== Other mapping changes
|
|
|
+
|
|
|
+* The setting `index.mapping.allow_type_wrapper` has been removed. Documents should always be sent without the type as the root element.
|
|
|
+* The `binary` field does not support the `compress` and `compress_threshold` options anymore.
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
=== Networking
|
|
|
|
|
|
Elasticsearch now binds to the loopback interface by default (usually 127.0.0.1
|
|
|
@@ -188,141 +458,6 @@ Delete api requires a routing value when deleting a document belonging to a type
|
|
|
mapping, whereas previous elasticsearch versions would trigger a broadcast delete on all shards belonging to the index.
|
|
|
A `RoutingMissingException` is now thrown instead.
|
|
|
|
|
|
-=== Mappings
|
|
|
-
|
|
|
-* The setting `index.mapping.allow_type_wrapper` has been removed. Documents should always be sent without the type as the root element.
|
|
|
-* The delete mappings API has been removed. Mapping types can no longer be deleted.
|
|
|
-* Mapping type names can no longer start with dots.
|
|
|
-* The `ignore_conflicts` option of the put mappings API has been removed. Conflicts can't be ignored anymore.
|
|
|
-* The `binary` field does not support the `compress` and `compress_threshold` options anymore.
|
|
|
-
|
|
|
-==== Removed type prefix on field names in queries
|
|
|
-Types can no longer be specified on fields within queries. Instead, specify type restrictions in the search request.
|
|
|
-
|
|
|
-The following is an example query in 1.x over types `t1` and `t2`:
|
|
|
-
|
|
|
-[source,js]
|
|
|
----------------
|
|
|
-curl -XGET 'localhost:9200/index/_search'
|
|
|
-{
|
|
|
- "query": {
|
|
|
- "bool": {
|
|
|
- "should": [
|
|
|
- {"match": { "t1.field_only_in_t1": "foo" }},
|
|
|
- {"match": { "t2.field_only_in_t2": "bar" }}
|
|
|
- ]
|
|
|
- }
|
|
|
- }
|
|
|
-}
|
|
|
----------------
|
|
|
-
|
|
|
-In 2.0, the query should look like the following:
|
|
|
-
|
|
|
-[source,js]
|
|
|
----------------
|
|
|
-curl -XGET 'localhost:9200/index/t1,t2/_search'
|
|
|
-{
|
|
|
- "query": {
|
|
|
- "bool": {
|
|
|
- "should": [
|
|
|
- {"match": { "field_only_in_t1": "foo" }},
|
|
|
- {"match": { "field_only_in_t2": "bar" }}
|
|
|
- ]
|
|
|
- }
|
|
|
- }
|
|
|
-}
|
|
|
----------------
|
|
|
-
|
|
|
-==== Removed short name field access
|
|
|
-Field names in queries, aggregations, etc. must now use the complete name. Use of the short name
|
|
|
-caused ambiguities in field lookups when the same name existed within multiple object mappings.
|
|
|
-
|
|
|
-The following example illustrates the difference between 1.x and 2.0.
|
|
|
-
|
|
|
-Given these mappings:
|
|
|
-
|
|
|
-[source,js]
|
|
|
----------------
|
|
|
-curl -XPUT 'localhost:9200/index'
|
|
|
-{
|
|
|
- "mappings": {
|
|
|
- "type": {
|
|
|
- "properties": {
|
|
|
- "name": {
|
|
|
- "type": "object",
|
|
|
- "properties": {
|
|
|
- "first": {"type": "string"},
|
|
|
- "last": {"type": "string"}
|
|
|
- }
|
|
|
- }
|
|
|
- }
|
|
|
- }
|
|
|
- }
|
|
|
-}
|
|
|
----------------
|
|
|
-
|
|
|
-The following query was possible in 1.x:
|
|
|
-
|
|
|
-[source,js]
|
|
|
----------------
|
|
|
-curl -XGET 'localhost:9200/index/type/_search'
|
|
|
-{
|
|
|
- "query": {
|
|
|
- "match": { "first": "foo" }
|
|
|
- }
|
|
|
-}
|
|
|
----------------
|
|
|
-
|
|
|
-In 2.0, the same query should now be:
|
|
|
-
|
|
|
-[source,js]
|
|
|
----------------
|
|
|
-curl -XGET 'localhost:9200/index/type/_search'
|
|
|
-{
|
|
|
- "query": {
|
|
|
- "match": { "name.first": "foo" }
|
|
|
- }
|
|
|
-}
|
|
|
----------------
|
|
|
-
|
|
|
-==== Removed support for `.` in field name mappings
|
|
|
-Prior to Elasticsearch 2.0, a field could be defined to have a `.` in its name.
|
|
|
-Mappings like the one below have been deprecated for some time and they will be
|
|
|
-blocked in Elasticsearch 2.0.
|
|
|
-
|
|
|
-[source,js]
|
|
|
----------------
|
|
|
-curl -XPUT 'localhost:9200/index'
|
|
|
-{
|
|
|
- "mappings": {
|
|
|
- "type": {
|
|
|
- "properties": {
|
|
|
- "name.first": {
|
|
|
- "type": "string"
|
|
|
- }
|
|
|
- }
|
|
|
- }
|
|
|
- }
|
|
|
-}
|
|
|
----------------
|
|
|
-
|
|
|
-==== Meta fields have limited configuration
|
|
|
-Meta fields (those beginning with underscore) are fields used by elasticsearch
|
|
|
-to provide special features. They now have limited configuration options.
|
|
|
-
|
|
|
-* `_id` configuration can no longer be changed. If you need to sort, use `_uid` instead.
|
|
|
-* `_type` configuration can no longer be changed.
|
|
|
-* `_index` configuration can no longer be changed.
|
|
|
-* `_routing` configuration is limited to requiring the field.
|
|
|
-* `_boost` has been removed.
|
|
|
-* `_field_names` configuration is limited to disabling the field.
|
|
|
-* `_size` configuration is limited to enabling the field.
|
|
|
-* `_timestamp` configuration is limited to enabling the field, setting format and default value
|
|
|
-
|
|
|
-==== Meta fields in documents
|
|
|
-Meta fields can no longer be specified within a document. They should be specified
|
|
|
-via the API. For example, instead of adding a field `_parent` within a document,
|
|
|
-use the `parent` url parameter when indexing that document.
|
|
|
|
|
|
==== Default date format now is `strictDateOptionalTime`
|
|
|
|
|
|
@@ -389,10 +524,6 @@ the user-friendly representation of boolean fields: `false`/`true`:
|
|
|
Fields of type `murmur3` can no longer change `doc_values` or `index` setting.
|
|
|
They are always stored with doc values, and not indexed.
|
|
|
|
|
|
-==== Source field configuration
|
|
|
-The `_source` field no longer supports `includes` and `excludes` parameters. When
|
|
|
-`_source` is enabled, the entire original source will be stored.
|
|
|
-
|
|
|
==== Config based mappings
|
|
|
The ability to specify mappings in configuration files has been removed. To specify
|
|
|
default mappings that apply to multiple indexes, use index templates.
|
|
|
@@ -437,10 +568,10 @@ script.indexed: on
|
|
|
|
|
|
=== Script parameters
|
|
|
|
|
|
-Deprecated script parameters `id`, `file`, `scriptField`, `script_id`, `script_file`,
|
|
|
+Deprecated script parameters `id`, `file`, `scriptField`, `script_id`, `script_file`,
|
|
|
`script`, `lang` and `params`. The <<modules-scripting,new script API syntax>> should be used in their place.
|
|
|
|
|
|
-The deprecated script parameters have been removed from the Java API so applications using the Java API will
|
|
|
+The deprecated script parameters have been removed from the Java API so applications using the Java API will
|
|
|
need to be updated.
|
|
|
|
|
|
=== Groovy scripts sandbox
|
Clinton Gormley