Java High Level REST Client 中文API（仅供参考）

时间  2019-11-12
标签 java high level rest client 中文 api 仅供参考 栏目 Java 繁體版
原文   原文链接

一、初始化

兼容性

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

High Level Client保证可以与运行在相同主版本和大于或等于的次要版本上的任何Elasticsearch节点通讯。当它与Elasticsearch节点通讯时，它不须要在同一个次要版本中，由于它是向前兼容的，这意味着它支持与Elasticsearch的更高的版本进行通讯，而不是与其开发的版本进行通讯。java

6.0客户端可以与任何6.x Elasticsearch节点通讯，而6.1客户端确定可以与6.1，6.2和任何更高版本的6.x版本通讯，可是，若是6.1客户端支持6.0节点不知道的某些API的新请求主体字段，则在与先前的Elasticsearch节点版本通讯时可能存在不兼容问题，例如在6.1和6.0之间。web

建议在将Elasticsearch集群升级到新的主要版本时升级High Level Client，由于REST API重要更改可能会致使意外结果，具体取决于请求命中的节点，而且只有较新版本的客户端才支持新添加的API，一旦集群中的全部节点都升级到新的主版本，客户端应该老是在最后更新。编程

Javadoc

https://www.elastic.co/guide/en/elasticsearch/client/java-rest/7.4/java-rest-high-supported-apis.htmljson

Maven仓库

高级别Java REST客户端托管在Maven Central上，所需的最低Java版本为1.8。segmentfault

High Level REST Client与Elasticsearch具备相同的发布周期，将版本替换为想要的客户端版本。api

若是你正在寻找SNAPSHOT版本，能够经过https://snapshots.elastic.co/maven/获取Elastic Maven Snapshot仓库。数组

Maven配置

如下是如何使用maven做为依赖关系管理器来配置依赖关系，将如下内容添加到pom.xml文件中异步

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

Gradle配置

如下是使用gradle做为依赖关系管理器配置依赖关系的方法，将如下内容添加到build.gradle文件中：elasticsearch

dependencies {
    compile 'org.elasticsearch.client:elasticsearch-rest-high-level-client:6.4.2'
}

Lucene Snapshot仓库

任何主要版本（如测试版）的最新版本可能都是基于Lucene Snapshot版本构建的，在这种状况下，你将没法解析客户端的Lucene依赖关系。

例如，若是要使用依赖于Lucene 7.0.0-snapshot-00142c9的6.0.0-beta1版本，则必须定义如下存储库。

对于Maven：

<repository>
    <id>elastic-lucene-snapshots</id>
    <name>Elastic Lucene Snapshots</name>
    <url>http://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9</url>
    <releases><enabled>true</enabled></releases>
    <snapshots><enabled>false</enabled></snapshots>
</repository>

对于Gradle：

maven {
    url 'http://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9'
}

依赖关系

High Level Java REST Client依赖于如下工件及其传递依赖性：

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

初始化

RestHighLevelClient实例须要按以下方式构建REST低级别客户端构建器：

RestHighLevelClient client = new RestHighLevelClient(
        RestClient.builder(
                new HttpHost("localhost", 9200, "http"),
                new HttpHost("localhost", 9201, "http")));

高级别客户端将在内部建立用于根据提供的构建器执行请求的低级别客户端，该低级别客户端维护一个链接池并启动一些线程，所以当你无缺无损地关闭高级别客户端时，它将关闭内部低级别客户端以释放这些资源，这能够经过close来完成：

client.close();

在关于Java High Level Client的本文档的其他部分中，RestHighLevelClient实例将被引用为client。

RequestOptions

RestHighLevelClient中的全部API都接受RequestOptions，你能够用来不会改变Elasticsearch执行请求的的方式自定义请求。例如，你能够在此处指定NodeSelector来控制哪一个节点接收请求，有关自定义选项的更多示例，请参阅低级别客户端文档。

二、Index API

索引请求

IndexRequest须要如下参数：

IndexRequest request = new IndexRequest(
        "posts", 
        "doc",  
        "1");   
String jsonString = "{" +
        "\"user\":\"kimchy\"," +
        "\"postDate\":\"2013-01-30\"," +
        "\"message\":\"trying out Elasticsearch\"" +
        "}";
request.source(jsonString, XContentType.JSON);
  • posts — 索引。
  • doc — 类型。
  • 1 — 文档ID。
  • 文档源以字符串形式提供。

提供文档源

除了上面显示的String示例以外，还能够以不一样的方式提供文档源：

Map<String, Object> jsonMap = new HashMap<>();
jsonMap.put("user", "kimchy");
jsonMap.put("postDate", new Date());
jsonMap.put("message", "trying out Elasticsearch");
IndexRequest indexRequest = new IndexRequest("posts", "doc", "1")
        .source(jsonMap);
  • 文档源做为Map提供，可自动转换为JSON格式。
