mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
Docs: HighLevelRestClient#multiGet (#29095)
Add documentation for HighLevelRestClient#multiGet. Relates to #28389.
This commit is contained in:
Nik Everett
GitHub
parent
60cb476cc9
commit
2f21dc7129
3 changed files with 377 additions and 1 deletions
168
docs/java-rest/high-level/document/multi-get.asciidoc
Normal file
168
docs/java-rest/high-level/document/multi-get.asciidoc
Normal file
|
|
@ -0,0 +1,168 @@
|
|||
[[java-rest-high-document-multi-get]]
|
||||
=== Multi-Get API
|
||||
|
||||
The `multiGet` API executes multiple <<java-rest-high-document-get,`get`>>
|
||||
requests in a single http request in parallel.
|
||||
|
||||
[[java-rest-high-document-mulit-get-request]]
|
||||
==== Multi-Get Request
|
||||
|
||||
A `MultiGetRequest` is built empty and you add `MultiGetRequest.Item`s to
|
||||
configure what to fetch:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request]
|
||||
--------------------------------------------------
|
||||
<1> Index
|
||||
<2> Type
|
||||
<3> Document id
|
||||
<4> Add another item to fetch
|
||||
|
||||
==== Optional arguments
|
||||
|
||||
`multiGet` supports the same optional arguments that the
|
||||
<<java-rest-high-document-get-request-optional-arguments,`get` API>> supports.
|
||||
You can set most of these on the `Item`:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request-no-source]
|
||||
--------------------------------------------------
|
||||
<1> Disable source retrieval, enabled by default
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request-source-include]
|
||||
--------------------------------------------------
|
||||
<1> Configure source inclusion for specific fields
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request-source-exclude]
|
||||
--------------------------------------------------
|
||||
<1> Configure source exclusion for specific fields
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request-stored]
|
||||
--------------------------------------------------
|
||||
<1> Configure retrieval for specific stored fields (requires fields to be
|
||||
stored separately in the mappings)
|
||||
<2> Retrieve the `foo` stored field (requires the field to be stored
|
||||
separately in the mappings)
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request-item-extras]
|
||||
--------------------------------------------------
|
||||
<1> Routing value
|
||||
<2> Parent value
|
||||
<3> Version
|
||||
<4> Version type
|
||||
|
||||
{ref}/search-request-preference.html[`preference`],
|
||||
{ref}/docs-get.html#realtime[`realtime`]
|
||||
and
|
||||
{ref}/docs-get.html#get-refresh[`refresh`] can be set on the main request but
|
||||
not on any items:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request-top-level-extras]
|
||||
--------------------------------------------------
|
||||
<1> Preference value
|
||||
<2> Set realtime flag to `false` (`true` by default)
|
||||
<3> Perform a refresh before retrieving the document (`false` by default)
|
||||
|
||||
[[java-rest-high-document-multi-get-sync]]
|
||||
==== Synchronous Execution
|
||||
|
||||
After building the `MultiGetRequest` you can execute it synchronously with
|
||||
`multiGet`:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-execute]
|
||||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-document-multi-get-async]]
|
||||
==== Asynchronous Execution
|
||||
|
||||
The asynchronous execution of a multi get request requires both the
|
||||
`MultiGetRequest` instance and an `ActionListener` instance to be passed to
|
||||
the asynchronous method:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-execute-async]
|
||||
--------------------------------------------------
|
||||
<1> The `MultiGetRequest` to execute and the `ActionListener` to use when
|
||||
the execution completes.
|
||||
|
||||
The asynchronous method does not block and returns immediately. Once the
|
||||
request 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 `MultiGetResponse` looks like:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-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-multi-get-response]]
|
||||
==== Multi Get Response
|
||||
|
||||
The returned `MultiGetResponse` contains a list of `MultiGetItemResponse`s in
|
||||
`getResponses` in the same order that they were requested.
|
||||
`MultiGetItemResponse` contains *either* a
|
||||
<<java-rest-high-document-get-response, `GetResponse`>> if the get succeeded
|
||||
or a `MultiGetResponse.Failure` if it failed. A success looks just like a
|
||||
normal `GetResponse`.
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-response]
|
||||
--------------------------------------------------
|
||||
<1> `getFailure` returns null because there isn't a failure.
|
||||
<2> `getResponse` returns the `GetResponse`.
|
||||
<3> Retrieve the document as a `String`
|
||||
<4> Retrieve the document as a `Map<String, Object>`
|
||||
<5> Retrieve the document as a `byte[]`
|
||||
<6> 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 one of the subrequests as performed against an index that does not exist
|
||||
`getFailure` will contain an exception:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-indexnotfound]
|
||||
--------------------------------------------------
|
||||
<1> `getResponse` is null.
|
||||
<2> `getFailure` isn't and contains an `Exception`.
|
||||
<3> That `Exception` is actually an `ElasticsearchException`
|
||||
<4> and it has a status of `NOT_FOUND`. It'd have been an HTTP 404 if this
|
||||
wasn't a multi get.
|
||||
<5> `getMessage` explains the actual cause, `no such index`.
|
||||
|
||||
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[multi-get-conflict]
|
||||
--------------------------------------------------
|
||||
<1> `getResponse` is null.
|
||||
<2> `getFailure` isn't and contains an `Exception`.
|
||||
<3> That `Exception` is actuall and `ElasticsearchException`
|
||||
<4> and it has a status of `CONFLICT`. It'd have been an HTTP 409 if this
|
||||
wasn't a multi get.
|
||||
<5> `getMessage` explains the actual cause, `
|
||||
|
|
@ -14,6 +14,7 @@ Single document APIs::
|
|||
[[multi-doc]]
|
||||
Multi-document APIs::
|
||||
* <<java-rest-high-document-bulk>>
|
||||
* <<java-rest-high-document-multi-get>>
|
||||
|
||||
include::document/index.asciidoc[]
|
||||
include::document/get.asciidoc[]
|
||||
|
|
@ -21,6 +22,7 @@ include::document/exists.asciidoc[]
|
|||
include::document/delete.asciidoc[]
|
||||
include::document/update.asciidoc[]
|
||||
include::document/bulk.asciidoc[]
|
||||
include::document/multi-get.asciidoc[]
|
||||
|
||||
== Search APIs
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue