OpenSearch/docs/reference/migration/migrate_1_0.asciidoc

[[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`&#32; `_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.