377 lines
12 KiB
Plaintext
377 lines
12 KiB
Plaintext
[[breaking-changes]]
|
|
= Breaking changes in 1.0
|
|
|
|
[partintro]
|
|
--
|
|
This section discusses the changes that you need to be aware of when migrating
|
|
your application to Elasticsearch 1.0.
|
|
--
|
|
|
|
== System and settings
|
|
|
|
* Elasticsearch now runs in the foreground by default. There is no more `-f`
|
|
flag on the command line. Instead, to run elasticsearch as a daemon, use
|
|
the `-d` flag:
|
|
|
|
[source,sh]
|
|
---------------
|
|
./bin/elasticsearch -d
|
|
---------------
|
|
|
|
* Command line settings can now be passed without the `-Des.` prefix, for
|
|
instance:
|
|
|
|
[source,sh]
|
|
---------------
|
|
./bin/elasticsearch --node.name=search_1 --cluster.name=production
|
|
---------------
|
|
|
|
* Elasticsearch on 64 bit Linux now uses <<mmapfs,`mmapfs`>> by default. Make
|
|
sure that you set <<setup-service,`MAX_MAP_COUNT`>> to a sufficiently high
|
|
number. The RPM and Debian packages default this value to `262144`.
|
|
|
|
* The RPM and Debian packages no longer start Elasticsearch by default.
|
|
|
|
* The `cluster.routing.allocation` settings (`disable_allocation`,
|
|
`disable_new_allocation` and `disable_replica_location`) have been
|
|
<<modules-cluster,replaced by the single setting>>:
|
|
+
|
|
[source,yaml]
|
|
---------------
|
|
cluster.routing.allocation.enable: all|primaries|new_primaries|none
|
|
---------------
|
|
|
|
== Stats and Info APIs
|
|
|
|
The <<cluster-state,`cluster_state`>>, <<cluster-nodes-info,`nodes_info`>>,
|
|
<<cluster-nodes-stats,`nodes_stats`>> and <<indices-stats,`indices_stats`>>
|
|
APIs have all been changed to make their format more RESTful and less clumsy.
|
|
|
|
For instance, if you just want the `nodes` section of the the `cluster_state`,
|
|
instead of:
|
|
|
|
[source,sh]
|
|
---------------
|
|
GET /_cluster/state?filter_metadata&filter_routing_table&filter_blocks
|
|
---------------
|
|
|
|
you now use:
|
|
|
|
[source,sh]
|
|
---------------
|
|
GET /_cluster/state/nodes
|
|
---------------
|
|
|
|
Simliarly for the `nodes_stats` API, if you want the `transport` and `http`
|
|
metrics only, instead of:
|
|
|
|
[source,sh]
|
|
---------------
|
|
GET /_nodes/stats?clear&transport&http
|
|
---------------
|
|
|
|
you now use:
|
|
|
|
[source,sh]
|
|
---------------
|
|
GET /_nodes/stats/transport,http
|
|
---------------
|
|
|
|
See the links above for full details.
|
|
|
|
|
|
== Indices APIs
|
|
|
|
The `mapping`, `alias`, `settings`, and `warmer` index APIs are all similar
|
|
but there are subtle differences in the order of the URL and the response
|
|
body. For instance, adding a mapping and a warmer look slightly different:
|
|
|
|
[source,sh]
|
|
---------------
|
|
PUT /{index}/{type}/_mapping
|
|
PUT /{index}/_warmer/{name}
|
|
---------------
|
|
|
|
These URLs have been unified as:
|
|
|
|
[source,sh]
|
|
---------------
|
|
PUT /{indices}/_mapping/{type}
|
|
PUT /{indices}/_alias/{name}
|
|
PUT /{indices}/_warmer/{name}
|
|
|
|
GET /{indices}/_mapping/{types}
|
|
GET /{indices}/_alias/{names}
|
|
GET /{indices}/_settings/{names}
|
|
GET /{indices}/_warmer/{names}
|
|
|
|
DELETE /{indices}/_mapping/{types}
|
|
DELETE /{indices}/_alias/{names}
|
|
DELETE /{indices}/_warmer/{names}
|
|
---------------
|
|
|
|
All of the `{indices}`, `{types}` and `{names}` parameters can be replaced by:
|
|
|
|
* `_all`, `*` or blank (ie left out altogether), all of which mean ``all''
|
|
* wildcards like `test*`
|
|
* comma-separated lists: `index_1,test_*`
|
|
|
|
The only exception is `DELETE` which doesn't accept blank (missing)
|
|
parameters. If you want to delete something, you should be specific.
|
|
|
|
Similarly, the return values for `GET` have been unified with the following
|
|
rules:
|
|
|
|
* Only return values that exist. If you try to `GET` a mapping which doesn't
|
|
exist, then the result will be an empty object: `{}`. We no longer throw a
|
|
`404` if the requested mapping/warmer/alias/setting doesn't exist.
|
|
|
|
* The response format always has the index name, then the section, then the
|
|
element name, for instance:
|
|
+
|
|
[source,json]
|
|
---------------
|
|
{
|
|
"my_index": {
|
|
"mappings": {
|
|
"my_type": {...}
|
|
}
|
|
}
|
|
}
|
|
---------------
|
|
+
|
|
This is a breaking change for the `get_mapping` API.
|
|
|
|
In the future we will also provide plural versions to allow putting multiple mappings etc in a single request.
|
|
|
|
See <<indices-put-mapping,`put-mapping`>>, <<indices-get-mapping,`get-
|
|
mapping`>>, <<indices-get-field-mapping,`get-field-mapping`>>,
|
|
<<indices-delete-mapping,`delete-mapping`>>,
|
|
<<indices-update-settings,`update-settings`>>, <<indices-get-settings,`get-settings`>>,
|
|
<<indices-warmers,`warmers`>>, and <<indices-aliases,`aliases`>> for more details.
|
|
|
|
== Index request
|
|
|
|
Previously a document could be indexed as itself, or wrapped in an outer
|
|
object which specified the `type` name:
|
|
|
|
[source,json]
|
|
---------------
|
|
PUT /my_index/my_type/1
|
|
{
|
|
"my_type": {
|
|
... doc fields ...
|
|
}
|
|
}
|
|
---------------
|
|
|
|
This led to some ambiguity when a document also included a field with the same
|
|
name as the `type`. We no longer accept the outer `type` wrapper, but this
|
|
behaviour can be reenabled on an index-by-index basis with the setting:
|
|
`index.mapping.allow_type_wrapper`.
|
|
|
|
== Search requests
|
|
|
|
While the `search` API takes a top-level `query` parameter, the
|
|
<<search-count,`count`>>, <<docs-delete-by-query,`delete-by-query`>> and
|
|
<<search-validate,`validate-query`>> requests expected the whole body to be a
|
|
query. These now _require_ a top-level `query` parameter:
|
|
|
|
[source,json]
|
|
---------------
|
|
GET /_count
|
|
{
|
|
"query": {
|
|
"match": {
|
|
"title": "Interesting stuff"
|
|
}
|
|
}
|
|
}
|
|
---------------
|
|
|
|
Also, the top-level `filter` parameter in search has been renamed to
|
|
<<search-request-post-filter,`post_filter`>>, to indicate that it should not
|
|
be used as the primary way to filter search results (use a
|
|
<<query-dsl-filtered-query,`filtered` query>> instead), but only to filter
|
|
results AFTER aggregations have been calculated.
|
|
|
|
This example counts the top colors in all matching docs, but only returns docs
|
|
with color `red`:
|
|
|
|
[source,json]
|
|
---------------
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"match_all": {}
|
|
},
|
|
"aggs": {
|
|
"colors": {
|
|
"terms": { "field": "color" }
|
|
}
|
|
},
|
|
"post_filter": {
|
|
"term": {
|
|
"color": "red"
|
|
}
|
|
}
|
|
}
|
|
---------------
|
|
|
|
== Multi-fields
|
|
|
|
Multi-fields are dead! Long live multi-fields! Well, the field type
|
|
`multi_field` has been removed. Instead, any of the core field types
|
|
(excluding `object` and `nested`) now accept a `fields` parameter. It's the
|
|
same thing, but nicer. Instead of:
|
|
|
|
[source,json]
|
|
---------------
|
|
"title": {
|
|
"type": "multi_field",
|
|
"fields": {
|
|
"title": { "type": "string" },
|
|
"raw": { "type": "string", "index": "not_analyzed" }
|
|
}
|
|
}
|
|
---------------
|
|
|
|
you can now write:
|
|
|
|
[source,json]
|
|
---------------
|
|
"title": {
|
|
"type": "string",
|
|
"fields": {
|
|
"raw": { "type": "string", "index": "not_analyzed" }
|
|
}
|
|
}
|
|
---------------
|
|
|
|
Existing multi-fields will be upgraded to the new format automatically.
|
|
|
|
Also, instead of having to use the arcane `path` and `index_name` parameters
|
|
in order to index multiple fields into a single ``custom +_all+ field'', you
|
|
can now use the <<copy-to,`copy_to` parameter>>.
|
|
|
|
== Stopwords
|
|
|
|
Previously, the <<analysis-standard-analyzer,`standard`>> and
|
|
<<analysis-pattern-analyzer,`pattern`>> analyzers used the list of English stopwords
|
|
by default, which caused some hard to debug indexing issues. Now they are set to
|
|
use the empty stopwords list (ie `_none_`) instead.
|
|
|
|
== Dates without years
|
|
|
|
When dates are specified without a year, for example: `Dec 15 10:00:00` they
|
|
are treated as dates in 2000 during indexing and range searches... except for
|
|
the upper included bound `lte` where they were treated as dates in 1970! Now,
|
|
all https://github.com/elasticsearch/elasticsearch/issues/4451[dates without years]
|
|
use `1970` as the default.
|
|
|
|
== Parameters
|
|
|
|
* Geo queries used to use `miles` as the default unit. And we
|
|
http://en.wikipedia.org/wiki/Mars_Climate_Orbiter[all know what
|
|
happened at NASA] because of that decision. The new default unit is
|
|
https://github.com/elasticsearch/elasticsearch/issues/4515[`meters`].
|
|
|
|
* For all queries that support _fuzziness_, the `min_similarity`, `fuzziness`
|
|
and `edit_distance` parameters have been unified as the single parameter
|
|
`fuzziness`. See <<fuzziness>> for details of accepted values.
|
|
|
|
* The `ignore_missing` parameter has been replaced by the `expand_wildcards`,
|
|
`ignore_unavailable` and `allow_no_indices` parameters, all of which have
|
|
sensible defaults. See <<multi-index,the multi-index docs>> for more.
|
|
|
|
* An index name (or pattern) is now required for destructive operations like
|
|
deleting indices:
|
|
+
|
|
[source,sh]
|
|
---------------
|
|
# v0.90 - delete all indices:
|
|
DELETE /
|
|
|
|
# v1.0 - delete all indices:
|
|
DELETE /_all
|
|
DELETE /*
|
|
---------------
|
|
+
|
|
Setting `action.destructive_requires_name` to `true` provides further safety
|
|
by disabling wildcard expansion on destructive actions.
|
|
|
|
== Return values
|
|
|
|
* The `ok` return value has been removed from all response bodies as it added
|
|
no useful information.
|
|
|
|
* The `found`, `not_found` and `exists` return values have been unified as
|
|
`found` on all relevant APIs.
|
|
|
|
* Field values, in response to the <<search-request-fields,`fields`>>
|
|
parameter, are now always returned as arrays. A field could have single or
|
|
multiple values, which meant that sometimes they were returned as scalars
|
|
and sometimes as arrays. By always returning arrays, this simplifies user
|
|
code. The only exception to this rule is when `fields` is used to retrieve
|
|
metadata like the `routing` value, which are always singular. Metadata
|
|
fields are always returned as scalars.
|
|
+
|
|
The `fields` parameter is intended to be used for retrieving stored fields,
|
|
rather than for fields extracted from the `_source`. That means that it can no
|
|
longer be used to return whole objects and it no longer accepts the
|
|
`_source.fieldname` format. For these you should use the
|
|
<<search-request-source-filtering,`_source`  `_source_include` and `_source_exclude`>>
|
|
parameters instead.
|
|
|
|
* Settings, like `index.analysis.analyzer.default` are now returned as proper
|
|
nested JSON objects, which makes them easier to work with programatically:
|
|
+
|
|
[source,json]
|
|
---------------
|
|
{
|
|
"index": {
|
|
"analysis": {
|
|
"analyzer": {
|
|
"default": xxx
|
|
}
|
|
}
|
|
}
|
|
}
|
|
---------------
|
|
+
|
|
You can choose to return them in flattened format by passing `?flat_settings`
|
|
in the query string.
|
|
|
|
* The <<indices-analyze,`analyze`>> API no longer supports the text response
|
|
format, but does support JSON and YAML.
|
|
|
|
== Deprecations
|
|
|
|
* The `text` query has been removed. Use the
|
|
<<query-dsl-match-query,`match`>> query instead.
|
|
|
|
* The `field` query has been removed. Use the
|
|
<<query-dsl-query-string-query,`query_string`>> query instead.
|
|
|
|
* Per-document boosting with the <<mapping-boost-field,`_boost`>> field has
|
|
been removed. You can use the
|
|
<<function-score-instead-of-boost,`function_score`>> instead.
|
|
|
|
* The `path` parameter in mappings has been deprecated. Use the
|
|
<<copy-to,`copy_to`>> parameter instead.
|
|
|
|
* The `custom_score` and `custom_boost_score` is no longer supported. You can
|
|
use <<query-dsl-function-score-query,`function_score`>> instead.
|
|
|
|
== Percolator
|
|
|
|
The percolator has been redesigned and because of this the dedicated `_percolator` index is no longer used by the percolator,
|
|
but instead the percolator works with a dedicated `.percolator` type. Read the http://www.elasticsearch.org/blog/percolator-redesign-blog-post/[redesigned percolator]
|
|
blog post for the reasons why the percolator has been redesigned.
|
|
|
|
Elasticsearch will *not* delete the `_percolator` index when upgrading, only the percolate api will not use the queries
|
|
stored in the `_percolator` index. In order to use the already stored queries, you can just re-index the queries from the
|
|
`_percolator` index into any index under the reserved `.percolator` type. The format in which the percolate queries
|
|
were stored has *not* been changed. So a simple script that does a scan search to retrieve all the percolator queries
|
|
and then does a bulk request into another index should be sufficient.
|