spring-data-elasticsearch/src/main/asciidoc/reference/elasticsearch-migration-guide-4.4-5.0.adoc

[[elasticsearch-migration-guide-4.4-5.0]]
= Upgrading from 4.4.x to 5.0.x

This section describes breaking changes from version 4.4.x to 5.0.x and how removed features can be replaced by new introduced features.

[[elasticsearch-migration-guide-4.4-4.5.deprecations]]
== Deprecations

=== Custom trace level logging

Logging by setting the property `logging.level.org.springframework.data.elasticsearch.client.WIRE=trace` is 
deprecated now, the Elasticsearch `RestClient` provides a better solution that can be activated by setting the 
logging level of the `tracer` package to "trace".

[[elasticsearch-migration-guide-4.4-4.5.deprecations.package]]
=== `org.springframework.data.elasticsearch.client.erhlc` package

See <<elasticsearch-migration-guide-4.4-5.0.breaking-changes-packages>>, all classes in this package have been deprecated, as the default client implementations to use are the ones based on the new Java Client from Elasticsearch, see <<elasticsearch-migration-guide-4.4-5.0.new-clients>>

[[elasticsearch-migration-guide-4.4-4.5.deprecations.code]]
=== Removal of deprecated code

`DateFormat.none` and `DateFormat.custom` had been deprecated since version 4.2 and have been removed.

The properties of `@Document` that were deprecated since 4.2 have been removed.
Use the `@Settings` annotation for these.

`@DynamicMapping` and `@DynamicMappingValue` have been removed.
Use `@Document.dynamic` or `@Field.dynamic` instead.

[[elasticsearch-migration-guide-4.4-5.0.breaking-changes]]
== Breaking Changes

[[elasticsearch-migration-guide-4.4-5.0.breaking-changes.deprecated-calls]]
=== Removal of deprecated calls

[[elasticsearch-migration-guide-4.4-5.0.breaking-changes.deprecated-calls.1]]
==== suggest calls in operations interfaces have been removed

Both `SearchOperations` and `ReactiveSearchOperations` had deprecated calls that were using Elasticsearch classes as parameters.
These now have been removed and so the dependency on Elasticsearch classes in these APIs has been cleaned.

[[elasticsearch-migration-guide-4.4-5.0.breaking-changes-packages]]
=== Package changes

All the classes that are using or depend on the deprecated Elasticsearch `RestHighLevelClient` have been moved to the package `org.springframework.data.elasticsearch.client.erhlc`.
By this change we now have a clear separation of code using the old deprecated Elasticsearch libraries, code using the new Elasticsearch client and code that is independent of the client implementation.
Also the reactive implementation that was provided up to now has been moved here, as this implementation contains code that was copied and adapted from Elasticsearch libraries.

If you are using `ElasticsearchRestTemplate` directly and not the `ElasticsearchOperations` interface you'll need to adjust your imports as well.

When working with the `NativeSearchQuery` class, you'll need to switch to the `NativeQuery` class, which can take a
`Query` instance comign from the new Elasticsearch client libraries.
You'll find plenty of examples in the test code.

[[elasticsearch-migration-guide-4.4-5.0.breaking-changes-records]]
=== Conversion to Java 17 records

The following classes have been converted to `Record`, you might need to adjust the use of getter methods from
`getProp()` to `prop()`:

* `org.springframework.data.elasticsearch.core.AbstractReactiveElasticsearchTemplate.IndexResponseMetaData`
* `org.springframework.data.elasticsearch.core.ActiveShardCount`
* `org.springframework.data.elasticsearch.support.Version`
* `org.springframework.data.elasticsearch.support.ScoreDoc`
* `org.springframework.data.elasticsearch.core.query.ScriptData`
* `org.springframework.data.elasticsearch.core.query.SeqNoPrimaryTerm`

[[elasticsearch-migration-guide-4.4-5.0.breaking-changes-http-headers]]
=== New HttpHeaders class

Until version 4.4 the client configuration used the `HttpHeaders` class from the `org.springframework:spring-web`
project.
This introduces a dependency on that artifact.
Users that do not use spring-web then face an error as this class cannot be found.

In version 5.0 we introduce our own `HttpHeaders` to configure the clients.

So if you are using headers in the client configuration, you need to replace `org.springframework.http.HttpHeaders`
with `org.springframework.data.elasticsearch.support.HttpHeaders`.

Hint: You can pass a `org.springframework.http
.HttpHeaders` to the `addAll()` method of `org.springframework.data.elasticsearch.support.HttpHeaders`.

[[elasticsearch-migration-guide-4.4-5.0.new-clients]]
== New Elasticsearch client

Spring Data Elasticsearch now uses the new `ElasticsearchClient` and has deprecated the use of the previous `RestHighLevelClient`.

[[elasticsearch-migration-guide-4.4-5.0.new-clients.imperative]]
=== Imperative style configuration

To configure Spring Data Elasticsearch to use the new client, it is necessary to create a configuration bean that derives from `org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration`:

====
[source,java]
----
@Configuration
public class NewRestClientConfig extends ElasticsearchConfiguration {

	@Override
	public ClientConfiguration clientConfiguration() {
		return ClientConfiguration.builder() //
			.connectedTo("localhost:9200") //
			.build();
	}
}
----
====

The configuration is done in the same way as with the old client, but it is not necessary anymore to create more than the configuration bean.
With this configuration, the following beans will be available in the Spring application context:

* a `RestClient` bean, that is the configured low level `RestClient` that is used by the Elasticsearch client
* an `ElasticsearchClient` bean, this is the new client that uses the `RestClient`
* an `ElasticsearchOperations` bean, available with the bean names _elasticsearchOperations_ and _elasticsearchTemplate_, this uses the `ElasticsearchClient`

[[elasticsearch-migration-guide-4.4-5.0.new-clients.reactive]]
=== Reactive style configuration

To use the new client in a reactive environment the only difference is the class from which to derive the configuration:

====
[source,java]
----
@Configuration
public class NewRestClientConfig extends ReactiveElasticsearchConfiguration {

	@Override
	public ClientConfiguration clientConfiguration() {
		return ClientConfiguration.builder() //
			.connectedTo("localhost:9200") //
			.build();
	}
}
----
====

With this configuration, the following beans will be available in the Spring application context:

* a `RestClient` bean, that is the configured low level `RestClient` that is used by the Elasticsearch client
* an `ReactiveElasticsearchClient` bean, this is the new reactive client that uses the `RestClient`
* an `ReactiveElasticsearchOperations` bean, available with the bean names _reactiveElasticsearchOperations_ and _reactiveElasticsearchTemplate_, this uses the `ReactiveElasticsearchClient`

[[elasticsearch-migration-guide-4.4-5.0.old-client]]
=== Still want to use the old client?

The old deprecated `RestHighLevelClient` can still be used, but you will need to add the dependency explicitly to your application as Spring Data Elasticsearch does not pull it in automatically anymore:

====
[source,xml]
----
<!-- include the RHLC, specify version explicitly	-->
<dependency>
	<groupId>org.elasticsearch.client</groupId>
	<artifactId>elasticsearch-rest-high-level-client</artifactId>
	<version>7.17.12</version>
	<exclusions>
		<exclusion>
			<groupId>commons-logging</groupId>
			<artifactId>commons-logging</artifactId>
		</exclusion>
	</exclusions>
</dependency>
----
====

Make sure to specify the version 7.17.12 explicitly, otherwise maven will resolve to 8.5.3, and this does not exist.