ElasticSearch 应用开发（八）Java High Level Rest Client——Java API

---

1.概述

Java High Level REST Client

Elasticsearch 官方高级客户端： 基于低级客户端，提供特定的方法的API，并处理请求编码和响应解码

Java高级REST客户端可以在Java Low Level REST客户机之上工作。 其主要目标是公开特定方法的API，接受请求对象作为参数并返回响应对象，以便客户端自己处理请求编组和响应解组。

每个API可以同步或异步地调用。 同步方法返回一个响应对象，而名称以 async 后缀结尾的异步方法需要收到响应或错误后才会通知（在低级别客户端管理的线程池上）的侦听器参数。

Java高级REST客户端依赖于 Elasticsearch core项目。 它接受与 TransportClient 相同的请求参数，并返回相同的响应对象。

ElasticSeach6.6.0版本 Java Rest High Client，官网API，如下。相比之前，的确丰富了很多。

https://www.elastic.co/guide/en/elasticsearch/client/java-rest/6.6/java-rest-high.html 

2.Java High Level REST Client

2.1起步

本节介绍的内容，从如何high-level REST client获取包到在应用程序中使用高级REST客户端

2.1.1兼容性

Java高级REST客户端需要Java 1.8，并依赖于Elasticsearch核心项目。 客户端版本要与客户端开发的Elasticsearch版本相同。 它接受与 TransportClient 相同的请求参数，并返回相同的响应对象。 如果需要将应用程序从TransportClient迁移到新的REST客户端，请参阅 迁移指南。

高级客户端保证能够与运行在相同主版本和大于或等于次要版本的任何Elasticsearch节点进行通信。它不需要与它进行通信的弹性搜索节点相同的次要版本，因为它是向前兼容的，意味着它支持与之前开发的弹性搜索的更新版本进行通信。

6.0 客户端能够与任何 6.x Elasticsearch 节点进行通信，而 6.1 客户端确实能够与 6.1,6.2 和以后的 6.x 版本进行通信，但与以前的 Elasticsearch 节点版本通信时可能会出现不兼容问题例如 6.1 到 6.0 之间，例如 6.1 客户端支持而 6.0 节点不知道的某些API的新请求主体字段。

建议在将Elasticsearch集群升级到新的主要版本时升级高级客户端，因为REST API突破性更改可能会导致意外的结果，具体取决于请求所击中的节点，新添加的API只能由较新版本的客户端。一旦群集中的所有节点都升级到新的主版本，则客户端应当更新。

2.1.2 Javadoc

The javadoc for the REST high level client can be found at https://artifacts.elastic.co/javadoc/org/elasticsearch/client/elasticsearch-rest-high-level-client/6.6.2/index.html.

2.1.3Maven 仓库

高级 Java REST 客户端被托管在 Maven 中央仓库里。所需的最低Java版本为 1.8。

高级 REST 客户端与 elasticsearch 的发行周期相同。可以使用期望的版本进行替换。

Maven 配置

若使用 Maven 作依赖管理，你可以这样配置依赖。将下列内容添加到你的 pom.xml 文件里：

<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>elasticsearch-rest-high-level-client</artifactId>
    <version>6.6.0</version>
</dependency>

2.1.4依赖项

高级 Java REST Client 依赖以下包：

• org.elasticsearch.client:elasticsearch-rest-client
• org.elasticsearch:elasticsearch

2.1.5初始化

参考之前的内容：

ElasticSearch 应用开发（二）Java Client 连接ElasticSearch集群

2.1.6 RequestOptions

RestHighLevelClient 所有APIs都能接收一个能够自定义request请求的RequestOptions，而且不用改变elasticsearch如何执行request。例如，可以设定NodeSelector 决定哪个节点接收request。具体查看： low level client documentation 

 2.2Document APIs

The Java High Level REST Client supports the following Document APIs:

Single document APIs

• Index API
• Get API
• Exists API
• Delete API
• Update API
• Term Vectors API

Multi-document APIs

• Bulk API
• Multi-Get API
• Reindex API
• Update By Query API
• Delete By Query API
• Rethrottle API
• Multi Term Vectors API

2.3 Search APIs

The Java High Level REST Client supports the following Search APIs:

