[DOCS] Added breaking changes in 1.0

Author: clintongormley

docs/reference/index-modules/store.asciidoc

@@ -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
 

docs/reference/index.asciidoc

@@ -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[]
 
+
+

docs/reference/migration/migrate_1_0.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.
+
+