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

=== `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-5.0.breaking-changes]]
== Breaking Changes

=== Removal of deprecated calls

==== 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.new-clients]]
== New Elasticsearch client

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

=== 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`

=== 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.4</version>
	<exclusions>
		<exclusion>
			<groupId>commons-logging</groupId>
			<artifactId>commons-logging</artifactId>
		</exclusion>
	</exclusions>
</dependency>
----
====

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