[[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 <> by default. Make sure that you set <> 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 <>: + [source,yaml] --------------- cluster.routing.allocation.enable: all|primaries|new_primaries|none --------------- == Stats and Info APIs The <>, <>, <> and <> 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 <>, <>, <>, <>, <>, <>, <>, and <> 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 <>, <> and <> 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 <>, to indicate that it should not be used as the primary way to filter search results (use a <> 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 <> and <> 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 <> 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 <> 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 <> 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 <> 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 <> API no longer supports the text response format, but does support JSON and YAML. == Deprecations * The `text` query has been removed. Use the <> query instead. * The `field` query has been removed. Use the <> query instead. * Per-document boosting with the <> field has been removed. You can use the <> instead. * The `path` parameter in mappings has been deprecated. Use the <> parameter instead.