XContentBuilder builder = XContentFactory.jsonBuilder();
builder.startObject();
{
    builder.field("user", "kimchy");
    builder.timeField("postDate", new Date());
    builder.field("message", "trying out Elasticsearch");
}
builder.endObject();
IndexRequest indexRequest = new IndexRequest("posts", "doc", "1")
        .source(builder);
  • 文档源做为XContentBuilder对象提供，Elasticsearch内置辅助生成JSON内容。
IndexRequest indexRequest = new IndexRequest("posts", "doc", "1")
        .source("user", "kimchy",
                "postDate", new Date(),
                "message", "trying out Elasticsearch");
  • 文档源做为Object键值对提供，转换为JSON格式。

可选参数

能够选择提供如下参数：

request.routing("routing");
  • 路由值。
request.parent("parent");
  • parent值。
request.timeout(TimeValue.timeValueSeconds(1)); 
request.timeout("1s");
  • 等待主碎片可用的做为TimeValue的超时。
  • 等待主碎片可用的做为String的超时。
request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL);
request.setRefreshPolicy("wait_for");
  • 刷新策略做为WriteRequest.RefreshPolicy实例提供。
  • 刷新策略做为String提供。
request.version(2);
  • 版本。
request.versionType(VersionType.EXTERNAL);
  • 版本类型。
request.opType(DocWriteRequest.OpType.CREATE); 
request.opType("create");
  • 操做类型做为DocWriteRequest.OpType值提供。
  • 做为String提供的操做类型：能够为create或update（默认）。
request.setPipeline("pipeline");
  • 索引文档以前要执行的摄取管道的名称。

同步执行

如下列方式执行IndexRequest时，客户端在继续执行代码以前等待返回IndexResponse：

IndexResponse indexResponse = client.index(request, RequestOptions.DEFAULT);

异步执行

执行IndexRequest也能够以异步方式完成，以便客户端能够直接返回，用户须要经过将请求和侦听器传递给异步索引方法来指定响应或潜在故障的处理方式：

client.indexAsync(request, RequestOptions.DEFAULT, listener);
  • 要执行的IndexRequest和执行完成时要使用的ActionListener。

异步方法不会阻塞并当即返回，一旦完成，若是执行成功完成，则使用onResponse方法回调ActionListener，若是失败则使用onFailure方法。

index的典型侦听器以下所示：

listener = new ActionListener<IndexResponse>() {
    @Override
    public void onResponse(IndexResponse indexResponse) {
        
    }

    @Override
    public void onFailure(Exception e) {
        
    }
};
  • onResponse — 执行成功完成时调用。
  • onFailure — 当整个IndexRequest失败时调用。

索引响应

返回的IndexResponse容许检索有关已执行操做的信息，以下所示：

String index = indexResponse.getIndex();
String type = indexResponse.getType();
String id = indexResponse.getId();
long version = indexResponse.getVersion();
if (indexResponse.getResult() == DocWriteResponse.Result.CREATED) {
    
} else if (indexResponse.getResult() == DocWriteResponse.Result.UPDATED) {
    
}
ReplicationResponse.ShardInfo shardInfo = indexResponse.getShardInfo();
if (shardInfo.getTotal() != shardInfo.getSuccessful()) {
    
}
if (shardInfo.getFailed() > 0) {
    for (ReplicationResponse.ShardInfo.Failure failure :
            shardInfo.getFailures()) {
        String reason = failure.reason(); 
    }
}
  • 处理（若是须要）第一次建立文档的状况。
  • 处理（若是须要）文档被重写的状况，由于它已经存在。
  • 处理成功碎片数小于总碎片数的状况。
  • 处理潜在的失败。

若是存在版本冲突，则抛出ElasticsearchException：

IndexRequest request = new IndexRequest("posts", "doc", "1")
        .source("field", "value")
        .version(1);
try {
    IndexResponse response = client.index(request, RequestOptions.DEFAULT);
} catch(ElasticsearchException e) {
    if (e.status() == RestStatus.CONFLICT) {
        
    }
}
  • 引起的异常表示返回了版本冲突错误。

若是将opType设置为create而且已存在具备相同索引、类型和ID的文档，则会发生相同的状况：

IndexRequest request = new IndexRequest("posts", "doc", "1")
        .source("field", "value")
        .opType(DocWriteRequest.OpType.CREATE);
try {
    IndexResponse response = client.index(request, RequestOptions.DEFAULT);
} catch(ElasticsearchException e) {
    if (e.status() == RestStatus.CONFLICT) {
        
    }
}

