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


[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: 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

[[search_apis_fields_parameter_normalizes_geometry_objects_cross_international_dateline]]
.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.

To find out if you are using any deprecated functionality,
enable <<deprecation-logging, deprecation logging>>.

// tag::notable-breaking-changes[]
[discrete]
[[deprecations_81_cluster_and_node_setting]]
==== Cluster and node setting deprecations

[[legacy_values_for_discovery_type_setting_are_deprecated]]
.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]
[[deprecations_81_rest_api]]
==== REST API deprecations

[[lenient_parsing_of_bulk_actions_deprecated]]
.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[]

[[deprecate_index_include_frozen_request_parameter_in_sql_api]]
.Deprecate `index_include_frozen` request parameter in `_sql` API
[%collapsible]
====
*Details* +
Following the deprecation of frozen indices, the `index_include_frozen`
parameter and `FROZEN` syntax is now also deprecated.

*Impact* +
You should unfreeze frozen indices using the
{ref}/unfreeze-index-api.html[unfreeze index API] and stop using the
`index_include_frozen` parameter or the `FROZEN` keyword in SQL
queries. For some use cases, the frozen tier may be a suitable
replacement for frozen indices. See {ref}/data-tiers.html[data tiers]
for more information.
====