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.
Scroll
editScroll
editWhile a search
request returns a single “page” of results, the scroll
API can be used to retrieve large numbers of results (or even all results)
from a single search request, in much the same way as you would use a cursor
on a traditional database.
Scrolling is not intended for real time user requests, but rather for processing large amounts of data, e.g. in order to reindex the contents of one index into a new index with a different configuration.
The results that are returned from a scroll request reflect the state of
the index at the time that the initial search
request was made, like a
snapshot in time. Subsequent changes to documents (index, update or delete)
will only affect later search requests.
In order to use scrolling, the initial search request should specify the
scroll
parameter in the query string, which tells Elasticsearch how long it
should keep the “search context” alive (see Keeping the search context alive), eg ?scroll=1m
.
curl -XGET 'localhost:9200/twitter/tweet/_search?scroll=1m' -d ' { "query": { "match" : { "title" : "elasticsearch" } } } '
The result from the above request includes a _scroll_id
, which should
be passed to the scroll
API in order to retrieve the next batch of
results.
curl -XGET 'localhost:9200/_search/scroll' -d' { "scroll" : "1m", "scroll_id" : "c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1" } '
Added in 2.0.0-beta1.
body based parameters were added in 2.0.0
|
|
The |
|
The |
Each call to the scroll
API returns the next batch of results until there
are no more results left to return, ie the hits
array is empty.
For backwards compatibility, scroll_id
and scroll
can be passed in the query string.
And the scroll_id
can be passed in the request body
curl -XGET 'localhost:9200/_search/scroll?scroll=1m' -d 'c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1'
The initial search request and each subsequent scroll request
returns a new _scroll_id
— only the most recent _scroll_id
should be
used.
If the request specifies aggregations, only the initial search response will contain the aggregations results.
Efficient scrolling with Scroll-Scan
editDeep pagination with from
and size
— e.g.
?size=10&from=10000
— is very inefficient as (in this example) 100,000
sorted results have to be retrieved from each shard and resorted in order to
return just 10 results. This process has to be repeated for every page
requested.
The scroll
API keeps track of which results have already been returned and
so is able to return sorted results more efficiently than with deep
pagination. However, sorting results (which happens by default) still has a
cost.
Normally, you just want to retrieve all results and the order doesn’t matter.
Scrolling can be combined with the scan
search type to disable
any scoring or sorting and to return results in the most efficient way
possible. All that is needed is to add search_type=scan
to the query string
of the initial search request:
curl 'localhost:9200/twitter/tweet/_search?scroll=1m&search_type=scan' -d ' { "query": { "match" : { "title" : "elasticsearch" } } } '
A scanning scroll request differs from a standard scroll request in four ways:
- No score is calculated and sorting is disabled. Results are returned in the order they appear in the index.
- Aggregations are not supported.
-
The response of the initial
search
request will not contain any results in thehits
array. The first results will be returned by the firstscroll
request. -
The
size
parameter controls the number of results per shard, not per request, so asize
of10
which hits 5 shards will return a maximum of 50 results perscroll
request.
If you want the scoring to happen, even without sorting on it, set the
track_scores
parameter to true
.
Keeping the search context alive
editThe scroll
parameter (passed to the search
request and to every scroll
request) tells Elasticsearch how long it should keep the search context alive.
Its value (e.g. 1m
, see Time units) does not need to be long enough to
process all data — it just needs to be long enough to process the previous
batch of results. Each scroll
request (with the scroll
parameter) sets a
new expiry time.
Normally, the background merge process optimizes the index by merging together smaller segments to create new bigger segments, at which time the smaller segments are deleted. This process continues during scrolling, but an open search context prevents the old segments from being deleted while they are still in use. This is how Elasticsearch is able to return the results of the initial search request, regardless of subsequent changes to documents.
Keeping older segments alive means that more file handles are needed. Ensure that you have configured your nodes to have ample free file handles. See File Descriptors.
You can check how many search contexts are open with the nodes stats API:
curl -XGET localhost:9200/_nodes/stats/indices/search?pretty
Clear scroll API
editSearch context are automatically removed when the scroll
timeout has been
exceeded. However keeping scrolls open has a cost, as discussed in the
previous section so scrolls should be explicitly
cleared as soon as the scroll is not being used anymore using the
clear-scroll
API:
curl -XDELETE localhost:9200/_search/scroll -d ' { "scroll_id" : ["c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1"] }'
Added in 2.0.0-beta1.
Body based parameters were added in 2.0.0
Multiple scroll IDs can be passed as array:
curl -XDELETE localhost:9200/_search/scroll -d ' { "scroll_id" : ["c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1", "aGVuRmV0Y2g7NTsxOnkxaDZ"] }'
Added in 2.0.0-beta1.
Body based parameters were added in 2.0.0
All search contexts can be cleared with the _all
parameter:
curl -XDELETE localhost:9200/_search/scroll/_all
The scroll_id
can also be passed as a query string parameter or in the request body.
Multiple scroll IDs can be passed as comma separated values:
curl -XDELETE localhost:9200/_search/scroll \ -d 'c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1,aGVuRmV0Y2g7NTsxOnkxaDZ'