三、Get API

Get请求

GetRequest须要如下参数：

GetRequest getRequest = new GetRequest(
        "posts", 
        "doc",  
        "1");
  • posts — 索引。
  • doc — 类型。
  • 1 — 文档id。

可选参数

能够选择提供如下参数：

request.fetchSourceContext(FetchSourceContext.DO_NOT_FETCH_SOURCE);
  • 禁用源检索，默认状况下启用
String[] includes = new String[]{"message", "*Date"};
String[] excludes = Strings.EMPTY_ARRAY;
FetchSourceContext fetchSourceContext =
        new FetchSourceContext(true, includes, excludes);
request.fetchSourceContext(fetchSourceContext);
  • 为特定字段配置源包含
String[] includes = Strings.EMPTY_ARRAY;
String[] excludes = new String[]{"message"};
FetchSourceContext fetchSourceContext =
        new FetchSourceContext(true, includes, excludes);
request.fetchSourceContext(fetchSourceContext);
  • 为特定字段配置源排除
request.storedFields("message"); 
GetResponse getResponse = client.get(request, RequestOptions.DEFAULT);
String message = getResponse.getField("message").getValue();
  • 配置特定存储字段的检索（要求字段分别存储在映射中）。
  • 检索message存储字段（要求字段分别存储在映射中）。
request.routing("routing");
  • 路由值。
request.parent("parent");
  • parent值。
request.preference("preference");
  • 偏好值。
request.realtime(false);
  • 将realtime标志设置为false（默认为true）。
request.refresh(true);
  • 在检索文档以前执行刷新（默认为false）。
request.version(2);
  • 版本。
request.versionType(VersionType.EXTERNAL);
  • 版本类型。

同步执行

如下列方式执行GetRequest时，客户端在继续执行代码以前等待返回GetResponse：

GetResponse getResponse = client.get(getRequest, RequestOptions.DEFAULT);

异步执行

执行GetRequest也能够以异步方式完成，以便客户端能够直接返回，用户须要经过将请求和侦听器传递给异步get方法来指定响应或潜在故障的处理方式：

client.getAsync(request, RequestOptions.DEFAULT, listener);
  • 要执行的GetRequest和执行完成时要使用的ActionListener。

异步方法不会阻塞并当即返回，完成后，若是执行成功完成，则使用onResponse方法回调ActionListener，若是失败则使用onFailure方法。

get的典型监听器看起来像：

ActionListener<GetResponse> listener = new ActionListener<GetResponse>() {
    @Override
    public void onResponse(GetResponse getResponse) {
        
    }

    @Override
    public void onFailure(Exception e) {
        
    }
};
  • onResponse — 执行成功完成时调用。
  • onFailure — 在整个GetRequest失败时调用。

Get响应

返回的GetResponse容许检索所请求的文档及其元数据和最终存储的字段。

String index = getResponse.getIndex();
String type = getResponse.getType();
String id = getResponse.getId();
if (getResponse.isExists()) {
    long version = getResponse.getVersion();
    String sourceAsString = getResponse.getSourceAsString();        
    Map<String, Object> sourceAsMap = getResponse.getSourceAsMap(); 
    byte[] sourceAsBytes = getResponse.getSourceAsBytes();          
} else {
    
}
  • 以字符串形式检索文档。
  • 将文档检索为Map<String, Object>。
  • 以byte[]的形式检索文档。
  • 处理未找到文档的方案，请注意，虽然返回的响应具备404状态代码，但返回有效的GetResponse而不是抛出异常，此类响应不包含任何源文档，而且其isExists方法返回false。

当针对不存在的索引执行get请求时，响应具备404状态代码，抛出ElasticsearchException，须要按以下方式处理：

GetRequest request = new GetRequest("does_not_exist", "doc", "1");
try {
    GetResponse getResponse = client.get(request, RequestOptions.DEFAULT);
} catch (ElasticsearchException e) {
    if (e.status() == RestStatus.NOT_FOUND) {
        
    }
}
  • 处理抛出的异常，由于索引不存在。

若是已请求特定文档版本，而且现有文档具备不一样的版本号，则会引起版本冲突：

try {
    GetRequest request = new GetRequest("posts", "doc", "1").version(2);
    GetResponse getResponse = client.get(request, RequestOptions.DEFAULT);
} catch (ElasticsearchException exception) {
    if (exception.status() == RestStatus.CONFLICT) {
        
    }
}

引起的异常表示返回了版本冲突错误。

四、Exists API

若是文档存在，则existsAPI返回true，不然返回false。

Exists请求

它就像Get API同样使用GetRequest，支持全部可选参数，因为exists()只返回true或false，咱们建议关闭获取_source和任何存储的字段，以便请求稍微轻一点：

