<commit_before>[[breaking-changes-3.0]]
== Breaking changes in 3.0

This section discusses the changes that you need to be aware of when migrating
your application to Elasticsearch 3.0.

* <<breaking_30_search_changes>>
* <<breaking_30_rest_api_changes>>
* <<breaking_30_parent_child_changes>>
* <<breaking_30_settings_changes>>
* <<breaking_30_mapping_changes>>
* <<breaking_30_plugins>>
* <<breaking_30_java_api_changes>>
* <<breaking_30_cache_concurrency>>
* <<breaking_30_non_loopback>>
* <<breaking_30_thread_pool>>
* <<breaking_30_allocation>>
* <<breaking_30_percolator>>
* <<breaking_30_packaging>>
* <<breaking_30_scripting>>
* <<breaking_30_term_vectors>>

[[breaking_30_search_changes]]
=== Warmers

Thanks to several changes like doc values by default or disk-based norms,
warmers have become quite useless. As a consequence, warmers and the warmer
API have been removed: it is not possible anymore to register queries that
will run before a new IndexSearcher is published.

Don't worry if you have warmers defined on your indices, they will simply be
ignored when upgrading to 3.0.

=== Search changes

==== `search_type=count` removed

The `count` search type was deprecated since version 2.0.0 and is now removed.
In order to get the same benefits, you just need to set the value of the `size`
parameter to `0`.

For instance, the following request:

[source,sh]
---------------
GET /my_index/_search?search_type=count
{
  "aggs": {
    "my_terms": {
       "terms": {
         "field": "foo"
       }
     }
  }
}
---------------

can be replaced with:

[source,sh]
---------------
GET /my_index/_search
{
  "size": 0,
  "aggs": {
    "my_terms": {
       "terms": {
         "field": "foo"
       }
     }
  }
}
---------------

==== `search_type=scan` removed

The `scan` search type was deprecated since version 2.1.0 and is now removed.
All benefits from this search type can now be achieved by doing a scroll
request that sorts documents in `_doc` order, for instance:

[source,sh]
---------------
GET /my_index/_search?scroll=2m
{
  "sort": [
    "_doc"
  ]
}
---------------

Scroll requests sorted by `_doc` have been optimized to more efficiently resume
from where the previous request stopped, so this will have the same performance
characteristics as the former `scan` search type.

[[breaking_30_rest_api_changes]]
=== REST API changes

==== search exists api removed

The search exists api has been removed in favour of using the search api with
`size` set to `0` and `terminate_after` set to `1`.

==== `/_optimize` endpoint removed

The deprecated `/_optimize` endpoint has been removed. The `/_forcemerge`
endpoint should be used in lieu of optimize.

The `GET` HTTP verb for `/_forcemerge` is no longer supported, please use the
`POST` HTTP verb.

==== Deprecated queries removed

The following deprecated queries have been removed:
* `filtered`: use `bool` query instead, which supports `filter` clauses too
* `and`: use `must` clauses in a `bool` query instead
* `or`: use should clauses in a `bool` query instead
* `limit`: use `terminate_after` parameter instead
* `fquery`: obsolete after filters and queries have been merged
* `query`: obsolete after filters and queries have been merged

==== Unified fuzziness parameter

* Removed support for the deprecated `min_similarity` parameter in `fuzzy query`, in favour of `similarity`.
* Removed support for the deprecated `fuzzy_min_sim` parameter in `query_string` query, in favour of `similarity`.
* Removed support for the deprecated `edit_distance` parameter in completion suggester, in favour of `similarity`.

==== indices query

Removed support for the deprecated `filter` and `no_match_filter` fields in `indices` query,
in favour of `query` and `no_match_query`.

==== nested query

Removed support for the deprecated `filter` fields in `nested` query, in favour of `query`.

==== terms query

Removed support for the deprecated `minimum_should_match` and `disable_coord` in `terms` query, use `bool` query instead.
Removed also support for the deprecated `execution` parameter.

==== function_score query

Removed support for the top level `filter` element in `function_score` query, replaced by `query`.

