Java API改变 · Elasticsearch 5.4 中文文档

# Java API改变原文链接 : [https://www.elastic.co/guide/en/elasticsearch/reference/5.0/breaking_50_java_api_changes.html#_changes_to_query_builders](https://www.elastic.co/guide/en/elasticsearch/reference/5.0/breaking_50_java_api_changes.html#_changes_to_query_builders) 译文链接 : [http://www.apache.wiki/pages/viewpage.action?pageId=4260805](http://www.apache.wiki/pages/viewpage.action?pageId=4260805) 贡献者 : [片刻](/display/~jiangzhonglian) ## 传输客户端已移动 Java传输客户端已移至其自己的模块，可以使用以下方式引用： ``` <dependency> <groupId> org.elasticsearch.client </ groupId> <artifactId> transport </ artifactId> <version> 5.0.0 </ version> </ dependency> ``` 传输客户端现在使用以下代码段创建： ``` TransportClient client = new PreBuiltTransportClient(Settings.EMPTY) .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("host1"), 9300)) .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("host2"), 9300)); ``` 有关更多信息，请参阅[Java客户端文档](https://www.elastic.co/guide/en/elasticsearch/client/java-api/5.0/java-api.html) ## 已删除计数API 已弃用的计数api已从Java api中删除，请改用search api并将大小设置为0。以下调用 ``` client.prepareCount(indices).setQuery(query).get(); ``` 可以替换 ``` client.prepareSearch(indices).setSource(new SearchSourceBuilder().size(0).query(query)).get(); ``` ## Suggest API已删除 suggest API已从Java API中删除，在搜索 API 中使用建议选项，它已针对仅建议请求进行了优化。下面调用 ``` client.prepareSuggest(indices).addSuggestion("foo", SuggestBuilders.completionSuggestion("field").text("s")).get(); ``` 可以替换 ``` client.prepareSearch(indices).suggest(new SuggestBuilder().addSuggestion("foo", SuggestBuilders.completionSuggestion("field").text("s"))).get(); ``` ## Elasticsearch将不再检测日志实现 Elasticsearch现在使用Log4j记录日志。以前，如果Log4j不在类路径上，它会努力降级到SLF4J或Java日志记录。现在，如果没有Log4j 2 API，它将无法工作。当使用Java客户端时，log4j-over-slf4j桥应该工作。 log4j-1.2-api网桥用于仍然使用Log4j 1 API的第三方依赖项。 Elasticsearch服务器现在仅支持由log4j2.properties配置的Log4j 2，并且如果Log4j不存在，它将失败。 ## Groovy依赖在以前的Elasticsearch版本中，Groovy脚本功能依赖于org.codehaus.groovy:groovy-all 手动。除了引入Groovy语言之外，这还提供了一大套功能，在Elasticsearch中脚本不需要这些功能。除了管理这样大的依赖性的固有困难之外，这还增加了用于安全问题的表面积。这种依赖已经减少到核心Groovy语言org.codehaus.groovy:groovy 手动。 ## DocumentAlreadyExistsException已删除 DocumentAlreadyExistsException被删除，并且抛出VersionConflictException（具有更好的错误描述）。这将影响使用IndexRequest.opType() 或IndexRequest.create() 来对文档进行索引的代码（如果它不存在）。 ## writeConsistencyLevel在写请求时删除在以前的Elasticsearch版本中，各种写入请求都有setWriteConsistencyLevel方法来设置写入操作的分片一致性级别。然而，写一致性的语义是不明确的，因为这只是一个操作前检查，以确保在操作开始之前指定数量的分片可用。写一致性级别不保证在操作完成时将数据复制到这些数量的副本。这些写请求的setWriteConsistencyLevel方法已更改为setWaitForActiveShards，它可以获取所有分片副本的分片副本或ActiveShardCount.ALL的总数。默认值是在继续操作之前等待主分片处于活动状态。有关更多详细信息，请参阅有关[等待活动碎片](https://www.elastic.co/guide/en/elasticsearch/reference/5.0/docs-index_.html#index-wait-for-active-shards)的部分。此更改会影响IndexRequest，IndexRequestBuilder，BulkRequest，BulkRequestBuilder，UpdateRequest，UpdateRequestBuilder，DeleteRequest和DeleteRequestBuilder。 ## 查询构建器的更改 ### BoostingQueryBuilder 删除强制正/负查询的设置器。这两个参数现在必须在施工时提供，并且必须是非空的。 ### SpanContainingQueryBuilder 删除了强制性大/小内部跨度查询的设置器。这两个参数现在必须在施工时提供，并且必须是非空的。相应地更新QueryBuilders中的静态工厂方法。 ### SpanOrQueryBuilder 通过在构造函数中强制使用初始子句，确保查询至少包含一个子句。重命名方法将子句（SpanQueryBuilder）中的子句添加到addClause（SpanQueryBuilder）。 ### SpanNearQueryBuilder 删除强制性斜坡参数的setter，需要在构造函数中设置。还要确保查询包含至少一个子句，使初始子句在构造函数中是必需的。相应地更新QueryBuilders中的静态工厂方法。重命名方法将子句（SpanQueryBuilder）中的子句添加到addClause（SpanQueryBuilder）。 ### SpanNotQueryBuilder 删除强制包含/排除span查询子句的setter，需要在构造函数中设置。更新了QueryBuilders中的静态工厂方法并进行相应的测试。 ### SpanWithinQueryBuilder 删除了强制性大/小内部跨度查询的设置器。这两个参数现在必须在施工时提供，并且必须是非空的。相应地更新QueryBuilders中的静态工厂方法。 ### WrapperQueryBuilder 删除wrapperQueryBuilder（byte [] source，int offset，int length）。而只需使用wrapperQueryBuilder（byte [] source）。相应地更新QueryBuilders中的静态工厂方法。 ### QueryStringQueryBuilder 在表单中删除了使用字段（字符串字段）方法传递boost值的能力。字段^ 2。请改用字段（String，float）方法。 ### Operator 从MatchQueryBuilder，QueryStringQueryBuilder，SimpleQueryStringBuilder和CommonTermsQueryBuilder中删除了名为Operator的枚举，以便使用org.elasticsearch.index.query.Operator中定义的枚举，以便合并代码库并避免重复。 ### queryName和boost支持支持queryName和boost已经精简到所有的查询。这是一个破坏性的变化，直到查询作为序列化的json而不是Streamable格式通过网络发送。事实上，当额外的字段添加到查询的json表示时，较旧的节点在找到未知字段时可能会引发错误。 ### InnerHitsBuilder InnerHitsBuilder现在有一个专用的addParentChildInnerHits和addNestedInnerHits方法来区分嵌套与父/子文档的内部命中。此更改使类型/路径参数是必需的。 ### MatchQueryBuilder 将MatchQueryBuilder.Type和MatchQueryBuilder.ZeroTermsQuery枚举移动到MatchQuery.Type。还重用了新的Operator的枚举。 ### MoreLikeThisQueryBuilder 已移除 `MoreLikeThisQueryBuilder.Item#id(String id)`, `Item#doc(BytesReference doc)`,`Item#doc(XContentBuilder doc)`. 使用提供的构造函数。删除 MoreLikeThisQueryBuilder#addLike 赞成在建设时提供的文本和/或项目。现在使用数组而不是列表。删除 MoreLikeThisQueryBuilder#addUnlike 赞成使用不同的方法，现在取数组作为参数，而不是以前使用的列表。废弃的文档 `docs(Item... docs)`, `ignoreLike(Item... docs)`, `ignoreLike(String... likeText)`, `addItem(Item... likeItems) `已被删除。 ### GeoDistanceQueryBuilder 删除lon() 和lat() 值的各个设置器，这两个值应使用point(lon，lat) 一起设置。 ### GeoDistanceRangeQueryBuilder 为了（Object ...）和从（Object ...）移除setters，只有两个允许的输入参数（String，Number）。删除中心点的设置器（point() ，geohash() ），因为参数是必需的，并且应该已在构造函数中设置。还删除lt()，lte()，gt()，gte() 的setter，因为它们都可以被等价调用到/ from() 和inludeLower() / includeUpper() 。 ### GeoPolygonQueryBuilder 需要在构造函数中指定多边形的外壳，而不是逐点添加。这启用验证，但是需要删除addPoint() 方法。 ### MultiMatchQueryBuilder 将MultiMatchQueryBuilder.ZeroTermsQuery枚举移动到MatchQuery.ZeroTermsQuery。还重用了新的Operator的枚举。在表单中删除了使用字段（字符串字段）方法传递boost值的能力。字段^ 2。请改用字段（String，float）方法。 ### MissingQueryBuilder 已删除2.2.0中已弃用的MissingQueryBuilder。作为替代，在mustNot（）子句中使用ExistsQueryBuilder。因此，不使用新的ExistsQueryBuilder（name）现在使用新的BoolQueryBuilder() 。mustNot（new ExistsQueryBuilder（name））。 ### NotQueryBuilder 删除了在2.1.0中弃用的NotQueryBuilder。作为替换使用BoolQueryBuilder添加了mustNot（）子句。所以，而不是使用新的NotQueryBuilder（过滤器）现在使用新的BoolQueryBuilder() 。mustNot（filter）。 ### TermsQueryBuilder 删除termLookup() 的setter，使它只能在构造时使用TermsLookup对象或单个值。还将TermsLookup（lookupIndex，lookupType，lookupId，lookupPath）的各个设置移动到单独的TermsLookup类，仅使用构造函数，并在那里移动检查。已移除TermsLookupQueryBuilder以支持TermsQueryBuilder。 ### FunctionScoreQueryBuilder 添加方法已删除，所有过滤器和函数必须作为构造函数参数提供，方法是创建一个FunctionScoreQueryBuilder.FilterFunctionBuilder对象数组，每个过滤器/函数对包含一个元素。 scoreMode和boostMode只能使用相应的枚举成员而不是字符串值提供：请参阅FilterFunctionScoreQuery.ScoreMode和CombineFunction。 CombineFunction.MULT已重命名为MULTIPLY。 ### IdsQueryBuilder 为了简单起见，只剩下一种将id添加到现有列表（默认为空）的方法：addIds（String ...） ### ShapeBuilders InternalLineStringBuilder被删除赞成LineStringBuilder，InternalPolygonBuilder赞成PolygonBuilder`和Ring已经替换为LineStringBuilder。此外，抽象基类BaseLineStringBuilder和BasePolygonBuilder haven已经与它们相应的实现合并。 ### RescoreBuilder RecoreBuilder.Rescorer与RescoreBuilder合并，现在是一个抽象超类。 QueryRescoreBuilder目前是它唯一的实现。 ### PhraseSuggestionBuilder 内部DirectCandidateGenerator类已移出到其自己的类DirectCandidateGeneratorBuilder。 ### SortBuilders FieldSortBuilder，GeoDistanceSortBuilder和ScriptSortBuilder中的sortMode设置器现在接受SortMode枚举，而不是String常量。此外，getter返回相同的枚举类型。 ### SuggestBuilder setText方法已更改为setGlobalText，以使意图更清楚，并已添加了一个getGlobalText方法。 addSuggestion方法现在需要用户指定的建议名称，以前在每个建议的ctor中使用。 ### SuggestionBuilder 字段设置器已删除。相反，字段名称需要指定为构造函数参数。 ## SearchSourceBuilder 所有采用XContentBuilder，BytesReference Map <String，Object>或bytes []的方法已被删除，以便为该特征提供相关的构建器对象（例如HighlightBuilder，AggregationBuilder，SuggestBuilder）。这意味着所有搜索请求现在可以在调用时验证，这会导致更清晰的错误。 defaultResourceWindowSize（int）方法已删除。窗口大小应该在所有RescoreBuilder对象上显式设置。 ## SearchRequestBuilder 所有采用XContentBuilder，BytesReference Map <String，Object>或bytes []的方法已被删除，以便为该特征提供相关的构建器对象（例如HighlightBuilder，AggregationBuilder，SuggestBuilder）。这意味着所有搜索请求现在可以在调用时验证，这会导致更清晰的错误。所有的荧光笔方法已被删除，有利于单个highlighter(HighlightBuilder)方法。 setExtraSource(SearchSourceBuilder)方法已删除。 setTemplateSource(String)和setTemplateSource(BytesReference)方法已删除。请改用setTemplate(Template)。 setRescorer(RescoreBuilder）和setRescorer(RescoreBuilder，int)的setRescorer(Rescorer)和setRescorer(Rescorer，int） ## SearchRequest 所有源方法已删除，有利于单个源(SearchSourceBuilder)方法。这意味着所有搜索请求现在可以在调用时验证，这会导致更清晰的错误。所有extraSource方法已删除。所有模板方法已删除，有利于新的搜索模板API。新的SearchTemplateRequest现在接受模板和SearchRequest，并且必须使用新的SearchTemplateAction操作执行。 ## SearchResponse 字符串字段的排序值现在返回为java.lang.String对象，而不是org.elasticsearch.common.text.Text。 ## AggregationBuilder 已经删除了采用XContentBuilder，BytesReference Map <String，Object>或bytes []的所有方法，以提供相关的构建器对象（即subAggregation(AggregationBuilder)或subAggregation(PipelineAggregationBuilder) ）。这意味着所有请求现在可以在调用时验证，这会导致更清晰的错误。 ## ValidateQueryRequest 已经去除了`source(QuerySourceBuilder)`, `source(Map)`, `source(XContentBuilder)`, `source(String)`, `source(byte[])`, `source(byte[], int, int)`, `source(BytesReference)` 和 `source()` 有利于使用 `query(QueryBuilder)` 和 `query()` ## ValidateQueryRequestBuilder setSource() 方法已被删除，赞成使用 setQuery(QueryBuilder) ## 解释请求已经删除了`source(QuerySourceBuilder)`, `source(Map)`, `source(BytesReference)` 和 `source()`以支持使用 `query(QueryBuilder)` 和 `query()` ## ExplainRequestBuilder setQuery(BytesReference) 方法已被删除，有利于使用 setQuery(QueryBuilder) ## ClusterStatsResponse 从OsStats中删除了getMemoryAvailable方法，可以先调用`clusterStatsResponse.getNodesStats().getOs().getMemoryAvailable()`. 它现在被替换为`clusterStatsResponse.getNodesStats().getOs().getMem()` 这暴露了 `getTotal()`, `getFree()`,`getUsed()`, `getFreePercent()` 和 `getUsedPercent()`. ## setRefresh（boolean）已被删除 setRefresh（boolean）已被删除，有利于setRefreshPolicy（RefreshPolicy），因为现在有三个选项（NONE，IMMEDIATE和WAIT_FOR）。 setRefresh（IMMEDIATE）具有与setRefresh（true）相同的行为。有关更多信息，请参阅setRefreshPolicy的javadoc。 ## 删除属性支持一些Java API（例如，IndicesAdminClient＃setSettings）将支持Java属性语法（行分隔的键=值对）。此支持已删除。 ## 渲染搜索模板Java API已删除已删除渲染搜索模板Java API（包括RenderSearchTemplateAction，RenderSearchTemplateRequest和RenderSearchTemplateResponse），以支持搜索模板Java API中的新模拟选项。此搜索模板API现在包含在lang-mustache模块中，并且必须在SearchTemplateRequest对象上设置模拟标志。 ## AnalyzeRequest 为了使用`addTokenFilter(String)`/`addTokenFilter(Map) `和`addCharFilter(String)`/`addCharFilter(Map)`，删除了tokenFilters(String...)和charFilters(String...) ## AnalyzeRequestBuilder setTokenFilters(String...) 和setCharFilters(String...) 方法已被删除，有利于使用`addTokenFilter(String)`/`addTokenFilter(Map)`和`addCharFilter(String)`/`addCharFilter(Map)` ## ClusterHealthRequest waitForRelocatingShards(int) 方法已被删除，赞成使用`waitForNoRelocatingShards(boolean)` ，而是使用布尔标志来表示集群健康操作是否应该在返回之前等待集群中没有重定位碎片。 ## ClusterHealthRequestBuilder setWaitForRelocatingShards(int)方法已被删除，有利于setWaitForNoRelocatingShards(boolean)，而是使用布尔标志来表示集群健康操作是否应该在返回之前等待集群中没有重定位碎片。 ## 用于快照/恢复的BlobContainer接口一些方法已从BlobContainer接口中删除Snapshot / Restore存储库。特别地，已经去除了以下三种方法： 1. `deleteBlobs(Collection<String>)` (use `deleteBlob(String)` instead) 2. `deleteBlobsByPrefix(String)` (use `deleteBlob(String)` instead) 3. `writeBlob(String, BytesReference)` (use `writeBlob(String, InputStream, long)` instead) 删除多个blob作为参数的deleteBlob方法已被删除，因为无法对删除所有blob或删除它们进行原子保证，并且在这种情况下的异常处理是不明确的，最好留给调用者。因此，所有删除blob调用都使用单个deleteBlob(String) 方法。额外的writeBlob方法没有为接口提供真正的优势，并且对writeBlob(blobName, bytesRef) 的所有调用都可以替换为： ``` try (InputStream stream = bytesRef.streamInput()) { blobContainer.writeBlob(blobName, stream, bytesRef.length()); } ``` 对于BlobContainer接口的任何自定义实现，必须删除这三个方法。 ## 已删除NodeBuilder NodeBuilder已删除。虽然在应用程序中直接使用Node不是官方支持，它仍然可以用Node(Settings) 构造函数构造。