GetRequest getRequest = new GetRequest(
    "posts", 
    "doc",   
    "1");    
getRequest.fetchSourceContext(new FetchSourceContext(false)); 
getRequest.storedFields("_none_");
  • posts — 索引。
  • doc — 类型。
  • 1 — 索引id。
  • FetchSourceContext(false) — 禁用提取_source。
  • storedFields("_none_") — 禁用提取存储的字段。

同步执行

如下列方式执行GetRequest时，客户端在继续执行代码以前等待返回boolean：

boolean exists = client.exists(getRequest, RequestOptions.DEFAULT);

异步执行

执行GetRequest也能够以异步方式完成，以便客户端能够直接返回，用户须要经过将请求和侦听器传递给异步exists方法来指定响应或潜在故障的处理方式：

client.existsAsync(getRequest, RequestOptions.DEFAULT, listener);
  • 要执行的GetRequest和执行完成时要使用的ActionListener。

异步方法不会阻塞并当即返回，完成后，若是执行成功完成，则使用onResponse方法回调ActionListener，若是失败则使用onFailure方法。

exists的典型侦听器以下所示：

ActionListener<Boolean> listener = new ActionListener<Boolean>() {
    @Override
    public void onResponse(Boolean exists) {
        
    }

    @Override
    public void onFailure(Exception e) {
        
    }
};
  • onResponse — 执行成功完成时调用。
  • onFailure — 在整个GetRequest失败时调用。

五、Delete API

Delete请求

DeleteRequest没有参数。

DeleteRequest request = new DeleteRequest(
        "posts",    
        "doc",      
        "1");
  • posts — 索引。
  • doc — 类型。
  • 1 — 文档id。

可选参数

能够选择提供如下参数：

request.routing("routing");
  • 路由值。
request.parent("parent");
  • parent值。
request.timeout(TimeValue.timeValueMinutes(2)); 
request.timeout("2m");
  • 等待主碎片可用的做为TimeValue的超时。
  • 等待主碎片可用的做为String的超时。
request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL);
request.setRefreshPolicy("wait_for");
  • 将刷新策略做为WriteRequest.RefreshPolicy实例。
  • 将刷新策略做为String。
request.version(2);
  • 版本。
request.versionType(VersionType.EXTERNAL);
  • 版本类型。

同步执行

如下列方式执行DeleteRequest时，客户端在继续执行代码以前等待返回DeleteResponse：

DeleteResponse deleteResponse = client.delete(
        request, RequestOptions.DEFAULT);

异步执行

执行DeleteRequest也能够以异步方式完成，以便客户端能够直接返回，用户须要经过将请求和侦听器传递给异步删除方法来指定响应或潜在故障的处理方式：

client.deleteAsync(request, RequestOptions.DEFAULT, listener);
  • 要执行的DeleteRequest和执行完成时要使用的ActionListener。

异步方法不会阻塞并当即返回，完成后，若是执行成功完成，则使用onResponse方法回调ActionListener，若是失败则使用onFailure方法。

delete的典型侦听器以下所示：

listener = new ActionListener<DeleteResponse>() {
    @Override
    public void onResponse(DeleteResponse deleteResponse) {
        
    }

    @Override
    public void onFailure(Exception e) {
        
    }
};
  • onResponse — 执行成功完成时调用。
  • onFailure — 在整个DeleteRequest失败时调用。

Delete响应

返回的DeleteResponse容许检索有关已执行操做的信息，以下所示：

String index = deleteResponse.getIndex();
String type = deleteResponse.getType();
String id = deleteResponse.getId();
long version = deleteResponse.getVersion();
ReplicationResponse.ShardInfo shardInfo = deleteResponse.getShardInfo();
if (shardInfo.getTotal() != shardInfo.getSuccessful()) {
    
}
if (shardInfo.getFailed() > 0) {
    for (ReplicationResponse.ShardInfo.Failure failure :
            shardInfo.getFailures()) {
        String reason = failure.reason(); 
    }
}
  • 处理成功碎片数小于总分片数的状况。
  • 处理潜在的失败。

还能够检查文档是否被找到：

DeleteRequest request = new DeleteRequest("posts", "doc", "does_not_exist");
DeleteResponse deleteResponse = client.delete(
        request, RequestOptions.DEFAULT);
if (deleteResponse.getResult() == DocWriteResponse.Result.NOT_FOUND) {
    
}
  • 若是找不到要删除的文档，请执行某些操做。

若是存在版本冲突，则抛出ElasticsearchException：

