mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-03-09 14:34:43 +00:00
075fdc579f
With this new structure supported APIs are ordered and grouped in the same way as they are in the Elasticsearch reference docs
162 lines
6.7 KiB
Plaintext
162 lines
6.7 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
|
|
|
|
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
|