296 lines
7.8 KiB
Plaintext
296 lines
7.8 KiB
Plaintext
[[docs-multi-get]]
|
|
=== Multi get (mget) API
|
|
++++
|
|
<titleabbrev>Multi get</titleabbrev>
|
|
++++
|
|
|
|
Retrieves multiple JSON documents by ID.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_mget
|
|
{
|
|
"docs" : [
|
|
{
|
|
"_index" : "twitter",
|
|
"_id" : "1"
|
|
},
|
|
{
|
|
"_index" : "twitter",
|
|
"_id" : "2"
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[setup:twitter]
|
|
|
|
[[docs-multi-get-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_mget`
|
|
|
|
`GET /<index>/_mget`
|
|
|
|
[[docs-multi-get-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
You use `mget` to retrieve multiple documents from one or more indices.
|
|
If you specify an index in the request URI, you only need to specify the document IDs in the request body.
|
|
|
|
[[mget-security]]
|
|
===== Security
|
|
|
|
See <<url-access-control>>.
|
|
|
|
[[multi-get-partial-responses]]
|
|
===== Partial responses
|
|
|
|
To ensure fast responses, the multi get API responds with partial results if one or more shards fail.
|
|
See <<shard-failures, Shard failures>> for more information.
|
|
|
|
[[docs-multi-get-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<index>`::
|
|
(Optional, string) Name of the index to retrieve documents from when `ids` are specified,
|
|
or when a document in the `docs` array does not specify an index.
|
|
|
|
[[docs-multi-get-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=preference]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=realtime]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=refresh]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=stored_fields]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=source]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes]
|
|
|
|
[[docs-multi-get-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
`docs`::
|
|
(Optional, array) The documents you want to retrieve.
|
|
Required if no index is specified in the request URI.
|
|
You can specify the following attributes for each
|
|
document:
|
|
+
|
|
--
|
|
`_id`::
|
|
(Required, string) The unique document ID.
|
|
|
|
`_index`::
|
|
(Optional, string)
|
|
The index that contains the document.
|
|
Required if no index is specified in the request URI.
|
|
|
|
`_routing`::
|
|
(Optional, string) The key for the primary shard the document resides on.
|
|
Required if routing is used during indexing.
|
|
|
|
`_source`::
|
|
(Optional, boolean) If `false`, excludes all `_source` fields. Defaults to `true`.
|
|
`source_include`:::
|
|
(Optional, array) The fields to extract and return from the `_source` field.
|
|
`source_exclude`:::
|
|
(Optional, array) The fields to exclude from the returned `_source` field.
|
|
|
|
`_stored_fields`::
|
|
(Optional, array) The stored fields you want to retrieve.
|
|
--
|
|
|
|
`ids`::
|
|
(Optional, array) The IDs of the documents you want to retrieve.
|
|
Allowed when the index is specified in the request URI.
|
|
|
|
[[multi-get-api-response-body]]
|
|
==== {api-response-body-title}
|
|
|
|
The response includes a `docs` array that contains the documents in the order specified in the request.
|
|
The structure of the returned documents is similar to that returned by the <<docs-get,get>> API.
|
|
If there is a failure getting a particular document, the error is included in place of the document.
|
|
|
|
[[docs-multi-get-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
[[mget-ids]]
|
|
===== Get documents by ID
|
|
|
|
If you specify an index in the request URI, only the document IDs are required in the request body:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /twitter/_mget
|
|
{
|
|
"docs" : [
|
|
{
|
|
"_type" : "_doc",
|
|
"_id" : "1"
|
|
},
|
|
{
|
|
"_type" : "_doc",
|
|
"_id" : "2"
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
And type:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /test/_doc/_mget
|
|
{
|
|
"docs" : [
|
|
{
|
|
"_id" : "1"
|
|
},
|
|
{
|
|
"_id" : "2"
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[setup:twitter]
|
|
|
|
You can use the `ids` element to simplify the request:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /twitter/_mget
|
|
{
|
|
"ids" : ["1", "2"]
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[setup:twitter]
|
|
|
|
[[mget-source-filtering]]
|
|
===== Filter source fields
|
|
|
|
By default, the `_source` field is returned for every document (if stored).
|
|
Use the `_source` and `_source_include` or `source_exclude` attributes to
|
|
filter what fields are returned for a particular document.
|
|
You can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the
|
|
request URI to specify the defaults to use when there are no per-document instructions.
|
|
|
|
For example, the following request sets `_source` to false for document 1 to exclude the
|
|
source entirely, retrieves `field3` and `field4` from document 2, and retrieves the `user` field
|
|
from document 3 but filters out the `user.location` field.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_mget
|
|
{
|
|
"docs" : [
|
|
{
|
|
"_index" : "test",
|
|
"_type" : "_doc",
|
|
"_id" : "1",
|
|
"_source" : false
|
|
},
|
|
{
|
|
"_index" : "test",
|
|
"_type" : "_doc",
|
|
"_id" : "2",
|
|
"_source" : ["field3", "field4"]
|
|
},
|
|
{
|
|
"_index" : "test",
|
|
"_type" : "_doc",
|
|
"_id" : "3",
|
|
"_source" : {
|
|
"include": ["user"],
|
|
"exclude": ["user.location"]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[mget-fields]]
|
|
===== Get stored fields
|
|
|
|
Use the `stored_fields` attribute to specify the set of stored fields you want
|
|
to retrieve. Any requested fields that are not stored are ignored.
|
|
You can include the `stored_fields` query parameter in the request URI to specify the defaults
|
|
to use when there are no per-document instructions.
|
|
|
|
For example, the following request retrieves `field1` and `field2` from document 1, and
|
|
`field3` and `field4`from document 2:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_mget
|
|
{
|
|
"docs" : [
|
|
{
|
|
"_index" : "test",
|
|
"_type" : "_doc",
|
|
"_id" : "1",
|
|
"stored_fields" : ["field1", "field2"]
|
|
},
|
|
{
|
|
"_index" : "test",
|
|
"_type" : "_doc",
|
|
"_id" : "2",
|
|
"stored_fields" : ["field3", "field4"]
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
The following request retrieves `field1` and `field2` from all documents by default.
|
|
These default fields are returned for document 1, but
|
|
overridden to return `field3` and `field4` for document 2.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /test/_doc/_mget?stored_fields=field1,field2
|
|
{
|
|
"docs" : [
|
|
{
|
|
"_id" : "1"
|
|
},
|
|
{
|
|
"_id" : "2",
|
|
"stored_fields" : ["field3", "field4"]
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[mget-routing]]
|
|
===== Specify document routing
|
|
|
|
If routing is used during indexing, you need to specify the routing value to retrieve documents.
|
|
For example, the following request fetches `test/_doc/2` from the shard corresponding to routing key `key1`,
|
|
and fetches `test/_doc/1` from the shard corresponding to routing key `key2`.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_mget?routing=key1
|
|
{
|
|
"docs" : [
|
|
{
|
|
"_index" : "test",
|
|
"_type" : "_doc",
|
|
"_id" : "1",
|
|
"routing" : "key2"
|
|
},
|
|
{
|
|
"_index" : "test",
|
|
"_type" : "_doc",
|
|
"_id" : "2"
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|