==== highlighters

Removed support for multiple highlighter names, the only supported ones are: `plain`, `fvh` and `postings`.

==== top level filter

Removed support for the deprecated top level `filter` in the search api, replaced by `post_filter`.

==== `query_binary` and `filter_binary` removed

Removed support for the undocumented `query_binary` and `filter_binary` sections of a search request.

==== `span_near`'s' `collect_payloads` deprecated

Payloads are now loaded when needed.

[[breaking_30_parent_child_changes]]
=== Parent/Child changes

The `children` aggregation, parent child inner hits and `has_child` and `has_parent` queries will not work on indices
with `_parent` field mapping created before version `2.0.0`. The data of these indices need to be re-indexed into a new index.

The format of the join between parent and child documents have changed with the `2.0.0` release. The old
format can't read from version `3.0.0` and onwards. The new format allows for a much more efficient and
scalable join between parent and child documents and the join data structures are stored on on disk
data structures as opposed as before the join data structures were stored in the jvm heap space.

==== `score_type` has been removed

The `score_type` option has been removed from the `has_child` and `has_parent` queries in favour of the `score_mode` option
which does the exact same thing.

==== `sum` score mode removed

The `sum` score mode has been removed in favour of the `total` mode which does the same and is already available in
previous versions.

==== `max_children` option

When `max_children` was set to `0` on the `has_child` query then there was no upper limit on how many children documents
are allowed to match. This has changed and `0` now really means to zero child documents are allowed. If no upper limit
is needed then the `max_children` option shouldn't be defined at all on the `has_child` query.

==== `_parent` field no longer indexed

The join between parent and child documents no longer relies on indexed fields and therefor from `3.0.0` onwards
the `_parent` indexed field won't be indexed. In order to find documents that referrer to a specific parent id
the new `parent_id` query can be used. The get response and hits inside the search response remain to include
the parent id under the `_parent` key.

[[breaking_30_settings_changes]]
=== Settings changes

==== Analysis settings

The `index.analysis.analyzer.default_index` analyzer is not supported anymore.
If you wish to change the analyzer to use for indexing, change the
`index.analysis.analyzer.default` analyzer instead.

==== Ping timeout settings

Previously, there were three settings for the ping timeout: `discovery.zen.initial_ping_timeout`,
`discovery.zen.ping.timeout` and `discovery.zen.ping_timeout`. The former two have been removed and
the only setting key for the ping timeout is now `discovery.zen.ping_timeout`. The default value for
ping timeouts remains at three seconds.

==== Recovery settings

Recovery settings deprecated in 1.x have been removed:

 * `index.shard.recovery.translog_size` is superseded by `indices.recovery.translog_size`
 * `index.shard.recovery.translog_ops` is superseded by `indices.recovery.translog_ops`
 * `index.shard.recovery.file_chunk_size` is superseded by `indices.recovery.file_chunk_size`
 * `index.shard.recovery.concurrent_streams` is superseded by `indices.recovery.concurrent_streams`
 * `index.shard.recovery.concurrent_small_file_streams` is superseded by `indices.recovery.concurrent_small_file_streams`
 * `indices.recovery.max_size_per_sec` is superseded by `indices.recovery.max_bytes_per_sec`

If you are using any of these settings please take the time and review their purpose. All of the settings above are considered
_expert settings_ and should only be used if absolutely necessary. If you have set any of the above setting as persistent<commit_msg>Add notice in migration docs<commit_after>[[breaking-changes-3.0]]
== Breaking changes in 3.0

This section discusses the changes that you need to be aware of when migrating
your application to Elasticsearch 3.0.

* <<breaking_30_search_changes>>
* <<breaking_30_rest_api_changes>>
* <<breaking_30_parent_child_changes>>
* <<breaking_30_settings_changes>>
* <<breaking_30_mapping_changes>>
* <<breaking_30_plugins>>
* <<breaking_30_java_api_changes>>
* <<breaking_30_cache_concurrency>>
* <<breaking_30_non_loopback>>
* <<breaking_30_thread_pool>>
* <<breaking_30_allocation>>
* <<breaking_30_percolator>>
* <<breaking_30_packaging>>
* <<breaking_30_scripting>>
* <<breaking_30_term_vectors>>