• Search API
• Search Scroll API
• Clear Scroll API
• Search Template API
• Multi-Search-Template API
• Multi-Search API
• Field Capabilities API
• Ranking Evaluation API
• Explain API
• Count API

2.4Miscellaneous（其他）APIs

The Java High Level REST Client supports the following Miscellaneous APIs:

• Info API
• Ping API
• X-Pack Info API
• X-Pack Usage API

2.5 Indices APIs

The Java High Level REST Client supports the following Indices APIs:

Index Management

• Analyze API
• Create Index API
• Delete Index API
• Indices Exists API
• Open Index API
• Close Index API
• Shrink Index API
• Split Index API
• Refresh API
• Flush API
• Flush Synced API
• Clear Cache API
• Force Merge API
• Rollover Index API
• Update Indices Settings API
• Get Settings API
• Validate Query API
• Get Index API

Mapping Management

• Put Mapping API
• Get Mappings API
• Get Field Mappings API

Alias Management

• Index Aliases API
• Exists Alias API
• Get Alias API

Template Management

• Get Templates API
• Templates Exist API
• Put Template API

2.6Cluster APIs

The Java High Level REST Client supports the following Cluster APIs:

• Cluster Update Settings API
• Cluster Get Settings API
• Cluster Health API

2.7Ingest APIs

The Java High Level REST Client supports the following Ingest APIs:

• Put Pipeline API
• Get Pipeline API
• Delete Pipeline API
• Simulate Pipeline API

2.8Snapshot APIs

The Java High Level REST Client supports the following Snapshot APIs:

• Snapshot Get Repository API
• Snapshot Create RepositoryAPI
• Snapshot Delete Repository API
• Snapshot Verify Repository API
• Create Snapshot API
• Get Snapshots API
• Snapshots Status API
• Delete Snapshot API

2.9Tasks APIs

The Java High Level REST Client supports the following Tasks APIs:

• List Tasks API
• Cancel Tasks API

2.10Script APIs

The Java High Level REST Client supports the following Scripts APIs:

• Get Stored Script API
• Put Stored Script API
• Delete Stored Script API

2.11Licensing APIs

The Java High Level REST Client supports the following Licensing APIs:

• Update License
• Get License
• Delete License
• Start Trial
• Start Basic License
• Get Trial Status
• Get Basic Status

2.12Machine Learning APIs

The Java High Level REST Client supports the following Machine Learning APIs:

• Put Job API
• Get Job API
• Delete Job API
• Open Job API
• Close Job API
• Flush Job API
• Update Job API
• Get Job Stats API
• Put Datafeed API
• Update Datafeed API
• Get Datafeed API
• Delete Datafeed API
• Preview Datafeed API
• Start Datafeed API
• Stop Datafeed API
• Get Datafeed Stats API
• Forecast Job API
• Delete Forecast API
• Get Buckets API
• Get Overall Buckets API
• Get Records API
• Post Data API
• Get Influencers API
• Get Categories API
• Get Calendars API
• Put Calendar API
• Get Calendar Events API
• Post Calendar Event API
• Delete Calendar Event API
• Put Calendar Job API
• Delete Calendar Job API
• Delete Calendar API
• Put Filter API
• Get Filters API
• Update Filter API
• Delete Filter API
• Get Model Snapshots API
• Delete Model Snapshot API
• Revert Model Snapshot API
• Update Model Snapshot API
• ML Get Info API
• Delete Expired Data API

2.13Migration APIs

The Java High Level REST Client supports the following Migration APIs:

• Migration Get Assistance
• Migration Upgrade
• Get Deprecation Info

2.14Rollup APIs

The Java High Level REST Client supports the following Rollup APIs:

• Put Rollup Job API
• Start Rollup Job API
• Stop Rollup Job API
• Delete Rollup Job API
• Get Rollup Job API
• Rollup Search API
• Get Rollup Capabilities API
• Get Rollup Index Capabilities API

2.14Security APIs

The Java High Level REST Client supports the following Security APIs:

• Put User API
• Get Users API
• Delete User API
• Enable User API
• Disable User API
• Change Password API
• Put Role API
• Get Roles API
• Delete Role API
• Clear Roles Cache API
• Clear Realm Cache API
• Authenticate API
• Has Privileges API
• Get User Privileges API
• SSL Certificate API
• Put Role Mapping API
• Get Role Mappings API
• Delete Role Mapping API
• Create Token API
• Invalidate Token API
• Get Privileges API
• Put Privileges API
• Delete Privileges API