try {
    DeleteResponse deleteResponse = client.delete(
            new DeleteRequest("posts", "doc", "1").version(2),
            RequestOptions.DEFAULT);
} catch (ElasticsearchException exception) {
    if (exception.status() == RestStatus.CONFLICT) {
        
    }
}
  • 引起的异常表示返回了版本冲突错误。

说明此部分官方地址：

https://www.elastic.co/guide/en/elasticsearch/client/java-rest/7.4/_search_apis.html

六、Search API

Search Request

SearchRequest用于与搜索文档、聚合、建议相关的任何操做，还提供了请求突出显示结果文档的方法。

最基本的形式，咱们能够添加一个查询请求：

SearchRequest searchRequest = new SearchRequest(); 
SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder(); 
searchSourceBuilder.query(QueryBuilders.matchAllQuery()); 
searchRequest.source(searchSourceBuilder);
  • 建立SeachRequest。若是没有参数，则运行全部索引。
  • 大多数搜索参数被添加到SearchSourceBuilder。它为进入搜索请求体的全部内容提供。
  • 向SearchSourceBuilder添加一个match_all查询。
  • 将SearchSourceBuilder添加到SeachRequest中。

Optional arguments

可选参数

让咱们先看看SearchRequest的一些可选参数:

SearchRequest searchRequest = new SearchRequest("posts");

将请求限制为索引posts

有几个其余有趣的可选参数：

searchRequest.routing("routing");

设置路由参数

searchRequest.indicesOptions(IndicesOptions.lenientExpandOpen());

设置IndicesOptions能够控制如何解析不可用的索引以及如何展开通配符表达式

searchRequest.preference("_local");

使用preference参数，例如，执行搜索以选择本地碎片。默认设置是在碎片之间随机分配。

SearchSourceBuilder

大多数控制搜索行为的选项均可以在SearchSourceBuilder上设置，它或多或少地包含了Rest API的搜索请求体中的选项。

如下是一些常见的选择:

SearchSourceBuilder sourceBuilder = new SearchSourceBuilder(); 
sourceBuilder.query(QueryBuilders.termQuery("user", "kimchy")); 
sourceBuilder.from(0); 
sourceBuilder.size(5); 
sourceBuilder.timeout(new TimeValue(60, TimeUnit.SECONDS));
  • 使用默认选项建立一个SearchSourceBuilder。
  • 设置查询。成为任何类型的QueryBuilder
  • 设置from选项，该选项肯定要开始搜索的结果索引。默认值为0。
  • 设置肯定要返回的搜索结果数量的大小选项。默认为10。
  • 设置一个可选的超时，控制容许搜索的时间。

以后，SearchSourceBuilder只须要添加到SearchRequest:

SearchRequest searchRequest = new SearchRequest();
searchRequest.indices("posts");
searchRequest.source(sourceBuilder);

Building query

创建查询

搜索查询是使用QueryBuilder对象建立的。对于Elasticsearch的查询DSL支持的每一个搜索查询类型，都存在一个QueryBuilder。

QueryBuilder可使用它的构造函数建立:

MatchQueryBuilder matchQueryBuilder = new MatchQueryBuilder("user", "kimchy");

建立一个全文本匹配查询，在“user”字段上匹配文本“kimchy”

一旦建立，QueryBuilder对象提供方法来配置它建立的搜索查询的选项:

matchQueryBuilder.fuzziness(Fuzziness.AUTO); 
matchQueryBuilder.prefixLength(3); 
matchQueryBuilder.maxExpansions(10);
  • 对匹配查询启用模糊匹配
  • 在匹配查询中设置前缀长度选项
  • 设置最大扩展选项来控制查询的模糊过程

还可使用QueryBuilders实用程序类建立QueryBuilder对象。这个类提供了可使用连贯编程风格建立QueryBuilder对象的助手方法:

QueryBuilder matchQueryBuilder = QueryBuilders.matchQuery("user", "kimchy")
                                                .fuzziness(Fuzziness.AUTO)
                                                .prefixLength(3)
                                                .maxExpansions(10);

不管使用什么方法建立它，QueryBuilder对象都必须添加到SearchSourceBuilder中，以下所示:

searchSourceBuilder.query(matchQueryBuilder);

构建查询页面提供了全部可用搜索查询的列表，其中包含相应的QueryBuilder对象和QueryBuilders助手方法。

Specifying Sorting

指定排序

SearchSourceBuilder容许添加一个或多个SortBuilder实例。有四种特殊的实现(Field-、Score-、GeoDistance-和ScriptSortBuilder)。

sourceBuilder.sort(new ScoreSortBuilder().order(SortOrder.DESC)); 
sourceBuilder.sort(new FieldSortBuilder("_id").order(SortOrder.ASC));
  • 按_score降序排序(默认)
  • 还能够按_id字段升序排序

Source filtering

