WARNING: Version 2.0 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Get API
editGet API
editThe get API allows to get a typed JSON document from the index based on its id. The following example gets a JSON document from an index called twitter, under a type called tweet, with id valued 1:
curl -XGET 'http://localhost:9200/twitter/tweet/1'
The result of the above get operation is:
{ "_index" : "twitter", "_type" : "tweet", "_id" : "1", "_version" : 1, "found": true, "_source" : { "user" : "kimchy", "postDate" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" } }
The above result includes the _index
, _type
, _id
and _version
of the document we wish to retrieve, including the actual _source
of the document if it could be found (as indicated by the found
field in the response).
The API also allows to check for the existence of a document using
HEAD
, for example:
curl -XHEAD -i 'http://localhost:9200/twitter/tweet/1'
Realtime
editBy default, the get API is realtime, and is not affected by the refresh rate of the index (when data will become visible for search).
In order to disable realtime GET, one can either set realtime
parameter to false
, or globally default it to by setting the
action.get.realtime
to false
in the node configuration.
When getting a document, one can specify fields
to fetch from it. They
will, when possible, be fetched as stored fields (fields mapped as
stored in the mapping). When using realtime GET, there is no notion of
stored fields (at least for a period of time, basically, until the next
flush), so they will be extracted from the source itself (note, even if
source is not enabled). It is a good practice to assume that the fields
will be loaded from source when using realtime GET, even if the fields
are stored.
Optional Type
editThe get API allows for _type
to be optional. Set it to _all
in order
to fetch the first document matching the id across all types.
Source filtering
editBy default, the get operation returns the contents of the _source
field unless
you have used the fields
parameter or if the _source
field is disabled.
You can turn off _source
retrieval by using the _source
parameter:
curl -XGET 'http://localhost:9200/twitter/tweet/1?_source=false'
If you only need one or two fields from the complete _source
, you can use the _source_include
& _source_exclude
parameters to include or filter out that parts you need. This can be especially helpful
with large documents where partial retrieval can save on network overhead. Both parameters take a comma separated list
of fields or wildcard expressions. Example:
curl -XGET 'http://localhost:9200/twitter/tweet/1?_source_include=*.id&_source_exclude=entities'
If you only want to specify includes, you can use a shorter notation:
curl -XGET 'http://localhost:9200/twitter/tweet/1?_source=*.id,retweeted'
Fields
editThe get operation allows specifying a set of stored fields that will be
returned by passing the fields
parameter. For example:
curl -XGET 'http://localhost:9200/twitter/tweet/1?fields=title,content'
For backward compatibility, if the requested fields are not stored, they will be fetched
from the _source
(parsed and extracted). This functionality has been replaced by the
source filtering parameter.
Field values fetched from the document it self are always returned as an array. Metadata fields like _routing
and
_parent
fields are never returned as an array.
Also only leaf fields can be returned via the field
option. So object fields can’t be returned and such requests
will fail.
Generated fields
editIf no refresh occurred between indexing and refresh, GET will access the transaction log to fetch the document. However, some fields are generated only when indexing.
If you try to access a field that is only generated when indexing, you will get an exception (default). You can choose to ignore field that are generated if the transaction log is accessed by setting ignore_errors_on_generated_fields=true
.
Getting the _source directly
editUse the /{index}/{type}/{id}/_source
endpoint to get
just the _source
field of the document,
without any additional content around it. For example:
curl -XGET 'http://localhost:9200/twitter/tweet/1/_source'
You can also use the same source filtering parameters to control which parts of the _source
will be returned:
curl -XGET 'http://localhost:9200/twitter/tweet/1/_source?_source_include=*.id&_source_exclude=entities'
Note, there is also a HEAD variant for the _source endpoint to efficiently test for document existence. Curl example:
curl -XHEAD -i 'http://localhost:9200/twitter/tweet/1/_source'
Routing
editWhen indexing using the ability to control the routing, in order to get a document, the routing value should also be provided. For example:
curl -XGET 'http://localhost:9200/twitter/tweet/1?routing=kimchy'
The above will get a tweet with id 1, but will be routed based on the user. Note, issuing a get without the correct routing, will cause the document not to be fetched.
Preference
editControls a preference
of which shard replicas to execute the get
request on. By default, the operation is randomized between the shard
replicas.
The preference
can be set to:
-
_primary
- The operation will go and be executed only on the primary shards.
-
_local
- The operation will prefer to be executed on a local allocated shard if possible.
- Custom (string) value
- A custom value will be used to guarantee that the same shards will be used for the same custom value. This can help with "jumping values" when hitting different shards in different refresh states. A sample value can be something like the web session id, or the user name.
Refresh
editThe refresh
parameter can be set to true
in order to refresh the
relevant shard before the get operation and make it searchable. Setting
it to true
should be done after careful thought and verification that
this does not cause a heavy load on the system (and slows down
indexing).
Distributed
editThe get operation gets hashed into a specific shard id. It then gets redirected to one of the replicas within that shard id and returns the result. The replicas are the primary shard and its replicas within that shard id group. This means that the more replicas we will have, the better GET scaling we will have.
Versioning support
editYou can use the version
parameter to retrieve the document only if
it’s current version is equal to the specified one. This behavior is the same
for all version types with the exception of version type FORCE
which always
retrieves the document.
Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. The old version of the document doesn’t disappear immediately, although you won’t be able to access it. Elasticsearch cleans up deleted documents in the background as you continue to index more data.