rest-api-changes.asciidoc 35 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038
  1. [discrete]
  2. [[breaking_80_rest_api_changes]]
  3. ==== REST API changes
  4. //NOTE: The notable-breaking-changes tagged regions are re-used in the
  5. //Installation and Upgrade Guide
  6. //tag::notable-breaking-changes[]
  7. .REST API endpoints containing `_xpack` have been removed.
  8. [%collapsible]
  9. ====
  10. *Details* +
  11. In 7.0, we deprecated REST endpoints that contain `_xpack` in their path. These
  12. endpoints are now removed in 8.0. Each endpoint that was deprecated and removed
  13. is replaced with a new endpoint that does not contain `_xpack`. As an example,
  14. `/{index}/_xpack/graph/_explore` is replaced by `/{index}/_graph/explore`.
  15. *Impact* +
  16. Use the replacement REST API endpoints. Requests submitted to the `_xpack`
  17. API endpoints will return an error.
  18. ====
  19. [[remove-mapping-type-api-endpoints]]
  20. .REST API endpoints containing mapping types have been removed.
  21. [%collapsible]
  22. ====
  23. *Details* +
  24. Mapping types have been removed. API endpoints that contain a mapping type have
  25. also been removed. Use a typeless endpoint instead.
  26. [options="header",cols="<1,<3,<1"]
  27. |====
  28. | API | Typed API endpoint | Typeless API endpoint
  29. | {ref}/docs-bulk.html[Bulk]
  30. | `<target>/<type>/_bulk`
  31. | `<target>/_bulk`
  32. | {ref}/search-count.html[Count]
  33. | `<target>/<type>/_count`
  34. | `<target>/_count`
  35. | {ref}/docs-delete.html[Delete]
  36. | `<index>/<type>/<_id>`
  37. | `<index>/_doc/<_id>`
  38. | {ref}/docs-delete-by-query.html[Delete by query]
  39. | `<target>/<type>/_delete_by_query`
  40. | `<target>/_delete_by_query`
  41. | {ref}/search-explain.html[Explain]
  42. | `<index>/<type>/<_id>/_explain`
  43. | `<index>/_explain/<_id>`
  44. | {ref}/docs-get.html[Get]
  45. | `<index>/<type>/<_id>`
  46. | `<index>/_doc/<_id>`
  47. |
  48. | `<index>/<type>/<_id>/_source`
  49. | `<index>/_source/<_id>`
  50. | {ref}/indices-get-field-mapping.html[Get field mapping]
  51. | `_mapping/<type>/field/<field>`
  52. | `_mapping/field/<field>`
  53. |
  54. | `<target>/_mapping/<type>/field/<field>`
  55. | `<target>/_mapping/field/<field>`
  56. | {ref}/indices-get-mapping.html[Get mapping]
  57. | `_mapping/<type>`
  58. | `_mapping` or `<target>/_mapping`
  59. |
  60. | `<target>/<type>/_mapping`
  61. | `<target>/_mapping`
  62. |
  63. | `<target>/_mapping/<type>`
  64. | `<target>/_mapping`
  65. | {ref}/graph-explore-api.html[Graph explore]
  66. | `<index>/<type>/_graph/explore`
  67. | `<index>/_graph/explore`
  68. | {ref}/docs-index_.html[Index]
  69. | `<target>/<type>/<_id>/_create`
  70. | `<target>/_create/<_id>`
  71. |
  72. | `<target>/<type>`
  73. | `<target>/_doc`
  74. |
  75. | `<target>/<type>/<_id>`
  76. | `<target>/_doc/<_id>`
  77. | {ref}/docs-multi-get.html[Multi get]
  78. | `<index>/<type>/_mget`
  79. | `<index>/_mget`
  80. | {ref}/search-multi-search.html[Multi search]
  81. | `<target>/<type>/_msearch`
  82. | `<target>/_msearch`
  83. | {ref}/multi-search-template.html[Multi search template]
  84. | `<target>/<type>/_msearch/template`
  85. | `<target>/_msearch/template`
  86. | {ref}/docs-multi-termvectors.html[Multi term vectors]
  87. | `<index>/<type>/_mtermvectors`
  88. | `<index>/_mtermvectors`
  89. | {ref}/rollup-search.html[Rollup search]
  90. | `<target>/<type>/_rollup_search`
  91. | `<target>/_rollup_search`
  92. | {ref}/search-search.html[Search]
  93. | `<target>/<type>/_search`
  94. | `<target>/_search`
  95. | {ref}/search-template-api.html[Search template]
  96. | `<target>/<type>/_search/template`
  97. | `<target>/_search/template`
  98. | {ref}/docs-termvectors.html[Term vectors]
  99. | `<index>/<mapping_type>/<_id>/_termvectors`
  100. | `<index>/_termvectors<_id>`
  101. |
  102. | `<index>/<mapping_type>/_termvectors`
  103. | `<index>/_termvectors`
  104. | {ref}/docs-update.html[Update]
  105. | `<index>/<type>/<_id>/_update`
  106. | `<index>/_update/<_id>`
  107. | {ref}/docs-update-by-query.html[Update by query]
  108. | `<target>/<type>/_update_by_query`
  109. | `<target>/_update_by_query`
  110. | {ref}/indices-put-mapping.html[Update mapping]
  111. | `<target>/<type>/_mapping`
  112. | `<target>/_mapping`
  113. |
  114. | `<target>/_mapping/<type>`
  115. | `<target>/_mapping`
  116. |
  117. | `_mapping/<type>`
  118. | `<target>/_mapping`
  119. | {ref}/search-validate.html[Validate]
  120. | `<target>/<type>/_validate/query`
  121. | `<target>/_validate/query`
  122. |====
  123. *Impact* +
  124. Update your application to use typeless REST API endpoints. Requests to
  125. endpoints that contain a mapping type will return an error.
  126. ====
  127. [[remove-term-order-key]]
  128. .The `terms` aggregation no longer supports the `_term` order key.
  129. [%collapsible]
  130. ====
  131. *Details* +
  132. The `terms` aggregation no longer supports the `_term` key in `order` values. To
  133. sort buckets by their term, use `_key` instead.
  134. *Impact* +
  135. Discontinue use of the `_term` order key. Requests that include a `_term` order
  136. key will return an error.
  137. ====
  138. [[remove-time-order-key]]
  139. .The `date_histogram` aggregation no longer supports the `_time` order key.
  140. [%collapsible]
  141. ====
  142. *Details* +
  143. The `date_histogram` aggregation no longer supports the `_time` key in `order`
  144. values. To sort buckets by their key, use `_key` instead.
  145. *Impact* +
  146. Discontinue use of the `_time` order key. Requests that include a `_time` order
  147. key will return an error.
  148. ====
  149. [[remove-moving-avg-agg]]
  150. .The `moving_avg` aggregation has been removed.
  151. [%collapsible]
  152. ====
  153. *Details* +
  154. The `moving_avg` aggregation was deprecated in 6.4 and has been removed. To
  155. calculate moving averages, use the
  156. {ref}/search-aggregations-pipeline-movfn-aggregation.html[`moving_fn`
  157. aggregation] instead.
  158. *Impact* +
  159. Discontinue use of the `moving_avg` aggregation. Requests that include the
  160. `moving_avg` aggregation will return an error.
  161. ====
  162. [[percentile-duplication]]
  163. .The `percentiles` aggregation's `percents` parameter no longer supports duplicate values.
  164. [%collapsible]
  165. ====
  166. *Details* +
  167. If you specify the `percents` parameter with the
  168. {ref}/search-aggregations-metrics-percentile-aggregation.html[`percentiles` aggregation],
  169. its values must be unique. Otherwise, an exception occurs.
  170. *Impact* +
  171. Use unique values in the `percents` parameter of the `percentiles` aggregation.
  172. Requests containing duplicate values in the `percents` parameter will return
  173. an error.
  174. ====
  175. [[date-histogram-interval]]
  176. .The `date_histogram` aggregation's `interval` parameter is no longer valid.
  177. [%collapsible]
  178. ====
  179. *Details* +
  180. It is now an error to specify the `interval` parameter to the
  181. {ref}/search-aggregations-bucket-datehistogram-aggregation.html[`date_histogram`
  182. aggregation] or the
  183. {ref}/search-aggregations-bucket-composite-aggregation.html#_date_histogram[`composite
  184. date_histogram` source. Instead, please use either `calendar_interval` or
  185. `fixed_interval` as appropriate.
  186. *Impact* +
  187. Uses of the `interval` parameter in either the `date_histogram` aggregation or
  188. the `date_histogram` composite source will now generate an error. Instead
  189. please use the more specific `fixed_interval` or `calendar_interval`
  190. parameters.
  191. ====
  192. [[ngram-edgengram-filter-names-removed]]
  193. .The `nGram` and `edgeNGram` token filter names have been removed.
  194. [%collapsible]
  195. ====
  196. *Details* +
  197. The `nGram` and `edgeNGram` token filter names that have been deprecated since
  198. version 6.4 have been removed. Both token filters can only be used by their
  199. alternative names `ngram` and `edge_ngram` since version 7.0.
  200. *Impact* +
  201. Use the equivalent `ngram` and `edge_ngram` token filters. Requests containing
  202. the `nGram` and `edgeNGram` token filter names will return an error.
  203. ====
  204. [[nGram-edgeNGram-tokenizer-dreprecation]]
  205. .The `nGram` and `edgeNGram` tokenizer names have been removed.
  206. [%collapsible]
  207. ====
  208. *Details* +
  209. The `nGram` and `edgeNGram` tokenizer names haven been deprecated with 7.6 and are no longer
  210. supported on new indices. Mappings for indices created after 7.6 will continue to work but
  211. emit a deprecation warning. The tokenizer name should be changed to the fully equivalent
  212. `ngram` or `edge_ngram` names for new indices and in index templates.
  213. *Impact* +
  214. Use the `ngram` and `edge_ngram` tokenizers. Requests to create new indices
  215. using the `nGram` and `edgeNGram` tokenizer names will return an error.
  216. ====
  217. .The `in_flight_requests` stat has been renamed `inflight_requests` in logs and diagnostic APIs.
  218. [%collapsible]
  219. ====
  220. *Details* +
  221. The name of the in flight requests circuit breaker in log output and diagnostic APIs (such as the node stats API) changes from `in_flight_requests` to `inflight_requests` to align it with the name of the corresponding settings.
  222. *Impact* +
  223. Update your workflow and applications to use the `inflight_requests` stat in
  224. place of `in_flight_requests`.
  225. ====
  226. .The voting configuration exclusions API endpoint has changed.
  227. [%collapsible]
  228. ====
  229. *Details* +
  230. The `POST /_cluster/voting_config_exclusions/{node_filter}` API has been
  231. removed in favour of `POST /_cluster/voting_config_exclusions?node_names=...`
  232. and `POST /_cluster/voting_config_exclusions?node_ids=...` which allow you to
  233. specify the names or IDs of the nodes to exclude.
  234. *Impact* +
  235. Use `POST /_cluster/voting_config_exclusions?node_ids=...` and specify the nodes
  236. to exclude instead of using a node filter. Requests submitted to the
  237. `/_cluster/voting_config_exclusions/{node_filter}` endpoint will return an
  238. error.
  239. ====
  240. .Remote system indices are not followed automatically if they match an auto-follow pattern.
  241. [%collapsible]
  242. ====
  243. *Details* +
  244. Remote system indices matching an {ref}/ccr-auto-follow.html[auto-follow
  245. pattern] won't be configured as a follower index automatically.
  246. *Impact* +
  247. Explicitly {ref}/ccr-put-follow.html[create a follower index] to follow a remote
  248. system index if that's the wanted behaviour.
  249. ====
  250. .The EQL `wildcard` function has been removed.
  251. [%collapsible]
  252. ====
  253. *Details* +
  254. The `wildcard` function was deprecated in {es} 7.13.0 and has been removed.
  255. *Impact* +
  256. Use the `like` or `regex` {ref}/eql-syntax.html#eql-syntax-pattern-comparison-keywords[keywords] instead.
  257. ====
  258. [[ilm-freeze-noop]]
  259. .The ILM `freeze` action is now a no-op.
  260. [%collapsible]
  261. ====
  262. *Details* +
  263. The ILM freeze action is now a no-op and performs no action on the index, as the freeze API endpoint
  264. has been removed in 8.0.
  265. *Impact* +
  266. Update your ILM policies to remove the `freeze` action from the `cold` phase.
  267. ====
  268. [[ilm-policy-validation]]
  269. .Additional validation for ILM policies.
  270. [%collapsible]
  271. ====
  272. *Details* +
  273. Creating or updating an ILM policy now requires that any referenced snapshot repositories and SLM
  274. policies exist.
  275. *Impact* +
  276. Update your code or configuration management to ensure that repositories and SLM policies are created
  277. before any policies that reference them.
  278. ====
  279. .The deprecated `_upgrade` API has been removed.
  280. [%collapsible]
  281. ====
  282. *Details* +
  283. Previously, the `_upgrade` API upgraded indices from the previous major
  284. version to the current version. The `_reindex` API should be used
  285. instead for that purpose.
  286. *Impact* +
  287. Requests made to the old `_upgrade` API will return an error.
  288. ====
  289. .The deprecated freeze index API has been removed.
  290. [%collapsible]
  291. ====
  292. *Details* +
  293. The freeze index API (`POST /<index>/_freeze`) has been removed.
  294. https://www.elastic.co/blog/significantly-decrease-your-elasticsearch-heap-memory-usage[Improvements
  295. in heap memory usage] have eliminated the reason to freeze indices.
  296. You can still unfreeze existing frozen indices using the
  297. {ref}/unfreeze-index-api.html[unfreeze index API]. For some use cases, the
  298. frozen tier may be a suitable replacement for frozen indices. See
  299. {ref}/data-tiers.html[data tiers] for more information.
  300. *Impact* +
  301. Requests made to the old freeze index API will return an error.
  302. ====
  303. .The force merge API's `max_num_segments` and `only_expunge_deletes` parameters cannot both be specified in the same request.
  304. [%collapsible]
  305. ====
  306. *Details* +
  307. Previously, the force merge API allowed the parameters `only_expunge_deletes`
  308. and `max_num_segments` to be set to a non default value at the same time. But
  309. the `max_num_segments` was silently ignored when `only_expunge_deletes` is set
  310. to `true`, leaving the false impression that it has been applied.
  311. *Impact* +
  312. When using the {ref}/indices-forcemerge.html[force merge API], do not specify
  313. values for both the `max_num_segments` and `only_expunge_deletes` parameters.
  314. Requests that include values for both parameters will return an error.
  315. ====
  316. .The create or update index template API's `template` parameter has been removed.
  317. [%collapsible]
  318. ====
  319. *Details* +
  320. In 6.0, we deprecated the `template` parameter in create or update index
  321. template requests in favor of using `index_patterns`. Support for the `template`
  322. parameter is now removed in 8.0.
  323. *Impact* +
  324. Use the {ref}/indices-templates-v1.html[create or update index template API]'s
  325. `index_patterns` parameter. Requests that include the `template` parameter will
  326. return an error.
  327. ====
  328. .Synced flush has been removed.
  329. [%collapsible]
  330. ====
  331. *Details* +
  332. Synced flush was deprecated in 7.6 and is removed in 8.0. Use a regular flush
  333. instead as it has the same effect as a synced flush in 7.6 and later.
  334. *Impact* +
  335. Use the {ref}/indices-flush.html[flush API]. Requests to the
  336. `/<index>/flush/synced` or `/flush/synced` endpoints will return an error.
  337. ====
  338. .The default for the `?wait_for_active_shards` parameter on the close index API has changed.
  339. [%collapsible]
  340. ====
  341. *Details* +
  342. When closing an index in earlier versions, by default {es} would not wait for
  343. the shards of the closed index to be properly assigned before returning. From
  344. version 8.0 onwards the default behaviour is to wait for shards to be assigned
  345. according to the
  346. {ref}/docs-index_.html#index-wait-for-active-shards[`index.write.wait_for_active_shards`
  347. index setting].
  348. *Impact* +
  349. Accept the new behaviour, or specify `?wait_for_active_shards=0` to preserve
  350. the old behaviour if needed.
  351. ====
  352. .The index stats API's `types` query parameter has been removed.
  353. [%collapsible]
  354. ====
  355. *Details* +
  356. The index stats API's `types` query parameter has been removed. Previously, you
  357. could combine `types` with the `indexing` query parameter to return indexing
  358. stats for specific mapping types. Mapping types have been removed in 8.0.
  359. *Impact* +
  360. Discontinue use of the `types` query parameter. Requests that include the
  361. parameter will return an error.
  362. ====
  363. .The `user_agent` ingest processor's `ecs` parameter has no effect.
  364. [%collapsible]
  365. ====
  366. *Details* +
  367. In 7.2, we deprecated the `ecs` parameter for the `user_agent` ingest processor.
  368. In 8.x, the `user_agent` ingest processor will only return {ecs-ref}[Elastic
  369. Common Schema (ECS)] fields, regardless of the `ecs` value.
  370. *Impact* +
  371. To avoid deprecation warnings, remove the parameter from your ingest pipelines.
  372. If a pipeline specifies an `ecs` value, the value is ignored.
  373. ====
  374. .The `include_type_name` query parameter has been removed.
  375. [%collapsible]
  376. ====
  377. *Details* +
  378. The `include_type_name` query parameter has been removed from the index
  379. creation, index template, and mapping APIs. Previously, you could set
  380. `include_type_name` to `true` to indicate that requests and responses should
  381. include a mapping type name. Mapping types have been removed in 8.x.
  382. *Impact* +
  383. Discontinue use of the `include_type_name` query parameter. Requests that
  384. include the parameter will return an error.
  385. ====
  386. .Reindex from remote now re-encodes URL-encoded index names.
  387. [%collapsible]
  388. ====
  389. *Details* +
  390. Reindex from remote would previously allow URL-encoded index names and not
  391. re-encode them when generating the search request for the remote host. This
  392. leniency has been removed such that all index names are correctly encoded when
  393. reindex generates remote search requests.
  394. *Impact* +
  395. Specify unencoded index names for reindex from remote requests.
  396. ====
  397. .In the reindex, delete by query, and update by query APIs, the `size` parameter has been renamed.
  398. [%collapsible]
  399. ====
  400. *Details* +
  401. Previously, a `_reindex` request had two different size specifications in the body:
  402. - Outer level, determining the maximum number of documents to process
  403. - Inside the `source` element, determining the scroll/batch size.
  404. The outer level `size` parameter has now been renamed to `max_docs` to
  405. avoid confusion and clarify its semantics.
  406. Similarly, the `size` parameter has been renamed to `max_docs` for
  407. `_delete_by_query` and `_update_by_query` to keep the 3 interfaces consistent.
  408. *Impact* +
  409. Use the replacement parameters. Requests containing the `size` parameter will
  410. return an error.
  411. ====
  412. .The update by query API now rejects unsupported `script` fields.
  413. [%collapsible]
  414. ====
  415. *Details* +
  416. An update by query API request that includes an unsupported field in the
  417. `script` object now returns an error. Previously, the API would silently ignore
  418. these unsupported fields.
  419. *Impact* +
  420. To avoid errors, remove unsupported fields from the `script` object.
  421. ====
  422. .The cat node API's `local` query parameter has been removed.
  423. [%collapsible]
  424. ====
  425. *Details* +
  426. The `?local` parameter to the `GET _cat/nodes` API was deprecated in 7.x and is
  427. rejected in 8.0. This parameter caused the API to use the local cluster state
  428. to determine the nodes returned by the API rather than the cluster state from
  429. the master, but this API requests information from each selected node
  430. regardless of the `?local` parameter which means this API does not run in a
  431. fully node-local fashion.
  432. *Impact* +
  433. Discontinue use of the `?local` query parameter. {ref}/cat-nodes.html[cat node
  434. API] requests that include this parameter will return an error.
  435. ====
  436. .The cat shard API's `local` query parameter has been removed.
  437. [%collapsible]
  438. ====
  439. *Details* +
  440. The `?local` parameter to the `GET _cat/shards` API was deprecated in 7.x and is
  441. rejected in 8.0. This parameter caused the API to use the local cluster state
  442. to determine the nodes returned by the API rather than the cluster state from
  443. the master, but this API requests information from each selected node
  444. regardless of the `?local` parameter which means this API does not run in a
  445. fully node-local fashion.
  446. *Impact* +
  447. Discontinue use of the `?local` query parameter. {ref}/cat-shards.html[cat shards
  448. API] requests that include this parameter will return an error.
  449. ====
  450. .The cat indices API's `local` query parameter has been removed.
  451. [%collapsible]
  452. ====
  453. *Details* +
  454. The `?local` parameter to the `GET _cat/indices` API was deprecated in 7.x and is
  455. rejected in 8.0. This parameter caused the API to use the local cluster state
  456. to determine the nodes returned by the API rather than the cluster state from
  457. the master, but this API requests information from each selected node
  458. regardless of the `?local` parameter which means this API does not run in a
  459. fully node-local fashion.
  460. *Impact* +
  461. Discontinue use of the `?local` query parameter. {ref}/cat-indices.html[cat indices
  462. API] requests that include this parameter will return an error.
  463. ====
  464. .The get field mapping API's `local` query parameter has been removed.
  465. [%collapsible]
  466. ====
  467. *Details* +
  468. The `local` parameter for get field mapping API was deprecated in 7.8 and is
  469. removed in 8.0. This parameter is a no-op and field mappings are always retrieved
  470. locally.
  471. *Impact* +
  472. Discontinue use of the `local` query parameter.
  473. {ref}/indices-get-field-mapping.html[get field mapping API] requests that
  474. include this parameter will return an error.
  475. ====
  476. .Post data to jobs API is deprecated.
  477. [%collapsible]
  478. ====
  479. *Details* +
  480. The {ml} {ref}/ml-post-data.html[post data to jobs API] is deprecated starting in 7.11.0
  481. and will be removed in a future major version.
  482. *Impact* +
  483. Use {ref}/ml-apis.html#ml-api-datafeed-endpoint[{dfeeds}] instead.
  484. ====
  485. .The `job_id` property of the Update {dfeeds} API has been removed.
  486. [%collapsible]
  487. ====
  488. *Details* +
  489. The ability to update a `job_id` in a {dfeed} was deprecated in 7.3.0. and is
  490. removed in 8.0.
  491. *Impact* +
  492. It is not possible to move {dfeeds} between {anomaly-jobs}.
  493. ====
  494. .Create repository and delete repository API's return `409` status code when a repository is in use instead of `500`.
  495. [%collapsible]
  496. ====
  497. *Details* +
  498. The {ref}/put-snapshot-repo-api.html[Create or update snapshot repository API] and
  499. {ref}/delete-snapshot-repo-api.html[Delete snapshot repository API] return `409`
  500. status code when the request is attempting to modify an existing repository that's in use instead of status code `500`.
  501. *Impact* +
  502. Update client code that handles creation and deletion of repositories to reflect this change.
  503. ====
  504. .The `allow_no_datafeeds` property has been removed from {ml} APIs.
  505. [%collapsible]
  506. ====
  507. *Details* +
  508. The `allow_no_datafeeds` property was deprecated in the
  509. {ref}/cat-datafeeds.html[cat {dfeeds}],
  510. {ref}/ml-get-datafeed.html[get {dfeeds}],
  511. {ref}/ml-get-datafeed-stats.html[get {dfeed} statistics], and
  512. {ref}/ml-stop-datafeed.html[stop {dfeeds}] APIs in 7.10.0.
  513. *Impact* +
  514. Use `allow_no_match` instead.
  515. ====
  516. .The `allow_no_jobs` property has been removed from {ml} APIs.
  517. [%collapsible]
  518. ====
  519. *Details* +
  520. The `allow_no_jobs` property was deprecated in the
  521. {ref}/cat-anomaly-detectors.html[cat anomaly detectors],
  522. {ref}/ml-close-job.html[close {anomaly-jobs}],
  523. {ref}/ml-get-job.html[get {anomaly-jobs}],
  524. {ref}/ml-get-job-stats.html[get {anomaly-job} statistics], and
  525. {ref}/ml-get-overall-buckets.html[get overall buckets] APIs in 7.10.0.
  526. *Impact* +
  527. Use `allow_no_match` instead.
  528. ====
  529. .The StartRollupJob endpoint now returns a success status if a job has already started.
  530. [%collapsible]
  531. ====
  532. *Details* +
  533. Previously, attempting to start an already-started rollup job would
  534. result in a `500 InternalServerError: Cannot start task for Rollup Job
  535. [job] because state was [STARTED]` exception.
  536. Now, attempting to start a job that is already started will just
  537. return a successful `200 OK: started` response.
  538. *Impact* +
  539. Update your workflow and applications to assume that a 200 status in response to
  540. attempting to start a rollup job means the job is in an actively started state.
  541. The request itself may have started the job, or it was previously running and so
  542. the request had no effect.
  543. ====
  544. .Stored scripts no longer support empty scripts or search templates.
  545. [%collapsible]
  546. ====
  547. *Details* +
  548. The {ref}/create-stored-script-api.html[create or update stored script API]'s
  549. `source` parameter cannot be empty.
  550. *Impact* +
  551. Before upgrading, use the {ref}/delete-stored-script-api.html[delete stored
  552. script API] to delete any empty stored scripts or search templates.
  553. In 8.0, {es} will drop any empty stored scripts or empty search templates from
  554. the cluster state. Requests to create a stored script or search template with
  555. an empty `source` will return an error.
  556. ====
  557. .The create or update stored script API's `code` parameter has been removed.
  558. [%collapsible]
  559. ====
  560. *Details* +
  561. The {ref}/create-stored-script-api.html[create or update stored script API]'s
  562. `code` parameter has been removed. Use the `source` parameter instead.
  563. *Impact* +
  564. Discontinue use of the `code` parameter. Requests that include the parameter
  565. will return an error.
  566. ====
  567. [[_type-search-matches-no-docs]]
  568. .Searches on the `_type` field are no longer supported.
  569. [%collapsible]
  570. ====
  571. *Details* +
  572. In 8.x, the `_type` metadata field has been removed. {es} now handles a search
  573. on the `_type` field as a search on a non-existent field. A search on a
  574. non-existent field matches no documents, regardless of the query string.
  575. In 7.x, a search for `_doc` in the `_type` field would match the same documents
  576. as a `match_all` query.
  577. *Impact* +
  578. Remove queries on the `_type` field from your search requests and search
  579. templates. Searches that include these queries may return no results.
  580. ====
  581. [[msearch-empty-line-support]]
  582. .The multi search API now parses an empty first line as action metadata in text files.
  583. [%collapsible]
  584. ====
  585. *Details* +
  586. The multi search API now parses an empty first line as empty action metadata
  587. when you provide a text file as the request body, such as when using curl's
  588. `--data-binary` flag.
  589. The API no longer supports text files that contain:
  590. * An empty first line followed by a line containing only `{}`.
  591. * An empty first line followed by another empty line.
  592. *Impact* +
  593. Don't provide an unsupported text file to the multi search API. Requests that
  594. include an unsupported file will return an error.
  595. ====
  596. [[remove-unmapped-type-string]]
  597. .The `unmapped_type: string` sort option has been removed.
  598. [%collapsible]
  599. ====
  600. *Details* +
  601. Search requests no longer support the `unmapped_type: string` sort option.
  602. Instead, use `unmapped_type: keyword` to handle an unmapped field as if it had
  603. the `keyword` field type but ignore its values for sorting.
  604. *Impact* +
  605. Discontinue use of `unmapped_type: string`. Search requests that include the
  606. `unmapped_type: string` sort option will return shard failures.
  607. ====
  608. [[id-field-data]]
  609. .Aggregating and sorting on `_id` is disallowed by default.
  610. [%collapsible]
  611. ====
  612. *Details* +
  613. Previously, it was possible to aggregate and sort on the built-in `_id` field
  614. by loading an expensive data structure called fielddata. This was deprecated
  615. in 7.6 and is now disallowed by default in 8.0.
  616. *Impact* +
  617. Aggregating and sorting on `_id` should be avoided. As an alternative, the
  618. `_id` field's contents can be duplicated into another field with docvalues
  619. enabled (note that this does not apply to auto-generated IDs).
  620. ====
  621. .The `common` query has been removed.
  622. [%collapsible]
  623. ====
  624. *Details* +
  625. The `common` query, deprecated in 7.x, has been removed in 8.0.
  626. The same functionality can be achieved by the `match` query if the total number of hits is not tracked.
  627. *Impact* +
  628. Discontinue use of the `common` query. Search requests containing a `common`
  629. query will return an error.
  630. ====
  631. .The `cutoff_frequency` parameter has been removed from the `match` and `multi_match` query.
  632. [%collapsible]
  633. ====
  634. *Details* +
  635. The `cutoff_frequency` parameter, deprecated in 7.x, has been removed in 8.0 from `match` and `multi_match` queries.
  636. The same functionality can be achieved without any configuration provided that the total number of hits is not tracked.
  637. *Impact* +
  638. Discontinue use of the `cutoff_frequency` parameter. Search requests containing
  639. this parameter in a `match` or `multi_match` query will return an error.
  640. ====
  641. .The `nested_filter` and `nested_path` properties have been removed from the search API's `sort` request body parameter.
  642. [%collapsible]
  643. ====
  644. *Details* +
  645. The `nested_filter` and `nested_path` options, deprecated in 6.x, have been removed in favor of the `nested` context.
  646. *Impact* +
  647. Discontinue use of the `sort` request body parameter's `nested_filter` and
  648. `nested_path` properties. Requests containing these properties will return an
  649. error.
  650. ====
  651. .Search and get requests are now routed to shards using adaptive replica selection by default.
  652. [%collapsible]
  653. ====
  654. *Details* +
  655. {es} will no longer prefer using shards in the same location (with the same awareness attribute values) to process
  656. `_search` and `_get` requests. Adaptive replica selection (activated by default in this version) will route requests
  657. more efficiently using the service time of prior inter-node communications.
  658. *Impact* +
  659. No action needed.
  660. ====
  661. .Vector functions using `(query, doc['field'])` are no longer supported.
  662. [%collapsible]
  663. ====
  664. *Details* +
  665. The vector functions of the form `function(query, doc['field'])` were
  666. deprecated in 7.6, and are now removed in 8.x. The form
  667. `function(query, 'field')` should be used instead. For example,
  668. `cosineSimilarity(query, doc['field'])` is replaced by
  669. `cosineSimilarity(query, 'field')`.
  670. *Impact* +
  671. Use the `function(query, 'field')` form. Discontinue use of the `function(query,
  672. doc['field'])` form. Requests containing the `function(query,
  673. doc['field'])` form will return an error.
  674. ====
  675. .The search API's `indices_boost` request body parameter no longer accepts object values.
  676. [%collapsible]
  677. ====
  678. *Details* +
  679. The `indices_boost` option in the search request used to accept the boosts
  680. both as an object and as an array. The object format has been deprecated since
  681. 5.2 and is now removed in 8.0.
  682. *Impact* +
  683. Use only array values in the `indices_boost` parameter. Requests containing an
  684. object value in the `indices_boost` parameter will return an error.
  685. ====
  686. .The search API's `use_field_mapping` request body parameter has been removed.
  687. [%collapsible]
  688. ====
  689. *Details* +
  690. In 7.0, we began formatting `docvalue_fields` by default using each field's
  691. mapping definition. To ease the transition from 6.x, we added the format
  692. option `use_field_mapping`. This parameter was deprecated in 7.0, and is now
  693. removed in 8.0.
  694. *Impact* +
  695. Discontinue use of the `use_field_mapping` request body parameter. Requests
  696. containing this parameter will return an error.
  697. ====
  698. .The search API's `from` request body and url parameter cannot be negative.
  699. [%collapsible]
  700. ====
  701. *Details* +
  702. Search request used to accept `-1` as a `from` in the search body and the url,
  703. treating it as the default value of 0. Other negative values got rejected with
  704. an error already. We now also reject `-1` as an invalid value.
  705. *Impact* +
  706. Change any use of `-1` as `from` parameter in request body or url parameters by either
  707. setting it to `0` or omitting it entirely. Requests containing negative values will
  708. return an error.
  709. ====
  710. .Range queries on date fields treat numeric values alwas as milliseconds-since-epoch.
  711. [%collapsible]
  712. ====
  713. *Details* +
  714. Range queries on date fields used to misinterpret small numbers (e.g. four digits like 1000)
  715. as a year when no additional format was set, but would interpret other numeric values as
  716. milliseconds since epoch. We now treat all numeric values in absence of a specific `format`
  717. parameter as milliseconds since epoch. If you want to query for years instead, with a missing
  718. `format` you now need to quote the input value (e.g. "1984").
  719. *Impact* +
  720. If you query date fields without a specified `format`, check if the values in your queries are
  721. actually meant to be milliseconds-since-epoch and use a numeric value in this case. If not, use
  722. a string value which gets parsed by either the date format set on the field in the mappings or
  723. by `strict_date_optional_time` by default.
  724. ====
  725. .The `geo_bounding_box` query's `type` parameter has been removed.
  726. [%collapsible]
  727. ====
  728. *Details* +
  729. The `geo_bounding_box` query's `type` parameter was deprecated in 7.14.0 and has
  730. been removed in 8.0.0. This parameter is a no-op and has no effect on the query.
  731. *Impact* +
  732. Discontinue use of the `type` parameter. `geo_bounding_box` queries that include
  733. this parameter will return an error.
  734. ====
  735. .The `type` query has been removed.
  736. [%collapsible]
  737. ====
  738. *Details* +
  739. The `type` query has been removed. Mapping types have been removed in 8.0.
  740. *Impact* +
  741. Discontinue use of the `type` query. Requests that include the `type` query
  742. will return an error.
  743. ====
  744. .The `kibana_user` role has been renamed `kibana_admin`.
  745. [%collapsible]
  746. ====
  747. *Details* +
  748. Users who were previously assigned the `kibana_user` role should instead be assigned
  749. the `kibana_admin` role. This role grants the same set of privileges as `kibana_user`, but has been
  750. renamed to better reflect its intended use.
  751. *Impact* +
  752. Assign users with the `kibana_user` role to the `kibana_admin` role.
  753. Discontinue use of the `kibana_user` role.
  754. ====
  755. [[snapshot-resolve-system-indices]]
  756. .For snapshot and {slm-init} APIs, the `indices` parameter no longer resolves to system indices or system data streams.
  757. [%collapsible]
  758. ====
  759. *Details* +
  760. For snapshot and {slm-init} APIs, the `indices` parameter no longer resolves to
  761. system indices or system data streams.
  762. {ref}/snapshot-restore.html#feature-state[Feature states] are now the only way
  763. to back up and restore system indices or system data streams from a snapshot.
  764. You can no longer use the `indices` parameter for the
  765. {ref}/slm-api-put-policy.html[create {slm-init} policy API] or the
  766. {ref}/create-snapshot-api.html[create snapshot API] to include a system index in
  767. a snapshot. To back up a system index, use the `include_global_state` and
  768. `feature_states` parameters to include the corresponding feature state instead.
  769. By default, the `include_global_state` and `feature_states` parameters include
  770. all system indices.
  771. Similarly, you can no longer use the {ref}/restore-snapshot-api.html[restore snapshot
  772. API]'s `indices` parameter to restore a system index from a snapshot. To restore
  773. a system index, use the `include_global_state` and `feature_states` parameters
  774. to restore the corresponding feature state instead. By default, the
  775. `include_global_state` and `feature_states` parameters don't restore any system
  776. indices.
  777. *Impact* +
  778. If you previously used the `indices` parameter to back up or restore system
  779. indices, update your {slm-init} policies and application to use the
  780. `include_global_state` and `feature_states` parameters instead.
  781. An {slm-init} policy that explicitly specifies a system index in the `indices`
  782. parameter will fail to create snapshots. Similarly, a create snapshot API or
  783. restore snapshot API request that explicitly specifies a system index in the
  784. `indices` parameter will fail and return an error. If the `indices` value
  785. includes a wildcard (`*`) pattern, the pattern will no longer match system
  786. indices.
  787. ====
  788. .Snapshots compress metadata files by default.
  789. [%collapsible]
  790. ====
  791. *Details* +
  792. Previously, the default value for `compress` was `false`. The default has been changed to `true`.
  793. This change will affect both newly created repositories and existing repositories where `compress=false` has not been
  794. explicitly specified.
  795. For more information on the compress option, see
  796. {ref}/snapshots-register-repository.html[Register a snapshot repository].
  797. *Impact* +
  798. Update your workflow and applications to assume a default value of `true` for
  799. the `compress` parameter.
  800. ====
  801. .The S3 repository plugin now uses a DNS-style access pattern by default.
  802. [%collapsible]
  803. ====
  804. *Details* +
  805. Starting in version 7.4 the `repository-s3` plugin does not use the
  806. now-deprecated path-style access pattern by default. In versions 7.0, 7.1, 7.2
  807. and 7.3 the `repository-s3` plugin always used the path-style access pattern.
  808. This is a breaking change for deployments that only support path-style access
  809. but which are recognized as supporting DNS-style access by the AWS SDK. This
  810. breaking change was made necessary by
  811. https://aws.amazon.com/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/[AWS's
  812. announcement] that the path-style access pattern is deprecated and will be
  813. unsupported on buckets created after September 30th 2020.
  814. *Impact* +
  815. If your deployment only supports path-style access and is affected by this
  816. change then you must configure the S3 client setting `path_style_access` to
  817. `true`.
  818. ====
  819. .Restore requests no longer accept settings.
  820. [%collapsible]
  821. ====
  822. *Details* +
  823. In earlier versions, you could pass both `settings` and `index_settings` in the
  824. body of a restore snapshot request, but the `settings` value was ignored. The
  825. restore snapshot API now rejects requests that include a `settings` value.
  826. *Impact* +
  827. Discontinue use of the `settings` parameter in restore
  828. snapshot request. Requests that include these parameters will return an error.
  829. ====
  830. .The repository stats API has been removed.
  831. [%collapsible]
  832. ====
  833. *Details* +
  834. The repository stats API has been removed. We deprecated this experimental API
  835. in 7.10.0.
  836. *Impact* +
  837. Use the {ref}/repositories-metering-apis.html[repositories metering APIs]
  838. instead.
  839. ====
  840. .Watcher history now writes to a hidden data stream.
  841. [%collapsible]
  842. ====
  843. *Details* +
  844. In 8.x, {es} writes Watcher history to a hidden
  845. `.watcher-history-<index-template-version>` data stream. Previously, {es} wrote
  846. Watcher history to hidden
  847. `.watcher-history-<index-template-version>-<yyyy-MM-dd>` indices.
  848. *Impact* +
  849. Update your requests to target the Watcher history data stream. For example, use
  850. the `.watcher-history-*` wildcard expression. Requests that specifically target
  851. non-existent Watcher history indices may return an error.
  852. ====
  853. .HTTP Status code has changed for the Cluster Health API in case of a server timeout.
  854. [%collapsible]
  855. ====
  856. *Details* +
  857. The {ref}/cluster-health.html[cluster health API] includes options for waiting
  858. for certain health conditions to be satisfied. If the requested conditions are
  859. not satisfied within a timeout then {es} will send back a normal response
  860. including the field `"timed_out": true`. In earlier versions it would also use
  861. the HTTP response code `408 Request timeout` if the request timed out, and `200
  862. OK` otherwise. The `408 Request timeout` response code is not appropriate for
  863. this situation, so from version 8.0.0 {es} will use the response code `200 OK`
  864. for both cases.
  865. *Impact* +
  866. To detect a server timeout, check the `timed_out` field of the JSON response.
  867. ====
  868. //end::notable-breaking-changes[]