[[breaking_30_search_changes]]
=== Warmers

Thanks to several changes like doc values by default or disk-based norms,
warmers have become quite useless. As a consequence, warmers and the warmer
API have been removed: it is not possible anymore to register queries that
will run before a new IndexSearcher is published.

Don't worry if you have warmers defined on your indices, they will simply be
ignored when upgrading to 3.0.

=== Search changes

==== `search_type=count` removed

The `count` search type was deprecated since version 2.0.0 and is now removed.
In order to get the same benefits, you just need to set the value of the `size`
parameter to `0`.

For instance, the following request:

[source,sh]
---------------
GET /my_index/_search?search_type=count
{
  "aggs": {
    "my_terms": {
       "terms": {
         "field": "foo"
       }
     }
  }
}
---------------

can be replaced with:

[source,sh]
---------------
GET /my_index/_search
{
  "size": 0,
  "aggs": {
    "my_terms": {
       "terms": {
         "field": "foo"
       }
     }
  }
}
---------------

==== `search_type=scan` removed

The `scan` search type was deprecated since version 2.1.0 and is now removed.
All benefits from this search type can now be achieved by doing a scroll
request that sorts documents in `_doc` order, for instance:

[source,sh]
---------------
GET /my_index/_search?scroll=2m
{
  "sort": [
    "_doc"
  ]
}
---------------

Scroll requests sorted by `_doc` have been optimized to more efficiently resume
from where the previous request stopped, so this will have the same performance
characteristics as the former `scan` search type.

[[breaking_30_rest_api_changes]]
=== REST API changes

==== search exists api removed

The search exists api has been removed in favour of using the search api with
`size` set to `0` and `terminate_after` set to `1`.

==== `/_optimize` endpoint removed

The deprecated `/_optimize` endpoint has been removed. The `/_forcemerge`
endpoint should be used in lieu of optimize.

The `GET` HTTP verb for `/_forcemerge` is no longer supported, please use the
`POST` HTTP verb.

==== Deprecated queries removed

The following deprecated queries have been removed:
* `filtered`: use `bool` query instead, which supports `filter` clauses too
* `and`: use `must` clauses in a `bool` query instead
* `or`: use should clauses in a `bool` query instead
* `limit`: use `terminate_after` parameter instead
* `fquery`: obsolete after filters and queries have been merged
* `query`: obsolete after filters and queries have been merged

==== Unified fuzziness parameter

* Removed support for the deprecated `min_similarity` parameter in `fuzzy query`, in favour of `similarity`.
* Removed support for the deprecated `fuzzy_min_sim` parameter in `query_string` query, in favour of `similarity`.
* Removed support for the deprecated `edit_distance` parameter in completion suggester, in favour of `similarity`.

==== indices query

Removed support for the deprecated `filter` and `no_match_filter` fields in `indices` query,
in favour of `query` and `no_match_query`.

==== nested query

Removed support for the deprecated `filter` fields in `nested` query, in favour of `query`.

==== terms query

Removed support for the deprecated `minimum_should_match` and `disable_coord` in `terms` query, use `bool` query instead.
Removed also support for the deprecated `execution` parameter.

==== function_score query

Removed support for the top level `filter` element in `function_score` query, replaced by `query`.

==== highlighters

Removed support for multiple highlighter names, the only supported ones are: `plain`, `fvh` and `postings`.

==== top level filter

Removed support for the deprecated top level `filter` in the search api, replaced by `post_filter`.

==== `query_binary` and `filter_binary` removed

Removed support for the undocumented `query_binary` and `filter_binary` sections of a search request.

==== `span_near`'s' `collect_payloads` deprecated

Payloads are now loaded when needed.

[[breaking_30_parent_child_changes]]
=== Parent/Child changes

