mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-07 21:48:39 +00:00
6fd7ea71f1
This further applies the pattern set in #34125 to reduce copy-and-paste in the multi-document CRUD portion of the High Level REST Client docs. It also adds line wraps to snippets that are too wide to fit into the box when rendered in the docs, following up on the work started in #34163.
136 lines
5.2 KiB
Plaintext
136 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> 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-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 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, `
|