1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376
|
[[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 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.
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`  `_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.
|