The `children` aggregation, parent child inner hits and `has_child` and `has_parent` queries will not work on indices
with `_parent` field mapping created before version `2.0.0`. The data of these indices need to be re-indexed into a new index.

The format of the join between parent and child documents have changed with the `2.0.0` release. The old
format can't read from version `3.0.0` and onwards. The new format allows for a much more efficient and
scalable join between parent and child documents and the join data structures are stored on on disk
data structures as opposed as before the join data structures were stored in the jvm heap space.

==== `score_type` has been removed

The `score_type` option has been removed from the `has_child` and `has_parent` queries in favour of the `score_mode` option
which does the exact same thing.

==== `sum` score mode removed

The `sum` score mode has been removed in favour of the `total` mode which does the same and is already available in
previous versions.

==== `max_children` option

When `max_children` was set to `0` on the `has_child` query then there was no upper limit on how many children documents
are allowed to match. This has changed and `0` now really means to zero child documents are allowed. If no upper limit
is needed then the `max_children` option shouldn't be defined at all on the `has_child` query.

==== `_parent` field no longer indexed

The join between parent and child documents no longer relies on indexed fields and therefor from `3.0.0` onwards
the `_parent` indexed field won't be indexed. In order to find documents that referrer to a specific parent id
the new `parent_id` query can be used. The get response and hits inside the search response remain to include
the parent id under the `_parent` key.

[[breaking_30_settings_changes]]
=== Settings changes

From Elasticsearch 3.0 on all settings are validated before they are applied. Node level and default index
level settings are validated on node startup, dynamic cluster and index setting are validated before they are updated/added
to the cluster state. Every setting must be a _known_ setting or in other words all settings must be registered with the
node or transport client they are used with. This implies that plugins that define custom settings must register all of their
settings during pluging loading on the `SettingsModule#registerSettings(Setting)` method.

==== Node settings

The `name` settings has been remove and is replaced with `node.name`. Usage of `-Dname=some_node_name` is not supported
anymore. Scripts must be updated accordingly.

==== Transport Settings

All settings with a `netty` infix have been replaced by their already existing `transport` synonyms. For instance `transport.netty.bind_host` is
now not supported anymore and should be replaced by the superseeding setting `transport.bind_host`.

==== Analysis settings

The `index.analysis.analyzer.default_index` analyzer is not supported anymore.
If you wish to change the analyzer to use for indexing, change the
`index.analysis.analyzer.default` analyzer instead.

==== Ping timeout settings

Previously, there were three settings for the ping timeout: `discovery.zen.initial_ping_timeout`,
`discovery.zen.ping.timeout` and `discovery.zen.ping_timeout`. The former two have been removed and
the only setting key for the ping timeout is now `discovery.zen.ping_timeout`. The default value for
ping timeouts remains at three seconds.

==== Recovery settings

Recovery settings deprecated in 1.x have been removed:

 * `index.shard.recovery.translog_size` is superseded by `indices.recovery.translog_size`
 * `index.shard.recovery.translog_ops` is superseded by `indices.recovery.translog_ops`
 * `index.shard.recovery.file_chunk_size` is superseded by `indices.recovery.file_chunk_size`
 * `index.shard.recovery.concurrent_streams` is superseded by `indices.recovery.concurrent_streams`
 * `index.shard.recovery.concurrent_small_file_streams` is superseded by `indices.recovery.concurrent_small_file_streams`
 * `indices.recovery.max_size_per_sec` is superseded by `indices.recovery.max_bytes_per_sec`

If you are using any of these settings please take the time and review their purpose. All of the settings above are considered
_expert settings_ and should only be used if absolutely necessary. If you have set any of the above setting as persistent
{'fraction_non_alphanumeric': 0.09063042220936958, 'fraction_numerical': 0.008444187391555813, 'mean_word_length': 4.634082763115021, 'pattern_counts': {'":': 20, '<': 63, '<?xml version=': 0, '>': 63, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3823903', 'n_tokens_mistral': 4913, 'n_tokens_neox': 4685, 'n_words': 2160}