elasticsearch/docs/reference/migration/migrate_8_1.asciidoc

[[migrating-8.1]]
== Migrating to 8.1
++++
<titleabbrev>8.1</titleabbrev>
++++

This section discusses the changes that you need to be aware of when migrating
your application to {es} 8.1.

See also <<release-highlights>> and <<es-release-notes>>.

coming[8.1.0]

[discrete]
[[breaking-changes-8.1]]
=== Breaking changes

The following changes in {es} 8.1 might affect your applications
and prevent them from operating normally.
Before upgrading to 8.1, review these changes and take the described steps
to mitigate the impact.

NOTE: Breaking changes introduced in minor versions are
normally limited to security and bug fixes.
Significant changes in behavior are deprecated in a minor release and
the old behavior is supported until the next major release.
To find out if you are using any deprecated functionality,
enable <<deprecation-logging, deprecation logging>>.

//NOTE: The notable-breaking-changes tagged regions are re-used in the
//Installation and Upgrade Guide

//tag::notable-breaking-changes[]
[discrete]
[[breaking_81_rest_api_changes]]
==== REST API changes

[[fields_api_geoshape_normalize]]
.The search API's `fields` parameter now normalizes geometry objects that cross the international dateline.
[%collapsible]
====
*Details* +
The search API's `fields` parameter now normalizes `geo_shape` objects that
cross the international dateline (+/-180° longitude). For example, if a polygon
crosses the dateline, the `fields` parameter returns it as two polygons. You can
still retrieve original, unnormalized geometry objects from `_source`.

*Impact* +
If your application requires unnormalized geometry objects, retrieve them from
`_source` rather than using the `fields` parameter.
====
//end::notable-breaking-changes[]

[discrete]
[[deprecated-8.1]]
=== Deprecations

The following functionality has been deprecated in {es} 8.1
and will be removed in a future version.
While this won't have an immediate impact on your applications,
we strongly encourage you take the described steps to update your code
after upgrading to 8.1.

NOTE: Significant changes in behavior are deprecated in a minor release and
the old behavior is supported until the next major release.
To find out if you are using any deprecated functionality,
enable <<deprecation-logging, deprecation logging>>.

//tag::notable-breaking-changes[]
[discrete]
[[breaking_8.1_cluster_node_setting_deprecations]]
==== Cluster and node setting deprecations

[[deprecate-legacy-discovery-type-setting]]
.Legacy values for the `discovery.type` setting are deprecated.
[%collapsible]
====
*Details* +
Legacy values for the `discovery.type` setting are deprecated and will be
forbidden in a future version.

*Impact* +
Do not set `discovery.type` to any value except `single-node` or `multi-node`.
All other values are equivalent to the default discovery type which is
`multi-node`. Where possible, omit this setting so that {es} uses the default
discovery type.
====

[discrete]
[[breaking_8.1_rest_api_deprecations]]
==== REST API deprecations

[[deprecate-lenient-parsing-of-bulk-actions]]
.Lenient parsing of bulk actions is deprecated.
[%collapsible]
====
*Details* +
Older versions of {es} parse the action lines of bulk requests very permissively
and would silently ignore invalid or malformed actions. This lenience is
deprecated and a future version will reject bulk requests containing invalid
actions.

*Impact* +
Ensure that bulk actions are well-formed JSON objects containing a single entry
with the correct key.
====
//end::notable-breaking-changes[]