[[elasticsearch-migration-guide-3.2-4.0]]
= Upgrading from 3.2.x to 4.0.x

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

[[elasticsearch-migration-guide-3.2-4.0.jackson-removal]]
== Removal of the used Jackson Mapper

One of the changes in version 4.0.x is that Spring Data Elasticsearch does not use the Jackson Mapper anymore to map an entity to the JSON representation needed for Elasticsearch (see xref:elasticsearch/object-mapping.adoc[Elasticsearch Object Mapping]).
In version 3.2.x the Jackson Mapper was the default that was used.
It was possible to switch to the meta-model based converter (named `ElasticsearchEntityMapper`) by explicitly configuring it (xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model[Meta Model Object Mapping]).

In version 4.0.x the meta-model based converter is the only one that is available and does not need to be configured explicitly.
If you had a custom configuration to enable the meta-model converter by providing a bean like this:

[source,java]
----
@Bean
@Override
public EntityMapper entityMapper() {

  ElasticsearchEntityMapper entityMapper = new ElasticsearchEntityMapper(
    elasticsearchMappingContext(), new DefaultConversionService()
  );
  entityMapper.setConversions(elasticsearchCustomConversions());

  return entityMapper;
}
----

You now have to remove this bean, the `ElasticsearchEntityMapper` interface has been removed.

.Entity configuration
Some users had custom Jackson annotations on the entity class, for example in order to define a custom name for the mapped document in Elasticsearch or to configure date conversions.
These are not taken into account anymore.
The needed functionality is now provided with Spring Data Elasticsearch's `@Field` annotation.
Please see xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model.annotations[Mapping Annotation Overview] for detailed information.

[[elasticsearch-migration-guide-3.2-4.0.implicit-index-name]]
== Removal of implicit index name from query objects

In 3.2.x the different query classes like `IndexQuery` or `SearchQuery` had properties that were taking the index name or index names that they were operating upon.If these were not set, the passed in entity was inspected to retrieve the index name that was set in the `@Document` annotation. +
In 4.0.x the index name(s) must now be provided in an additional parameter of type `IndexCoordinates`.By separating this, it now is possible to use one query object against different indices.

So for example the following code:

[source,java]
----
IndexQuery indexQuery = new IndexQueryBuilder()
  .withId(person.getId().toString())
  .withObject(person)
  .build();

String documentId = elasticsearchOperations.index(indexQuery);
----

must be changed to:

[source,java]
----
IndexCoordinates indexCoordinates = elasticsearchOperations.getIndexCoordinatesFor(person.getClass());

IndexQuery indexQuery = new IndexQueryBuilder()
  .withId(person.getId().toString())
  .withObject(person)
  .build();

String documentId = elasticsearchOperations.index(indexQuery, indexCoordinates);
----

To make it easier to work with entities and use the index name that is contained in the entitie's `@Document` annotation, new methods have been added like `DocumentOperations.save(T entity)`;

[[elasticsearch-migration-guide-3.2-4.0.new-operations]]
== The new Operations interfaces

In version 3.2 there was the `ElasticsearchOperations` interface that defined all the methods for the `ElasticsearchTemplate` class. In version 4 the functions have been split into different interfaces, aligning these interfaces with the Elasticsearch API:

* `DocumentOperations` are the functions related documents like saving, or deleting
* `SearchOperations` contains the functions to search in Elasticsearch
* `IndexOperations` define the functions to operate on indexes, like index creation or mappings creation.

`ElasticsearchOperations` now extends `DocumentOperations` and `SearchOperations` and has methods get access to an `IndexOperations` instance.

NOTE: All the functions from the `ElasticsearchOperations` interface in version 3.2 that are now moved to the `IndexOperations` interface are still available, they are marked as deprecated and have default implementations that delegate to the new implementation:

[source,java]
----
/**
 * Create an index for given indexName.
 *
 * @param indexName the name of the index
 * @return {@literal true} if the index was created
 * @deprecated since 4.0, use {@link IndexOperations#create()}
 */
@Deprecated
default boolean createIndex(String indexName) {
	return indexOps(IndexCoordinates.of(indexName)).create();
}
----

[[elasticsearch-migration-guide-3.2-4.0.deprecations]]
== Deprecations

[[elasticsearch-migration-guide-3.2-4.0.deprecations.methods-classes]]
=== Methods and classes

Many functions and classes have been deprecated. These functions still work, but the Javadocs show with what they should be replaced.

.Example from ElasticsearchOperations
[source,java]
----
/*
 * Retrieves an object from an index.
 *
 * @param query the query defining the id of the object to get
 * @param clazz the type of the object to be returned
 * @return the found object
 * @deprecated since 4.0, use {@link #get(String, Class, IndexCoordinates)}
 */
@Deprecated
@Nullable
<T> T queryForObject(GetQuery query, Class<T> clazz);
----

[[elasticsearch-migration-guide-3.2-4.0.deprecations.elasticsearch]]
=== Elasticsearch deprecations

Since version 7 the Elasticsearch `TransportClient` is deprecated, it will be removed with Elasticsearch version 8. Spring Data Elasticsearch deprecates the `ElasticsearchTemplate` class which uses the `TransportClient` in version 4.0.

Mapping types were removed from Elasticsearch 7, they still exist as deprecated values in the Spring Data `@Document` annotation and the `IndexCoordinates` class but they are not used anymore internally.

[[elasticsearch-migration-guide-3.2-4.0.removal]]
== Removals

* As already described, the `ElasticsearchEntityMapper` interface has been removed.

* The `SearchQuery` interface has been merged into it's base interface `Query`, so it's occurrences can just be replaced with `Query`.

* The method `org.springframework.data.elasticsearch.core.ElasticsearchOperations.query(SearchQuery query, ResultsExtractor<T> resultsExtractor);` and the `org.springframework.data.elasticsearch.core.ResultsExtractor` interface have been removed.
These could be used to parse the result from Elasticsearch for cases in which the response mapping done with the Jackson based mapper was not enough.
Since version 4.0, there are the new xref:elasticsearch/template.adoc#elasticsearch.operations.searchresulttypes[Search Result Types]  to return the information from an Elasticsearch response, so there is no need to expose this low level functionality.

* The low level methods `startScroll`, `continueScroll` and `clearScroll` have been removed from the `ElasticsearchOperations` interface.
For low level scroll API access, there now are `searchScrollStart`, `searchScrollContinue` and `searchScrollClear` methods on the `ElasticsearchRestTemplate` class.
