[DOCS] Added breaking changes in 1.0
This commit is contained in:
Clinton Gormley
parent
baf3bd9224
commit
faddd66e87
|
|
@ -81,6 +81,7 @@ Lucene `NIOFSDirectory`) using NIO. It allows multiple threads to read
|
|||
from the same file concurrently. It is not recommended on Windows
|
||||
because of a bug in the SUN Java implementation.
|
||||
|
||||
[[mmapfs]]
|
||||
[float]
|
||||
==== MMap FS
|
||||
|
||||
|
|
|
|||
|
|
@ -3,6 +3,8 @@
|
|||
|
||||
include::setup.asciidoc[]
|
||||
|
||||
include::migration/migrate_1_0.asciidoc[]
|
||||
|
||||
include::api-conventions.asciidoc[]
|
||||
|
||||
include::docs.asciidoc[]
|
||||
|
|
@ -29,3 +31,5 @@ include::testing.asciidoc[]
|
|||
|
||||
include::glossary.asciidoc[]
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,345 @@
|
|||
[[breaking-changes]]
|
||||
= Breaking changes in 1.0
|
||||
|
||||
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 have been changed to all accept 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 facets/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.
|
||||
|
||||
== 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 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.
|
||||
|
||||
* 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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue