- Elasticsearch Guide: other versions:
- Setup
- API Conventions
- Document APIs
- Search APIs
- Indices APIs
- Create Index
- Delete Index
- Indices Exists
- Open / Close Index API
- Put Mapping
- Get Mapping
- Get Field Mapping
- Types Exists
- Delete Mapping
- Index Aliases
- Update Indices Settings
- Get Settings
- Analyze
- Index Templates
- Warmers
- Status
- Indices Stats
- Indices Segments
- Clear Cache
- Flush
- Refresh
- Optimize
- Gateway Snapshot
- Cluster APIs
- Query DSL
- Queries
- Match Query
- Multi Match Query
- Bool Query
- Boosting Query
- Common Terms Query
- Custom Filters Score Query
- Custom Score Query
- Custom Boost Factor Query
- Constant Score Query
- Dis Max Query
- Field Query
- Filtered Query
- Fuzzy Like This Query
- Fuzzy Like This Field Query
- Function Score Query
- Fuzzy Query
- GeoShape Query
- Has Child Query
- Has Parent Query
- Ids Query
- Indices Query
- Match All Query
- More Like This Query
- More Like This Field Query
- Nested Query
- Prefix Query
- Query String Query
- Simple Query String Query
- Range Query
- Regexp Query
- Span First Query
- Span Multi Term Query
- Span Near Query
- Span Not Query
- Span Or Query
- Span Term Query
- Term Query
- Terms Query
- Top Children Query
- Wildcard Query
- Text Query
- Minimum Should Match
- Multi Term Query Rewrite
- Filters
- And Filter
- Bool Filter
- Exists Filter
- Geo Bounding Box Filter
- Geo Distance Filter
- Geo Distance Range Filter
- Geo Polygon Filter
- GeoShape Filter
- Geohash Cell Filter
- Has Child Filter
- Has Parent Filter
- Ids Filter
- Indices Filter
- Limit Filter
- Match All Filter
- Missing Filter
- Nested Filter
- Not Filter
- Numeric Range Filter
- Or Filter
- Prefix Filter
- Query Filter
- Range Filter
- Regexp Filter
- Script Filter
- Term Filter
- Terms Filter
- Type Filter
- Queries
- Mapping
- Analysis
- Analyzers
- Tokenizers
- Token Filters
- Standard Token Filter
- ASCII Folding Token Filter
- Length Token Filter
- Lowercase Token Filter
- NGram Token Filter
- Edge NGram Token Filter
- Porter Stem Token Filter
- Shingle Token Filter
- Stop Token Filter
- Word Delimiter Token Filter
- Stemmer Token Filter
- Stemmer Override Token Filter
- Keyword Marker Token Filter
- Keyword Repeat Token Filter
- KStem Token Filter
- Snowball Token Filter
- Phonetic Token Filter
- Synonym Token Filter
- Compound Word Token Filter
- Reverse Token Filter
- Elision Token Filter
- Truncate Token Filter
- Unique Token Filter
- Pattern Capture Token Filter
- Pattern Replace Token Filter
- Trim Token Filter
- Limit Token Count Token Filter
- Hunspell Token Filter
- Common Grams Token Filter
- Normalization Token Filter
- Keep Words Token Filter
- Delimited Payload Token Filter
- Character Filters
- ICU Analysis Plugin
- Modules
- Index Modules
- Glossary of terms
WARNING: Version 0.90 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 "_source" : { "user" : "kimchy", "postDate" : "2009-11-15T14:12:12", "message" : "trying out Elastic Search" } }
The above result includes the _index
, _type
, _id
and the
version
of the document we wish to retrieve, including the
actual _source
of the document if it was found.
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.
Fields
editThe get operation allows specifying a set of fields that will be
returned (by default, the _source
field) by passing the fields
parameter. For example:
curl -XGET 'http://localhost:9200/twitter/tweet/1?fields=title,content'
The returned fields will either be loaded if they are stored, or fetched
from the _source
(parsed and extracted). It also supports sub objects
extraction from _source, like obj1.obj2
.
Getting the _source directly
editSince version 0.90.1
there is a new rest end point that allows the
source to be returned directly without any additional content around it.
The get endpoint has the following structure:
{index}/{type}/{id}/_source
. Curl example:
curl -XGET 'http://localhost:9200/twitter/tweet/1/_source'
Note, there is also a HEAD variant for the new _source endpoint. 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.
On this page