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 文件里：
org.elasticsearch.client
elasticsearch-rest-high-level-client
6.6.0
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请求。