OpenSearch/docs/java-rest/high-level/document/get.asciidoc

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

[[java-rest-high-document-get-request-optional-arguments]]
==== 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-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

The asynchronous execution of a get request requires both the `GetRequest`
instance and an `ActionListener` instance to be passed to the asynchronous
method:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-execute-async]
--------------------------------------------------
<1> The `GetRequest` to execute and the `ActionListener` to use when
the execution completes

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.

A typical listener for `GetResponse` looks like:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-execute-listener]
--------------------------------------------------
<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