[[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