Upgrading from 4.2.x to 4.3.x

  • 替换 RestHighLevelClient 以满足许可证要求。

  • 移除了或替换了 org.elasticsearch 包中的类，仅在实现层使用。

  • 弃用了建议方法，取而代之的是使用本地搜索查询和 Mono 返回值。

  • 更改了某些枚举、属性类型、方法返回类型、错误处理和其他类名。

  • 修复了字段和源筛选器属性的处理问题，并更改了 search_type 的默认值。

  • 更改了 BulkOptions 和 IndicesOptions 属性的类型，并移动了完成类。

本节介绍 4.2.x 到 4.3.x 版本的重大变动，以及如何使用新引入的功能替换移除的功能。

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

Elasticsearch 正在使用新的客户端来替换 RestHighLevelClient，因为 RestHighLevelClient 使用 Elasticsearch 核心库中的代码，而这些代码不再使用 Apache 2 许可。Spring Data Elasticsearch 也在为此更改做准备。这意味着 *Operations 接口的内部实现需要更改——如果用户按照 ElasticsearchOperations 或 ReactiveElasticsearchOperations 等接口进行编程，这应该不成问题。如果您直接使用 ElasticsearchRestTemplate 等实现类，则需要适应这些更改。

Elasticsearch is working on a new Client that will replace the RestHighLevelClient because the RestHighLevelClient uses code from Elasticsearch core libraries which are not Apache 2 licensed anymore. Spring Data Elasticsearch is preparing for this change as well. This means that internally the implementations for the *Operations interfaces need to change - which should be no problem if users program against the interfaces like ElasticsearchOperations or ReactiveElasticsearchOperations. If you are using the implementation classes like ElasticsearchRestTemplate directly, you will need to adapt to these changes.

Spring Data Elasticsearch 还移除了或替换了在其 API 类和方法中的 org.elasticsearch 包中类的使用，仅在实现 Elasticsearch 访问的实现中使用它们。对用户来说，这意味着一些使用的枚举类已被 org.springframework.data.elasticsearch 中具有相同值的新枚举类替换，这些类在内部映射到 Elasticsearch 枚举类中。

Spring Data Elasticsearch also removes or replaces the use of classes from the org.elasticsearch packages in it’s API classes and methods, only using them in the implementation where the access to Elasticsearch is implemented. For the user that means, that some enum classes that were used are replaced by enums that live in org.springframework.data.elasticsearch with the same values, these are internally mapped onto the Elasticsearch ones.

在无法轻松替换使用类的场合，会被标记为不推荐使用，我们正在致力于替换。

Places where classes are used that cannot easily be replaced, this usage is marked as deprecated, we are working on replacements.

查看 和 一节了解更多详细信息。

Check the sections on Deprecations and Breaking Changes for further details.

Deprecations

suggest methods

在 SearchOperations 中，以及 ElasticsearchOperations 中，将 org.elasticsearch.search.suggest.SuggestBuilder 作为参数并返回 org.elasticsearch.action.search.SearchResponse 的 suggest 方法已被弃用。请改用 SearchHits<T> search(Query query, Class<T> clazz)，传入一个 NativeSearchQuery，它可以包含一个 SuggestBuilder 并从返回的 SearchHit<T> 中读取建议结果。

In SearchOperations, and so in ElasticsearchOperations as well, the suggest methods taking a org.elasticsearch.search.suggest.SuggestBuilder as argument and returning a org.elasticsearch.action.search.SearchResponse have been deprecated. Use SearchHits<T> search(Query query, Class<T> clazz) instead, passing in a NativeSearchQuery which can contain a SuggestBuilder and read the suggest results from the returned SearchHit<T>.

在 ReactiveSearchOperations 中，新的 suggest 方法现在返回一个 Mono<org.springframework.data.elasticsearch.core.suggest.response.Suggest>。这里旧方法也被弃用。

In ReactiveSearchOperations the new suggest methods return a Mono<org.springframework.data.elasticsearch.core.suggest.response.Suggest> now. Here as well the old methods are deprecated.

Breaking Changes