2.15Watcher APIs

The Java High Level REST Client supports the following Watcher APIs:

• Start Watch Service API
• Stop Watch Service API
• Put Watch API
• Get Watch API
• Delete Watch API
• Deactivate Watch API
• Ack Watch API
• Activate Watch API
• Execute Watch API
• Watcher Stats API

2.16Graph APIs

The Java High Level REST Client supports the following Graph APIs:

• X-Pack Graph explore API

2.17CCR APIs

The Java High Level REST Client supports the following CCR APIs:

• Put Follow API
• Pause Follow API
• Resume Follow API
• Unfollow API
• Put Auto Follow Pattern API
• Delete Auto Follow Pattern API
• Get Auto Follow Pattern API
• Get CCR Stats API
• Get Follow Stats API

2.18Index Lifecycle Management APIs

The Java High Level REST Client supports the following Index Lifecycle Management APIs:

• Put Lifecycle Policy API
• Delete Lifecycle Policy API
• Get Lifecycle Policy API
• Explain Lifecycle API
• Start Index Lifecycle Management API
• Stop Index Lifecycle Management API
• Index Lifecycle Management Status API
• Retry Lifecycle Policy API
• Remove Policy from Index API

2.19Using Java Builders

Java高级REST客户端依赖于 Elasticsearch 核心项目提供的不同类型的 Java Builders 对象，包括：

（一）Query Builders

Query builders只适用于创建一次搜索请求，每次查询由 Query DSL支持。每一个Query builder由QueryBuilder 接口实现，并允许对每个给定类型的query设置特定参数。一旦完成创建， QueryBuilder 能够设置为SearchSourceBuilder的参数.  Search Request 展示了使用 SearchSourceBuilder 和QueryBuilder 进行搜索的例子.过程如下图所示：

Building Search Queries （如下所示）页给出 与QueryBuilder 相对于的 QueryBuilders 进行搜索的函数。

This page lists all the available search queries with their corresponding QueryBuilder class name and helper method name in the QueryBuilders utility class.

Match All Query

Search Query	QueryBuilder Class	Method in QueryBuilders
Match All	MatchAllQueryBuilder	QueryBuilders.matchAllQuery()

Full Text Queries

Search Query	QueryBuilder Class	Method in QueryBuilders
Match	MatchQueryBuilder	QueryBuilders.matchQuery()
Match Phrase	MatchPhraseQueryBuilder	QueryBuilders.matchPhraseQuery()
Match Phrase Prefix	MatchPhrasePrefixQueryBuilder	QueryBuilders.matchPhrasePrefixQuery()
Multi Match	MultiMatchQueryBuilder	QueryBuilders.multiMatchQuery()
Common Terms	CommonTermsQueryBuilder	QueryBuilders.commonTermsQuery()
Query String	QueryStringQueryBuilder	QueryBuilders.queryStringQuery()
Simple Query String	SimpleQueryStringBuilder	QueryBuilders.simpleQueryStringQuery()

Term level queries

Search Query	QueryBuilder Class	Method in QueryBuilders
Term	TermQueryBuilder	QueryBuilders.termQuery()
Terms	TermsQueryBuilder	QueryBuilders.termsQuery()
Range	RangeQueryBuilder	QueryBuilders.rangeQuery()
Exists	ExistsQueryBuilder	QueryBuilders.existsQuery()
Prefix	PrefixQueryBuilder	QueryBuilders.prefixQuery()
Wildcard	WildcardQueryBuilder	QueryBuilders.wildcardQuery()
Regexp	RegexpQueryBuilder	QueryBuilders.regexpQuery()
Fuzzy	FuzzyQueryBuilder	QueryBuilders.fuzzyQuery()
Type	TypeQueryBuilder	QueryBuilders.typeQuery()
Ids	IdsQueryBuilder	QueryBuilders.idsQuery()

Compound queries

Search Query	QueryBuilder Class	Method in QueryBuilders
Constant Score	ConstantScoreQueryBuilder	QueryBuilders.constantScoreQuery()
Bool	BoolQueryBuilder	QueryBuilders.boolQuery()
Dis Max	DisMaxQueryBuilder	QueryBuilders.disMaxQuery()
Function Score	FunctionScoreQueryBuilder	QueryBuilders.functionScoreQuery()
Boosting	BoostingQueryBuilder	QueryBuilders.boostingQuery()

