[[java-rest-high-document-multi-get]] === Multi-Get API The `multiGet` API executes multiple <> 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 <> 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> Version <3> 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 <> 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` <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, `