Upgrading from 3.2.x to 4.0.x

  • 取消 Jackson 映射器的使用，转而采用基于元模型的转换器。

  • 取消查询对象中隐式索引名称，索引名称必须明确指定。

  • 分拆 ElasticsearchOperations 接口为 DocumentOperations、SearchOperations 和 IndexOperations。

  • 弃用许多函数和类，建议使用替代方案。

  • 删除 ElasticsearchEntityMapper 接口和 SearchQuery 接口。

  • 取消 Elasticsearch 低级滚动 API 的 startScroll、continueScroll 和 clearScroll 方法。

本节介绍从 3.2.x 版到 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.

Removal of the used Jackson Mapper

版本 4.0.x 中的一项更改是 Spring Data Elasticsearch 不再使用 Jackson 映射器将实体映射到 Elasticsearch 所需的 JSON 表示（请参见 Elasticsearch Object Mapping）。在版本 3.2.x 中，Jackson 映射器是默认使用的映射器。可以通过显式配置它（Meta Model Object Mapping）来切换到基于元模型的转换器（名为 ElasticsearchEntityMapper）。

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 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 (Meta Model Object Mapping).

在 4.0.x 版中，基于元模型的转换器是唯一可用的转换器，并且不需要显式配置。如果您有自定义配置，可以使用如下 bean 启用元模型转换器：

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:

@Bean
@Override
public EntityMapper entityMapper() {

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

  return entityMapper;
}

现在您必须删除此 bean，ElasticsearchEntityMapper 接口已删除。

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

Entity configuration

一些用户在实体类上具有自定义 Jackson 注解，例如，为了定义 Elasticsearch 中映射文档的自定义名称或配置日期转换。现在不再考虑这些问题。所需的功能现在由 Spring Data Elasticsearch 的 `@Field`注解提供。有关详细信息，请参见 Mapping Annotation Overview。

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 Mapping Annotation Overview for detailed information.

Removal of implicit index name from query objects

在 3.2.x 中，诸如 IndexQuery 或 SearchQuery 之类的不同查询类具有接受索引名称或它们正在操作的索引名称的属性。如果未设置这些属性，则检查传入的实体以检索在 @Document 注释中设置的索引名称。在 4.0.x 中，索引名称现在必须在类型为 IndexCoordinates 的其他参数中提供。通过将这部分内容分离开，现在可以使用一个查询对象针对不同的索引。

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:

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

String documentId = elasticsearchOperations.index(indexQuery);

必须更改为：

must be changed to:

IndexCoordinates indexCoordinates = elasticsearchOperations.getIndexCoordinatesFor(person.getClass());

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

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

为了更加轻松地处理实体和使用实体的 @Document 注释中包含的索引名称，已添加了类似于 DocumentOperations.save(T entity) 的新方法；

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);

The new Operations interfaces

在 3.2 版中，ElasticsearchOperations 接口定义了 ElasticsearchTemplate 类的所有方法。在第 4 版中，这些函数已拆分为不同的接口，将这些接口与 Elasticsearch API 对齐：

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 现在扩展 DocumentOperations 和 SearchOperations，并具有获取对 IndexOperations 实例的访问的方法。

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

3.2 版本中 ElasticsearchOperations 接口中的所有函数现在都已移至 IndexOperations 接口中，这些函数仍然可用，它们被标记为已弃用，并具有委派给新实现的默认实现：

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:

 
/**
 * 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();
}

Deprecations

Methods and classes

许多函数和类已被弃用。这些函数仍可正常工作，但 Javadoc 却显示应该用什么替换它们。

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

Example from ElasticsearchOperations
/*
 * 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 deprecations

自第 7 版以来，Elasticsearch TransportClient 已被弃用，它将在 Elasticsearch 第 8 版中删除。Spring Data Elasticsearch 在第 4.0 版中弃用了使用 TransportClient 的 ElasticsearchTemplate 类。

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.

映射类型已从 Elasticsearch 7 中删除，它们仍作为 Spring Data @Document 注释和 IndexCoordinates 类中的弃用值存在，但不再在内部使用它们。

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.

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