Joining queries

Search Query	QueryBuilder Class	Method in QueryBuilders
Nested	NestedQueryBuilder	QueryBuilders.nestedQuery()
Has Child	HasChildQueryBuilder
Has Parent	HasParentQueryBuilder
Parent Id	ParentIdQueryBuilder

Geo queries

Search Query	QueryBuilder Class	Method in QueryBuilders
GeoShape	GeoShapeQueryBuilder	QueryBuilders.geoShapeQuery()
Geo Bounding Box	GeoBoundingBoxQueryBuilder	QueryBuilders.geoBoundingBoxQuery()
Geo Distance	GeoDistanceQueryBuilder	QueryBuilders.geoDistanceQuery()
Geo Polygon	GeoPolygonQueryBuilder	QueryBuilders.geoPolygonQuery()

Specialized queries

Search Query	QueryBuilder Class	Method in QueryBuilders
More Like This	MoreLikeThisQueryBuilder	QueryBuilders.moreLikeThisQuery()
Script	ScriptQueryBuilder	QueryBuilders.scriptQuery()
Percolate	PercolateQueryBuilder
Wrapper	WrapperQueryBuilder	QueryBuilders.wrapperQuery()

Span queries

Search Query	QueryBuilder Class	Method in QueryBuilders
Span Term	SpanTermQueryBuilder	QueryBuilders.spanTermQuery()
Span Multi Term	SpanMultiTermQueryBuilder	QueryBuilders.spanMultiTermQueryBuilder()
Span First	SpanFirstQueryBuilder	QueryBuilders.spanFirstQuery()
Span Near	SpanNearQueryBuilder	QueryBuilders.spanNearQuery()
Span Or	SpanOrQueryBuilder	QueryBuilders.spanOrQuery()
Span Not	SpanNotQueryBuilder	QueryBuilders.spanNotQuery()
Span Containing	SpanContainingQueryBuilder	QueryBuilders.spanContainingQuery()
Span Within	SpanWithinQueryBuilder	QueryBuilders.spanWithinQuery()
Span Field Masking	FieldMaskingSpanQueryBuilder	QueryBuilders.fieldMaskingSpanQuery()

（二）Aggregation Builders