源过滤

默认状况下，搜索请求会返回文档’ _source ‘的内容，可是就像在Rest API中同样，您能够覆盖这种行为。例如，你能够彻底关闭’ _source '检索:

sourceBuilder.fetchSource(false);

该方法还接受一个由一个或多个通配符模式组成的数组，以控制以更细粒度的方式包含或排除哪些字段:

String[] includeFields = new String[] {"title", "innerObject.*"};
String[] excludeFields = new String[] {"user"};
sourceBuilder.fetchSource(includeFields, excludeFields);

Requesting Highlighting

高亮查询

能够经过在SearchSourceBuilder上设置HighlightBuilder来突出显示搜索结果。经过添加一个或多个HighlightBuilder，能够为每一个字段定义不一样的突出显示行为。字段实例到HighlightBuilder。

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
HighlightBuilder highlightBuilder = new HighlightBuilder(); 
HighlightBuilder.Field highlightTitle =
        new HighlightBuilder.Field("title"); 
highlightTitle.highlighterType("unified");  
highlightBuilder.field(highlightTitle);  
HighlightBuilder.Field highlightUser = new HighlightBuilder.Field("user");
highlightBuilder.field(highlightUser);
searchSourceBuilder.highlighter(highlightBuilder);
  • 建立一个新的HighlightBuilder
  • 为标题栏建立一个高光栏
  • 设置字段高亮字体
  • 将字段高光添加到高光生成器

