135 lines
5.2 KiB
Plaintext
135 lines
5.2 KiB
Plaintext
--
|
|
:api: multi-get
|
|
:request: MultiGetRequest
|
|
:response: MultiGetResponse
|
|
--
|
|
|
|
[id="{upid}-{api}"]
|
|
=== Multi-Get API
|
|
|
|
The `multiGet` API executes multiple <<java-rest-high-document-get,`get`>>
|
|
requests in a single http request in parallel.
|
|
|
|
[id="{upid}-{api}-request"]
|
|
==== Multi-Get Request
|
|
|
|
A +{request}+ is built empty and you add `MultiGetRequest.Item`s to configure
|
|
what to fetch:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests-file}[{api}-request]
|
|
--------------------------------------------------
|
|
<1> Index
|
|
<2> Document id
|
|
<3> 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-file}[{api}-request-no-source]
|
|
--------------------------------------------------
|
|
<1> Disable source retrieval, enabled by default
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests-file}[{api}-request-source-include]
|
|
--------------------------------------------------
|
|
<1> Configure source inclusion for specific fields
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests-file}[{api}-request-source-exclude]
|
|
--------------------------------------------------
|
|
<1> Configure source exclusion for specific fields
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests-file}[{api}-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-file}[{api}-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-file}[{api}-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)
|
|
|
|
include::../execution.asciidoc[]
|
|
|
|
[id="{upid}-{api}-response"]
|
|
==== Multi Get Response
|
|
|
|
The returned +{response}+ 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-file}[{api}-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-file}[{api}-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-file}[{api}-conflict]
|
|
--------------------------------------------------
|
|
<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 `CONFLICT`. It'd have been an HTTP 409 if this
|
|
wasn't a multi get.
|
|
<5> `getMessage` explains the actual cause, `
|