和query builders类似，在搜索执行的过程，aggregation builders是用来聚合计算的。每一个类型的aggregation builder,都有与之对应的并且由ELasticsearch支持的aggregation (or pipeline aggregation)。创建成功后，`AggregationBuilder 可以作为SearchSourceBuilder的参数。  Search Request page，包含 AggregationBuilder 用于 SearchSourceBuilder 进行聚合计算的例子. The Building Aggregations page 列出了，AggregationBuilder 和 AggregationBuilders 相对于的帮助方法（如下所示）。

This page lists all the available aggregations with their corresponding AggregationBuilder class name and helper method name in the AggregationBuilders or PipelineAggregatorBuilders utility classes.

Metrics Aggregations

Aggregation	AggregationBuilder Class	Method in AggregationBuilders
Avg	AvgAggregationBuilder	AggregationBuilders.avg()
Cardinality	CardinalityAggregationBuilder	AggregationBuilders.cardinality()
Extended Stats	ExtendedStatsAggregationBuilder	AggregationBuilders.extendedStats()
Geo Bounds	GeoBoundsAggregationBuilder	AggregationBuilders.geoBounds()
Geo Centroid	GeoCentroidAggregationBuilder	AggregationBuilders.geoCentroid()
Max	MaxAggregationBuilder	AggregationBuilders.max()
Min	MinxAggregationBuilder	AggregationBuilders.min()
Percentiles	PercentilesAggregationBuilder	AggregationBuilders.percentiles()
Percentile Ranks	PercentileRanksAggregationBuilder	AggregationBuilders.percentileRanks()
Scripted Metric	ScriptedMetricAggregationBuilder	AggregationBuilders.scriptedMetric()
Stats	StatsAggregationBuilder	AggregationBuilders.stats()
Sum	SumAggregationBuilder	AggregationBuilders.sum()
Top hits	TopHitsAggregationBuilder	AggregationBuilders.topHits()
Value Count	ValueCountAggregationBuilder	AggregationBuilders.count()

Bucket Aggregations

Aggregation	AggregationBuilder Class	Method in AggregationBuilders
Adjacency Matrix	AdjacencyMatrixAggregationBuilder	AggregationBuilders.adjacencyMatrix()
Children	ChildrenAggregationBuilder
Date Histogram	DateHistogramAggregationBuilder	AggregationBuilders.dateHistogram()
Date Range	DateRangeAggregationBuilder	AggregationBuilders.dateRange()
Diversified Sampler	DiversifiedAggregationBuilder	AggregationBuilders.diversifiedSampler()
Filter	FilterAggregationBuilder	AggregationBuilders.filter()
Filters	FiltersAggregationBuilder	AggregationBuilders.filters()
Geo Distance	GeoDistanceAggregationBuilder	AggregationBuilders.geoDistance()
GeoHash Grid	GeoGridAggregationBuilder	AggregationBuilders.geohashGrid()
Global	GlobalAggregationBuilder	AggregationBuilders.global()
Histogram	HistogramAggregationBuilder	AggregationBuilders.histogram()
IP Range	IpRangeAggregationBuilder	AggregationBuilders.ipRange()
Missing	MissingAggregationBuilder	AggregationBuilders.missing()
Nested	NestedAggregationBuilder	AggregationBuilders.nested()
Range	RangeAggregationBuilder	AggregationBuilders.range()
Reverse nested	ReverseNestedAggregationBuilder	AggregationBuilders.reverseNested()
Sampler	SamplerAggregationBuilder	AggregationBuilders.sampler()
Significant Terms	SignificantTermsAggregationBuilder	AggregationBuilders.significantTerms()
Significant Text	SignificantTextAggregationBuilder	AggregationBuilders.significantText()
Terms	TermsAggregationBuilder	AggregationBuilders.terms()

Pipeline Aggregations

Pipeline on	PipelineAggregationBuilder Class	Method in PipelineAggregatorBuilders
Avg Bucket	AvgBucketPipelineAggregationBuilder	PipelineAggregatorBuilders.avgBucket()
Derivative	DerivativePipelineAggregationBuilder	PipelineAggregatorBuilders.derivative()
Max Bucket	MaxBucketPipelineAggregationBuilder	PipelineAggregatorBuilders.maxBucket()
Min Bucket	MinBucketPipelineAggregationBuilder	PipelineAggregatorBuilders.minBucket()
Sum Bucket	SumBucketPipelineAggregationBuilder	PipelineAggregatorBuilders.sumBucket()
Stats Bucket	StatsBucketPipelineAggregationBuilder	PipelineAggregatorBuilders.statsBucket()
Extended Stats Bucket	ExtendedStatsBucketPipelineAggregationBuilder	PipelineAggregatorBuilders.extendedStatsBucket()
Percentiles Bucket	PercentilesBucketPipelineAggregationBuilder	PipelineAggregatorBuilders.percentilesBucket()
Moving Average	MovAvgPipelineAggregationBuilder	PipelineAggregatorBuilders.movingAvg()
Cumulative Sum	CumulativeSumPipelineAggregationBuilder	PipelineAggregatorBuilders.cumulativeSum()
Bucket Script	BucketScriptPipelineAggregationBuilder	PipelineAggregatorBuilders.bucketScript()
Bucket Selector	BucketSelectorPipelineAggregationBuilder	PipelineAggregatorBuilders.bucketSelector()
Serial Differencing	SerialDiffPipelineAggregationBuilder	PipelineAggregatorBuilders.diff()

Matrix Aggregations

Aggregation	AggregationBuilder Class	Method in MatrixStatsAggregationBuilders
Matrix Stats	MatrixStatsAggregationBuilder	MatrixStatsAggregationBuilders.matrixStats()

2.20Migration Guide

本节介绍如何将现有代码从 TransportClient 迁移到使用 Elasticsearch 5.6.0 版本发布的新的 Java 高级 REST 客户端。

3.总结

ElasticSearch6.6中，Rest High Level Client的API如下 ，以Async的都是异步请求。

如果API没能够满足请求，可以通过获取LowLevelClient，发送Http请求。