Rest API文档中详细解释了许多选项。Rest API参数(例如pre_tags)一般由同名的setter(例如#preTags(String…))更改。

Requesting Aggregation

聚合查询

经过首先建立适当的AggregationBuilder，而后在SearchSourceBuilder上设置它，能够将聚合添加到搜索中。在下面的例子中，咱们建立了一个基于公司名称的术语聚合，其中包含一个关于公司员工平均年龄的子聚合:

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
TermsAggregationBuilder aggregation = AggregationBuilders.terms("by_company")
        .field("company.keyword");
aggregation.subAggregation(AggregationBuilders.avg("average_age")
        .field("age"));
searchSourceBuilder.aggregation(aggregation);

Requesting Suggestion

使用建议

要向搜索请求添加建议，请使用能够从SuggestBuilders factory类轻松访问的SuggestionBuilder实现之一。建议生成器须要添加到顶级的SuggestBuilder中，其自己能够设置在SearchSourceBuilder中。

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
SuggestionBuilder termSuggestionBuilder =
    SuggestBuilders.termSuggestion("user").text("kmichy"); 
SuggestBuilder suggestBuilder = new SuggestBuilder();
suggestBuilder.addSuggestion("suggest_user", termSuggestionBuilder); 
searchSourceBuilder.suggest(suggestBuilder);
  • 为用户字段和文本kmichy建立一个新的termtionbuilder
  • 添加建议生成器并将其命名为suggest_user

Profiling Queries and Aggregationsedit

分析查询和聚合

配置文件API可用于配置特定搜索请求的查询和聚合的执行。为了使用它，配置文件标志必须设置为真在SearchSourceBuilder:

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
searchSourceBuilder.profile(true);

一旦检索请求是执行相应的回应类别将包含分析结果。

Asynchronous execution

异步执行

还能够以异步方式执行SearchRequest，以便客户机能够直接返回。用户须要经过向异步搜索方法传递请求和侦听器来指定如何处理响应或潜在故障:

client.searchAsync(searchRequest, RequestOptions.DEFAULT, listener);

执行的SearchRequest和执行完成时使用的ActionListener

异步方法不会阻塞，而是当即返回。一旦完成，若是执行成功完成，则使用onResponse方法调用ActionListener;若是执行失败，则使用onFailure方法调用它。失败场景和预期的异常与同步执行状况相同。

典型的搜索监听器是这样的：

ActionListener<SearchResponse> listener = new ActionListener<SearchResponse>() {
    @Override
    public void onResponse(SearchResponse searchResponse) {
        
    }

    @Override
    public void onFailure(Exception e) {
        
    }
};

onResponse当执行成功完成时，调用。

onFailure整个检索请求失败时调用。

SearchResponse

SearchResponse

执行搜索返回的SearchResponse提供了关于搜索执行自己以及对返回文档的访问的详细信息。首先，有关于请求执行自己的有用信息，如HTTP状态码、执行时间或请求是否提早终止或超时:

RestStatus status = searchResponse.status();
TimeValue took = searchResponse.getTook();
Boolean terminatedEarly = searchResponse.isTerminatedEarly();
boolean timedOut = searchResponse.isTimedOut();

其次，响应还经过提供关于受搜索影响的碎片总数以及成功碎片和不成功碎片的统计信息，提供关于碎片级别上执行的信息。可能的故障也能够经过迭代shardsearchfailure数组来处理，以下面的例子所示:

int totalShards = searchResponse.getTotalShards();
int successfulShards = searchResponse.getSuccessfulShards();
int failedShards = searchResponse.getFailedShards();
for (ShardSearchFailure failure : searchResponse.getShardFailures()) {
    // failures should be handled here
}

Retrieving SearchHits

检索SearchHits

要访问返回的文档，咱们须要首先得到响应中包含的SearchHits:

SearchHits hits = searchResponse.getHits();

SearchHits提供关于全部点击的全局信息，好比总点击数或最大得分:

TotalHits totalHits = hits.getTotalHits();
// the total number of hits, must be interpreted in the context of totalHits.relation
long numHits = totalHits.value;
// whether the number of hits is accurate (EQUAL_TO) or a lower bound of the total (GREATER_THAN_OR_EQUAL_TO)
TotalHits.Relation relation = totalHits.relation;
float maxScore = hits.getMaxScore();

嵌套在SearchHits是能够迭代的单个搜索结果:

SearchHit[] searchHits = hits.getHits();
for (SearchHit hit : searchHits) {
    // do something with the SearchHit
}

SearchHit提供了对基本信息的访问，好比索引、文档ID和每次搜索命中的分数:

String index = hit.getIndex();
String id = hit.getId();
float score = hit.getScore();

此外，它还容许您以简单的JSON-String或键/值对映射的形式获取文档源。在此映射中，常规字段由字段名做为键值，并包含字段值。多值字段做为对象列表返回，嵌套对象做为另外一个键/值映射返回。这些状况须要相应地进行断定:

String sourceAsString = hit.getSourceAsString();
Map<String, Object> sourceAsMap = hit.getSourceAsMap();
String documentTitle = (String) sourceAsMap.get("title");
List<Object> users = (List<Object>) sourceAsMap.get("user");
Map<String, Object> innerObject =
        (Map<String, Object>) sourceAsMap.get("innerObject");

Retrieving Highlighting

检索高亮

若是须要，能够从结果中的每一个SearchHit检索突出显示的文本片断。hit对象提供了从字段名到HighlightField实例的映射，每一个实例包含一个或多个突出显示的文本片断:

SearchHits hits = searchResponse.getHits();
for (SearchHit hit : hits.getHits()) {
    Map<String, HighlightField> highlightFields = hit.getHighlightFields();
    HighlightField highlight = highlightFields.get("title"); 
    Text[] fragments = highlight.fragments();  
    String fragmentString = fragments[0].string();
}

获取标题字段的高亮显示

获取一个或多个包含突出显示字段内容的片断

Retrieving Aggregations

检索聚合

经过首先获取聚合树的根，即Aggregations对象，而后经过名称获取聚合，能够从SearchResponse检索聚合。

Aggregations aggregations = searchResponse.getAggregations();
Terms byCompanyAggregation = aggregations.get("by_company"); 
Bucket elasticBucket = byCompanyAggregation.getBucketByKey("Elastic"); 
Avg averageAge = elasticBucket.getAggregations().get("average_age"); 
double avg = averageAge.getValue();
  • 获得by_company聚合
  • 获得Elastic对应的Bucket
  • 从该bucket获取average_age子聚合

注意，若是按名称访问聚合，须要根据请求的聚合类型指定聚合接口，不然会抛出ClassCastException:

Range range = aggregations.get("by_company");

会抛出一个异常，由于“by_company”是一个术语聚合，但咱们试图将其检索为一个范围聚合。

还能够将全部聚合做为映射访问，映射由聚合名称做为键。在这种状况下，须要显式地转换到适当的聚合接口:

Map<String, Aggregation> aggregationMap = aggregations.getAsMap();
Terms companyAggregation = (Terms) aggregationMap.get("by_company");

还有getter返回全部顶级的聚合为一个列表：

List<Aggregation> aggregationList = aggregations.asList();

最后但并不是最不重要的是，你能够迭代全部的聚合，而后决定如何进一步处理他们基于他们的类型:

for (Aggregation agg : aggregations) {
    String type = agg.getType();
    if (type.equals(TermsAggregationBuilder.NAME)) {
        Bucket elasticBucket = ((Terms) agg).getBucketByKey("Elastic");
        long numberOfDocs = elasticBucket.getDocCount();
    }
}

Retrieving Suggestion

检索建议

要从SearchResponse获取建议，使用Suggest对象做为入口点，而后检索嵌套的建议对象:

Suggest suggest = searchResponse.getSuggest(); 
TermSuggestion termSuggestion = suggest.getSuggestion("suggest_user"); 
for (TermSuggestion.Entry entry : termSuggestion.getEntries()) { 
    for (TermSuggestion.Entry.Option option : entry) { 
        String suggestText = option.getText().string();
    }
}

  • 使用Suggest类来访问建议

  • 能够经过名称检索建议。您须要将它们分配给建议类的正确类型(这里是TermSuggestion)，不然将抛出ClassCastException

  • 迭代建议条目

  • 遍历一个条目中的选项

Retrieving Profiling Results

检索分析结果

使用getProfileResults()方法从SearchResponse检索分析结果。此方法为SearchRequest执行中涉及的每一个碎片返回一个包含ProfileShardResult对象的映射。ProfileShardResult使用惟一标识配置文件结果所对应的碎片的键存储在映射中。

下面的示例代码演示了如何遍历每一个碎片的全部分析结果:

Map<String, ProfileShardResult> profilingResults =
        searchResponse.getProfileResults(); 
for (Map.Entry<String, ProfileShardResult> profilingResult : profilingResults.entrySet()) { 
    String key = profilingResult.getKey(); 
    ProfileShardResult profileShardResult = profilingResult.getValue(); 
}
  • 从SearchResponse检索ProfileShardResult的地图
  • 若是键是已知的，那么能够经过shard的键检索分析结果，不然遍历全部分析结果可能更简单
  • 检索标识ProfileShardResult属于哪一个碎片的键
  • 检索给定碎片的ProfileShardResult

ProfileShardResult对象自己包含一个或多个查询配置文件结果，每一个查询一个针对底层Lucene索引执行:

List<QueryProfileShardResult> queryProfileShardResults =
        profileShardResult.getQueryProfileResults(); 
for (QueryProfileShardResult queryProfileResult : queryProfileShardResults) { 

}
  • 检索QueryProfileShardResult的列表
  • 遍历每一个QueryProfileShardResult

每一个QueryProfileShardResult都容许访问详细的查询树执行，以ProfileResult对象列表的形式返回:

for (ProfileResult profileResult : queryProfileResult.getQueryResults()) { 
    String queryName = profileResult.getQueryName(); 
    long queryTimeInMillis = profileResult.getTime(); 
    List<ProfileResult> profiledChildren = profileResult.getProfiledChildren(); 
}
  • 遍历配置文件结果
  • 检索Lucene查询的名称
  • 检索在millis中执行Lucene查询所花费的时间
  • 检索子查询的概要结果(若是有的话)

Rest API文档包含关于分析查询的更多信息，其中描述了查询分析信息。

QueryProfileShardResult还为Lucene收集器提供了对概要信息的访问:

CollectorResult collectorResult = queryProfileResult.getCollectorResult();  
String collectorName = collectorResult.getName();  
Long collectorTimeInMillis = collectorResult.getTime(); 
List<CollectorResult> profiledChildren = collectorResult.getProfiledChildren();
  • 检索Lucene收集器的分析结果
  • 检索Lucene收集器的名称
  • 检索在millis中执行Lucene收集器所花费的时间
  • 检索子收集器的配置文件结果(若是有)

Rest API文档包含关于Lucene收集器的分析信息的更多信息。看到分析查询。

QueryProfileShardResult对象以与查询树执行很是类似的方式访问详细的聚合树执行:

AggregationProfileShardResult aggsProfileResults =
        profileShardResult.getAggregationProfileResults(); 
for (ProfileResult profileResult : aggsProfileResults.getProfileResults()) { 
    String aggName = profileResult.getQueryName(); 
    long aggTimeInMillis = profileResult.getTime(); 
    List<ProfileResult> profiledChildren = profileResult.getProfiledChildren(); 
}
  • 检索AggregationProfileShardResult
  • 遍历聚合配置文件结果
  • 检索聚合的类型(对应于用于执行聚合的Java类)
  • 检索在millis中执行Lucene收集器所花费的时间
  • 检索子聚合的配置文件结果(若是有的话)

注：其它操做请查看https://www.elastic.co/guide/en/elasticsearch/client/java-rest/7.4/java-rest-high-supported-apis.html大同小异。

  • 这里官方说的对于TransportClient，7.0不建议使用，8.0删除

  • IndexRequest构建状况是相同的，区别在于构建IndexResponse，transport使用RequestBuilder的相关prepare遗留方法去构建Response，rest直接使用client的对应方法去返回一个对应的Response。
    好比transportClient.prepareBulk().get()直接变成client.bulk()获得的一样都是BulkResponse；
    prepareSearch变成了search方法

  • 不用Builder怎么执行——直接client执行

    更多请查看博客：https://www.unclewang.info/learn/es/714/，https://segmentfault.com/a/1190000015138673

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程