From 6f8c0453bc064bd33feb5cb57b3c09dacb087ccd Mon Sep 17 00:00:00 2001 From: Luca Cavanna Date: Wed, 5 Jul 2017 11:57:57 +0200 Subject: [PATCH] [DOCS] add docs for high level client get method (#25538) Document high level client get method --- .../documentation/CRUDDocumentationIT.java | 183 +++++++++++++++++- docs/java-rest/high-level/apis.asciidoc | 2 +- .../java-rest/high-level/apis/_index.asciidoc | 8 +- .../java-rest/high-level/apis/delete.asciidoc | 6 +- docs/java-rest/high-level/apis/get.asciidoc | 143 ++++++++++++++ docs/java-rest/high-level/apis/index.asciidoc | 1 + 6 files changed, 331 insertions(+), 12 deletions(-) create mode 100644 docs/java-rest/high-level/apis/get.asciidoc diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java index 661d30925d4..e35e17da588 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java @@ -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 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 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 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() { + @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 + } + } } diff --git a/docs/java-rest/high-level/apis.asciidoc b/docs/java-rest/high-level/apis.asciidoc index 7693dd13ce6..49fc8c0b543 100644 --- a/docs/java-rest/high-level/apis.asciidoc +++ b/docs/java-rest/high-level/apis.asciidoc @@ -4,7 +4,7 @@ The Java High Level REST Client supports the following APIs: * <> -* Get API +* <> * <> diff --git a/docs/java-rest/high-level/apis/_index.asciidoc b/docs/java-rest/high-level/apis/_index.asciidoc index 76ce8e46b49..9600f7cad43 100644 --- a/docs/java-rest/high-level/apis/_index.asciidoc +++ b/docs/java-rest/high-level/apis/_index.asciidoc @@ -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 diff --git a/docs/java-rest/high-level/apis/delete.asciidoc b/docs/java-rest/high-level/apis/delete.asciidoc index 24a085acc39..5b71f6214a5 100644 --- a/docs/java-rest/high-level/apis/delete.asciidoc +++ b/docs/java-rest/high-level/apis/delete.asciidoc @@ -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 diff --git a/docs/java-rest/high-level/apis/get.asciidoc b/docs/java-rest/high-level/apis/get.asciidoc new file mode 100644 index 00000000000..af1d64fa2a0 --- /dev/null +++ b/docs/java-rest/high-level/apis/get.asciidoc @@ -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` +<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 diff --git a/docs/java-rest/high-level/apis/index.asciidoc b/docs/java-rest/high-level/apis/index.asciidoc index 475b18dcf44..935a4ff5494 100644 --- a/docs/java-rest/high-level/apis/index.asciidoc +++ b/docs/java-rest/high-level/apis/index.asciidoc @@ -2,6 +2,7 @@ include::_index.asciidoc[] include::update.asciidoc[] +include::get.asciidoc[] include::delete.asciidoc[] include::bulk.asciidoc[]