Removal of org.elasticsearch classes from the API.

  • In the org.springframework.data.elasticsearch.annotations.CompletionContext annotation the property type() has changed from org.elasticsearch.search.suggest.completion.context.ContextMapping.Type to org.springframework.data.elasticsearch.annotations.CompletionContext.ContextMappingType, the available enum values are the same.

  • In the org.springframework.data.elasticsearch.annotations.Document annotation the versionType() property has changed to org.springframework.data.elasticsearch.annotations.Document.VersionType, the available enum values are the same.

  • In the org.springframework.data.elasticsearch.core.query.Query interface the searchType() property has changed to org.springframework.data.elasticsearch.core.query.Query.SearchType, the available enum values are the same.

  • In the org.springframework.data.elasticsearch.core.query.Query interface the return value of timeout() was changed to java.time.Duration.

  • The SearchHits<T>`class does not contain the `org.elasticsearch.search.aggregations.Aggregations anymore. Instead it now contains an instance of the org.springframework.data.elasticsearch.core.AggregationsContainer<T> class where T is the concrete aggregations type from the underlying client that is used. Currently this will be a org .springframework.data.elasticsearch.core.clients.elasticsearch7.ElasticsearchAggregations object; later different implementations will be available. The same change has been done to the ReactiveSearchOperations.aggregate() functions, the now return a Flux<AggregationContainer<?>>. Programs using the aggregations need to be changed to cast the returned value to the appropriate class to further proces it.

  • methods that might have thrown a org.elasticsearch.ElasticsearchStatusException now will throw org.springframework.data.elasticsearch.RestStatusException instead.

Handling of field and sourceFilter properties of Query

在 4.2 版中，Query 的 fields 属性已被解释并添加到 sourceFilter 的包含列表中。这是不正确的，因为对于 Elasticsearch 来说，这两个是不同的东西。此问题现已更正。因此，依赖使用 fields 来指定应从文档的 _source' and should be changed to use the `sourceFilter 中返回哪些字段的代码可能不再运行。

Up to version 4.2 the fields property of a Query was interpreted and added to the include list of the sourceFilter. This was not correct, as these are different things for Elasticsearch. This has been corrected. As a consequence code might not work anymore that relies on using fields to specify which fields should be returned from the document’s _source' and should be changed to use the `sourceFilter.

search_type default value

Elasticsearch 中 search_type 的默认值是 query_then_fetch。这也已作为 Query 实现的默认值进行设置，此前设置为 dfs_query_then_fetch。

The default value for the search_type in Elasticsearch is query_then_fetch. This now is also set as default value in the Query implementations, it was previously set to dfs_query_then_fetch.

BulkOptions changes

org.springframework.data.elasticsearch.core.query.BulkOptions 类的某些属性已更改其类型：

Some properties of the org.springframework.data.elasticsearch.core.query.BulkOptions class have changed their type:

  • the type of the timeout property has been changed to java.time.Duration.

  • the type of the`refreshPolicy` property has been changed to org.springframework.data.elasticsearch.core.RefreshPolicy.

IndicesOptions change

Spring Data Elasticsearch 现在使用 org.springframework.data.elasticsearch.core.query.IndicesOptions 而不是 org.elasticsearch.action.support.IndicesOptions。

Spring Data Elasticsearch now uses org.springframework.data.elasticsearch.core.query.IndicesOptions instead of org.elasticsearch.action.support.IndicesOptions.

Completion classes

包 org.springframework.data.elasticsearch.core.completion 中的类已移至 org.springframework.data.elasticsearch.core.suggest。

The classes from the package org.springframework.data.elasticsearch.core.completion have been moved to org.springframework.data.elasticsearch.core.suggest.

Other renamings

org.springframework.data.elasticsearch.core.mapping.ElasticsearchPersistentPropertyConverter 接口已重命名为 org.springframework.data.elasticsearch.core.mapping.PropertyValueConverter。同样，名为 XXPersistentPropertyConverter 的实现类已重命名为 XXPropertyValueConverter。

The org.springframework.data.elasticsearch.core.mapping.ElasticsearchPersistentPropertyConverter interface has been renamed to org.springframework.data.elasticsearch.core.mapping.PropertyValueConverter. Likewise the implementations classes named XXPersistentPropertyConverter have been renamed to XXPropertyValueConverter.