144 lines
6.0 KiB
Plaintext
144 lines
6.0 KiB
Plaintext
|
[[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
|