[DOCS] add docs for high level client get method (#25538)
Document high level client get method
This commit is contained in:
Luca Cavanna
GitHub
parent
83522ab4e5
commit
6f8c0453bc
|
|
@ -19,6 +19,8 @@
|
|||
|
||||
package org.elasticsearch.client.documentation;
|
||||
|
||||
import org.apache.http.entity.ContentType;
|
||||
import org.apache.http.nio.entity.NStringEntity;
|
||||
import org.elasticsearch.ElasticsearchException;
|
||||
import org.elasticsearch.action.ActionListener;
|
||||
import org.elasticsearch.action.DocWriteRequest;
|
||||
|
|
@ -28,6 +30,8 @@ import org.elasticsearch.action.bulk.BulkRequest;
|
|||
import org.elasticsearch.action.bulk.BulkResponse;
|
||||
import org.elasticsearch.action.delete.DeleteRequest;
|
||||
import org.elasticsearch.action.delete.DeleteResponse;
|
||||
import org.elasticsearch.action.get.GetRequest;
|
||||
import org.elasticsearch.action.get.GetResponse;
|
||||
import org.elasticsearch.action.index.IndexRequest;
|
||||
import org.elasticsearch.action.index.IndexResponse;
|
||||
import org.elasticsearch.action.support.ActiveShardCount;
|
||||
|
|
@ -36,15 +40,19 @@ import org.elasticsearch.action.support.replication.ReplicationResponse;
|
|||
import org.elasticsearch.action.update.UpdateRequest;
|
||||
import org.elasticsearch.action.update.UpdateResponse;
|
||||
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
|
||||
import org.elasticsearch.client.Response;
|
||||
import org.elasticsearch.client.RestHighLevelClient;
|
||||
import org.elasticsearch.common.Strings;
|
||||
import org.elasticsearch.common.unit.TimeValue;
|
||||
import org.elasticsearch.common.xcontent.XContentBuilder;
|
||||
import org.elasticsearch.common.xcontent.XContentFactory;
|
||||
import org.elasticsearch.common.xcontent.XContentType;
|
||||
import org.elasticsearch.index.VersionType;
|
||||
import org.elasticsearch.rest.RestStatus;
|
||||
import org.elasticsearch.search.fetch.subphase.FetchSourceContext;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.util.Collections;
|
||||
import java.util.Date;
|
||||
import java.util.HashMap;
|
||||
import java.util.Map;
|
||||
|
|
@ -117,7 +125,7 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
|
|||
"\"postDate\":\"2013-01-30\"," +
|
||||
"\"message\":\"trying out Elasticsearch\"" +
|
||||
"}";
|
||||
request.source(jsonString, XContentType.JSON); //<4>
|
||||
request.source(jsonString, XContentType.JSON); // <4>
|
||||
//end::index-request-string
|
||||
|
||||
// tag::index-execute
|
||||
|
|
@ -250,7 +258,7 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
|
|||
long version = deleteResponse.getVersion();
|
||||
ReplicationResponse.ShardInfo shardInfo = deleteResponse.getShardInfo();
|
||||
if (shardInfo.getTotal() != shardInfo.getSuccessful()) {
|
||||
//<1>
|
||||
// <1>
|
||||
}
|
||||
if (shardInfo.getFailed() > 0) {
|
||||
for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) {
|
||||
|
|
@ -362,10 +370,10 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
|
|||
|
||||
if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.INDEX
|
||||
|| bulkItemResponse.getOpType() == DocWriteRequest.OpType.CREATE) { // <3>
|
||||
IndexResponse indexResponse = (IndexResponse)itemResponse;
|
||||
IndexResponse indexResponse = (IndexResponse) itemResponse;
|
||||
|
||||
} else if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.UPDATE) { // <4>
|
||||
UpdateResponse updateResponse = (UpdateResponse)itemResponse;
|
||||
UpdateResponse updateResponse = (UpdateResponse) itemResponse;
|
||||
|
||||
} else if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.DELETE) { // <5>
|
||||
DeleteResponse deleteResponse = (DeleteResponse) itemResponse;
|
||||
|
|
@ -416,4 +424,171 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
|
|||
// end::bulk-execute-async
|
||||
}
|
||||
}
|
||||
|
||||
public void testGet() throws IOException {
|
||||
RestHighLevelClient client = highLevelClient();
|
||||
{
|
||||
String mappings = "{\n" +
|
||||
" \"mappings\" : {\n" +
|
||||
" \"doc\" : {\n" +
|
||||
" \"properties\" : {\n" +
|
||||
" \"message\" : {\n" +
|
||||
" \"type\": \"text\",\n" +
|
||||
" \"store\": true\n" +
|
||||
" }\n" +
|
||||
" }\n" +
|
||||
" }\n" +
|
||||
" }\n" +
|
||||
"}";
|
||||
|
||||
NStringEntity entity = new NStringEntity(mappings, ContentType.APPLICATION_JSON);
|
||||
Response response = client().performRequest("PUT", "/posts", Collections.emptyMap(), entity);
|
||||
assertEquals(200, response.getStatusLine().getStatusCode());
|
||||
|
||||
IndexRequest indexRequest = new IndexRequest("posts", "doc", "1")
|
||||
.source("user", "kimchy",
|
||||
"postDate", new Date(),
|
||||
"message", "trying out Elasticsearch");
|
||||
IndexResponse indexResponse = client.index(indexRequest);
|
||||
assertEquals(indexResponse.getResult(), DocWriteResponse.Result.CREATED);
|
||||
}
|
||||
{
|
||||
//tag::get-request
|
||||
GetRequest getRequest = new GetRequest(
|
||||
"posts", // <1>
|
||||
"doc", // <2>
|
||||
"1"); // <3>
|
||||
//end::get-request
|
||||
|
||||
//tag::get-execute
|
||||
GetResponse getResponse = client.get(getRequest);
|
||||
//end::get-execute
|
||||
assertTrue(getResponse.isExists());
|
||||
assertEquals(3, getResponse.getSourceAsMap().size());
|
||||
//tag::get-response
|
||||
String index = getResponse.getIndex();
|
||||
String type = getResponse.getType();
|
||||
String id = getResponse.getId();
|
||||
if (getResponse.isExists()) {
|
||||
long version = getResponse.getVersion();
|
||||
String sourceAsString = getResponse.getSourceAsString(); // <1>
|
||||
Map<String, Object> sourceAsMap = getResponse.getSourceAsMap(); // <2>
|
||||
byte[] sourceAsBytes = getResponse.getSourceAsBytes(); // <3>
|
||||
} else {
|
||||
// <4>
|
||||
}
|
||||
//end::get-response
|
||||
}
|
||||
{
|
||||
GetRequest request = new GetRequest("posts", "doc", "1");
|
||||
//tag::get-request-no-source
|
||||
request.fetchSourceContext(new FetchSourceContext(false)); // <1>
|
||||
//end::get-request-no-source
|
||||
GetResponse getResponse = client.get(request);
|
||||
assertNull(getResponse.getSourceInternal());
|
||||
}
|
||||
{
|
||||
GetRequest request = new GetRequest("posts", "doc", "1");
|
||||
//tag::get-request-source-include
|
||||
String[] includes = new String[]{"message", "*Date"};
|
||||
String[] excludes = Strings.EMPTY_ARRAY;
|
||||
FetchSourceContext fetchSourceContext = new FetchSourceContext(true, includes, excludes);
|
||||
request.fetchSourceContext(fetchSourceContext); // <1>
|
||||
//end::get-request-source-include
|
||||
GetResponse getResponse = client.get(request);
|
||||
Map<String, Object> sourceAsMap = getResponse.getSourceAsMap();
|
||||
assertEquals(2, sourceAsMap.size());
|
||||
assertEquals("trying out Elasticsearch", sourceAsMap.get("message"));
|
||||
assertTrue(sourceAsMap.containsKey("postDate"));
|
||||
}
|
||||
{
|
||||
GetRequest request = new GetRequest("posts", "doc", "1");
|
||||
//tag::get-request-source-exclude
|
||||
String[] includes = Strings.EMPTY_ARRAY;
|
||||
String[] excludes = new String[]{"message"};
|
||||
FetchSourceContext fetchSourceContext = new FetchSourceContext(true, includes, excludes);
|
||||
request.fetchSourceContext(fetchSourceContext); // <1>
|
||||
//end::get-request-source-exclude
|
||||
GetResponse getResponse = client.get(request);
|
||||
Map<String, Object> sourceAsMap = getResponse.getSourceAsMap();
|
||||
assertEquals(2, sourceAsMap.size());
|
||||
assertEquals("kimchy", sourceAsMap.get("user"));
|
||||
assertTrue(sourceAsMap.containsKey("postDate"));
|
||||
}
|
||||
{
|
||||
GetRequest request = new GetRequest("posts", "doc", "1");
|
||||
//tag::get-request-stored
|
||||
request.storedFields("message"); // <1>
|
||||
GetResponse getResponse = client.get(request);
|
||||
String message = getResponse.getField("message").getValue(); // <2>
|
||||
//end::get-request-stored
|
||||
assertEquals("trying out Elasticsearch", message);
|
||||
assertEquals(1, getResponse.getFields().size());
|
||||
assertNull(getResponse.getSourceInternal());
|
||||
}
|
||||
{
|
||||
GetRequest request = new GetRequest("posts", "doc", "1");
|
||||
//tag::get-request-routing
|
||||
request.routing("routing"); // <1>
|
||||
//end::get-request-routing
|
||||
//tag::get-request-parent
|
||||
request.parent("parent"); // <1>
|
||||
//end::get-request-parent
|
||||
//tag::get-request-preference
|
||||
request.preference("preference"); // <1>
|
||||
//end::get-request-preference
|
||||
//tag::get-request-realtime
|
||||
request.realtime(false); // <1>
|
||||
//end::get-request-realtime
|
||||
//tag::get-request-refresh
|
||||
request.refresh(true); // <1>
|
||||
//end::get-request-refresh
|
||||
//tag::get-request-version
|
||||
request.version(2); // <1>
|
||||
//end::get-request-version
|
||||
//tag::get-request-version-type
|
||||
request.versionType(VersionType.EXTERNAL); // <1>
|
||||
//end::get-request-version-type
|
||||
}
|
||||
{
|
||||
GetRequest request = new GetRequest("posts", "doc", "1");
|
||||
//tag::get-execute-async
|
||||
client.getAsync(request, new ActionListener<GetResponse>() {
|
||||
@Override
|
||||
public void onResponse(GetResponse getResponse) {
|
||||
// <1>
|
||||
}
|
||||
|
||||
@Override
|
||||
public void onFailure(Exception e) {
|
||||
// <2>
|
||||
}
|
||||
});
|
||||
//end::get-execute-async
|
||||
}
|
||||
{
|
||||
//tag::get-indexnotfound
|
||||
GetRequest request = new GetRequest("does_not_exist", "doc", "1");
|
||||
try {
|
||||
GetResponse getResponse = client.get(request);
|
||||
} catch (ElasticsearchException e) {
|
||||
if (e.status() == RestStatus.NOT_FOUND) {
|
||||
// <1>
|
||||
}
|
||||
}
|
||||
//end::get-indexnotfound
|
||||
}
|
||||
{
|
||||
// tag::get-conflict
|
||||
try {
|
||||
GetRequest request = new GetRequest("posts", "doc", "1").version(2);
|
||||
GetResponse getResponse = client.get(request);
|
||||
} catch (ElasticsearchException exception) {
|
||||
if (exception.status() == RestStatus.CONFLICT) {
|
||||
// <1>
|
||||
}
|
||||
}
|
||||
// end::get-conflict
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ The Java High Level REST Client supports the following APIs:
|
|||
|
||||
* <<java-rest-high-document-index>>
|
||||
|
||||
* Get API
|
||||
* <<java-rest-high-document-get>>
|
||||
|
||||
* <<java-rest-high-document-delete>>
|
||||
|
||||
|
|
|
|||
|
|
@ -109,8 +109,8 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute]
|
|||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute-async]
|
||||
--------------------------------------------------
|
||||
<1> Called when the execution is successfully completed. The response is
|
||||
provided as an argument.
|
||||
<2> Called in case of failure. The raised exception is provided as an argument.
|
||||
provided as an argument
|
||||
<2> Called in case of failure. The raised exception is provided as an argument
|
||||
|
||||
[[java-rest-high-document-index-response]]
|
||||
==== Index Response
|
||||
|
|
@ -137,7 +137,7 @@ be thrown:
|
|||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-conflict]
|
||||
--------------------------------------------------
|
||||
<1> The raised exception indicates that a version conflict error was returned.
|
||||
<1> The raised exception indicates that a version conflict error was returned
|
||||
|
||||
Same will happen in case `opType` was set to `create` and a document with
|
||||
same index, type and id already existed:
|
||||
|
|
@ -146,6 +146,6 @@ same index, type and id already existed:
|
|||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-optype]
|
||||
--------------------------------------------------
|
||||
<1> The raised exception indicates that a version conflict error was returned.
|
||||
<1> The raised exception indicates that a version conflict error was returned
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -71,8 +71,8 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute]
|
|||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute-async]
|
||||
--------------------------------------------------
|
||||
<1> Called when the execution is successfully completed. The response is
|
||||
provided as an argument.
|
||||
<2> Called in case of failure. The raised exception is provided as an argument.
|
||||
provided as an argument
|
||||
<2> Called in case of failure. The raised exception is provided as an argument
|
||||
|
||||
[[java-rest-high-document-delete-response]]
|
||||
==== Delete Response
|
||||
|
|
@ -104,5 +104,5 @@ be thrown:
|
|||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-conflict]
|
||||
--------------------------------------------------
|
||||
<1> The raised exception indicates that a version conflict error was returned.
|
||||
<1> The raised exception indicates that a version conflict error was returned
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,143 @@
|
|||
[[java-rest-high-document-get]]
|
||||
=== Get API
|
||||
|
||||
[[java-rest-high-document-get-request]]
|
||||
==== Get Request
|
||||
|
||||
A `GetRequest` requires the following arguments:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request]
|
||||
--------------------------------------------------
|
||||
<1> Index
|
||||
<2> Type
|
||||
<3> Document id
|
||||
|
||||
==== Optional arguments
|
||||
The following arguments can optionally be provided:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-no-source]
|
||||
--------------------------------------------------
|
||||
<1> Disable source retrieval, enabled by default
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-source-include]
|
||||
--------------------------------------------------
|
||||
<1> Configure source inclusion for specific fields
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-source-exclude]
|
||||
--------------------------------------------------
|
||||
<1> Configure source exclusion for specific fields
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-stored]
|
||||
--------------------------------------------------
|
||||
<1> Configure retrieval for specific stored fields (requires fields to be
|
||||
stored separately in the mappings)
|
||||
<2> Retrieve the `message` stored field (requires the field to be stored
|
||||
separately in the mappings)
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-routing]
|
||||
--------------------------------------------------
|
||||
<1> Routing value
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-parent]
|
||||
--------------------------------------------------
|
||||
<1> Parent value
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-preference]
|
||||
--------------------------------------------------
|
||||
<1> Preference value
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-realtime]
|
||||
--------------------------------------------------
|
||||
<1> Set realtime flag to `false` (`true` by default)
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-refresh]
|
||||
--------------------------------------------------
|
||||
<1> Perform a refresh before retrieving the document (`false` by default)
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-version]
|
||||
--------------------------------------------------
|
||||
<1> Version
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-version-type]
|
||||
--------------------------------------------------
|
||||
<1> Version type
|
||||
|
||||
[[java-rest-high-document-get-sync]]
|
||||
==== Synchronous Execution
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-execute]
|
||||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-document-get-async]]
|
||||
==== Asynchronous Execution
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-execute-async]
|
||||
--------------------------------------------------
|
||||
<1> Called when the execution is successfully completed. The response is
|
||||
provided as an argument.
|
||||
<2> Called in case of failure. The raised exception is provided as an argument.
|
||||
|
||||
[[java-rest-high-document-get-response]]
|
||||
==== Get Response
|
||||
|
||||
The returned `GetResponse` allows to retrieve the requested document along with
|
||||
its metadata and eventually stored fields.
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-response]
|
||||
--------------------------------------------------
|
||||
<1> Retrieve the document as a `String`
|
||||
<2> Retrieve the document as a `Map<String, Object>`
|
||||
<3> Retrieve the document as a `byte[]`
|
||||
<4> Handle the scenario where the document was not found. Note that although
|
||||
the returned response has `404` status code, a valid `GetResponse` is
|
||||
returned rather than an exception thrown. Such response does not hold any
|
||||
source document and its `isExists` method returns `false`.
|
||||
|
||||
When a get request is performed against an index that does not exist, the
|
||||
response has `404` status code, an `ElasticsearchException` gets thrown
|
||||
which needs to be handled as follows:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-indexnotfound]
|
||||
--------------------------------------------------
|
||||
<1> Handle the exception thrown because the index does not exist
|
||||
|
||||
In case a specific document version has been requested, and the existing
|
||||
document has a different version number, a version conflict is raised:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-conflict]
|
||||
--------------------------------------------------
|
||||
<1> The raised exception indicates that a version conflict error was returned
|
||||
|
|
@ -2,6 +2,7 @@
|
|||
|
||||
include::_index.asciidoc[]
|
||||
include::update.asciidoc[]
|
||||
include::get.asciidoc[]
|
||||
include::delete.asciidoc[]
|
||||
include::bulk.asciidoc[]
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue