Elasticsearch 7 Java High Level REST Client

古城微笑少年丶 2023-06-11 12:27 5阅读 0赞

新的api包含多种文档的创建方式：

1.  字符串形式
2.  以Map形式提供的文档源，可自动转换为JSON格式
3.  使用XConttentBuilder构建内容
4.  直接用键值对对象构建数据
5.  同步方式
6.  异步方式

An `IndexRequest` requires the following arguments:

IndexRequest request = new IndexRequest("posts"); 
    request.id("1"); 
    String jsonString = "{" +
            "\"user\":\"kimchy\"," +
            "\"postDate\":\"2013-01-30\"," +
            "\"message\":\"trying out Elasticsearch\"" +
            "}";
    request.source(jsonString, XContentType.JSON);

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Index</p> </td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Document id for the request</p> </td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Document source provided as a&nbsp;<code>String</code></p> </td> 
  </tr> 
 </tbody> 
</table>

### Providing the document source ###

The document source can be provided in different ways in addition to the `String` example shown above:

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")
        .id("1").source(jsonMap);

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Document source provided as a&nbsp;<code>Map</code>&nbsp;which gets automatically converted to JSON format</p> </td> 
  </tr> 
 </tbody> 
</table>

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")
        .id("1").source(builder);

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Document source provided as an&nbsp;<code>XContentBuilder</code>&nbsp;object, the Elasticsearch built-in helpers to generate JSON content</p> </td> 
  </tr> 
 </tbody> 
</table>

IndexRequest indexRequest = new IndexRequest("posts")
        .id("1")
        .source("user", "kimchy",
            "postDate", new Date(),
            "message", "trying out Elasticsearch");

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Document source provided as&nbsp;<code>Object</code>&nbsp;key-pairs, which gets converted to JSON format</p> </td> 
  </tr> 
 </tbody> 
</table>

### Optional arguments ###

The following arguments can optionally be provided:

request.routing("routing");

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Routing value</p> </td> 
  </tr> 
 </tbody> 
</table>

request.timeout(TimeValue.timeValueSeconds(1)); 
    request.timeout("1s");

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Timeout to wait for primary shard to become available as a&nbsp;<code>TimeValue</code></p> </td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Timeout to wait for primary shard to become available as a&nbsp;<code>String</code></p> </td> 
  </tr> 
 </tbody> 
</table>

request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL); 
    request.setRefreshPolicy("wait_for");

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Refresh policy as a&nbsp;<code>WriteRequest.RefreshPolicy</code>&nbsp;instance</p> </td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Refresh policy as a&nbsp;<code>String</code></p> </td> 
  </tr> 
 </tbody> 
</table>

request.version(2);

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Version</p> </td> 
  </tr> 
 </tbody> 
</table>

request.versionType(VersionType.EXTERNAL);

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Version type</p> </td> 
  </tr> 
 </tbody> 
</table>

request.opType(DocWriteRequest.OpType.CREATE); 
    request.opType("create");

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Operation type provided as an&nbsp;<code>DocWriteRequest.OpType</code>&nbsp;value</p> </td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Operation type provided as a&nbsp;<code>String</code>: can be&nbsp;<code>create</code>&nbsp;or&nbsp;<code>index</code>&nbsp;(default)</p> </td> 
  </tr> 
 </tbody> 
</table>

request.setPipeline("pipeline");

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>The name of the ingest pipeline to be executed before indexing the document</p> </td> 
  </tr> 
 </tbody> 
</table>

### Synchronous Execution ###

When executing a `IndexRequest` in the following manner, the client waits for the `IndexResponse` to be returned before continuing with code execution:

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

Synchronous calls may throw an `IOException` in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a `4xx` or `5xx` error code, the high-level client tries to parse the response body error details instead and then throws a generic `ElasticsearchException` and adds the original `ResponseException` as a suppressed exception to it.

### Asynchronous Execution ###

Executing a `IndexRequest` can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous index method:

client.indexAsync(request, RequestOptions.DEFAULT, listener);

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>The&nbsp;<code>IndexRequest</code>&nbsp;to execute and the&nbsp;<code>ActionListener</code>&nbsp;to use when the execution completes</p> </td> 
  </tr> 
 </tbody> 
</table>

The asynchronous method does not block and returns immediately. Once it is completed the `ActionListener` is called back using the `onResponse` method if the execution successfully completed or using the `onFailure` method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for `index` looks like:

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

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Called when the execution is successfully completed.</p> </td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Called when the whole&nbsp;<code>IndexRequest</code>&nbsp;fails.</p> </td> 
  </tr> 
 </tbody> 
</table>

### Index Response ###

The returned `IndexResponse` allows to retrieve information about the executed operation as follows:

String index = indexResponse.getIndex();
    String id = indexResponse.getId();
    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(); 
        }
    }

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Handle (if needed) the case where the document was created for the first time</p> </td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Handle (if needed) the case where the document was rewritten as it was already existing</p> </td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Handle the situation where number of successful shards is less than total shards</p> </td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>Handle the potential failures</p> </td> 
  </tr> 
 </tbody> 
</table>

If there is a version conflict, an `ElasticsearchException` will be thrown:

IndexRequest request = new IndexRequest("posts")
        .id("1")
        .source("field", "value")
        .setIfSeqNo(10L)
        .setIfPrimaryTerm(20);
    try {
        IndexResponse response = client.index(request, RequestOptions.DEFAULT);
    } catch(ElasticsearchException e) {
        if (e.status() == RestStatus.CONFLICT) {
            
        }
    }

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> <p>&nbsp;</p> </td> 
   <td style="vertical-align:top;"> <p>The raised exception indicates that a version conflict error was returned</p> </td> 
  </tr> 
 </tbody> 
</table>

Same will happen in case `opType` was set to `create` and a document with same index and id already existed:

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