From 1f1daf59bcd8d3ffbc6612654211c9489a9d9dd5 Mon Sep 17 00:00:00 2001
From: Craig Squire <csquire@widen.com>
Date: Tue, 1 Nov 2016 14:55:09 -0500
Subject: [PATCH] Documentation updates for scroll API size parameter (#21229)

* Document size parameter for scroll API

* Fix size parameter behavior description for scroll
---
 docs/java-api/search.asciidoc                 | 6 +-----
 docs/reference/search/request/scroll.asciidoc | 7 +++++--
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/docs/java-api/search.asciidoc b/docs/java-api/search.asciidoc
index f5f20b30a9c..2da24e93c22 100644
--- a/docs/java-api/search.asciidoc
+++ b/docs/java-api/search.asciidoc
@@ -58,7 +58,7 @@ SearchResponse scrollResp = client.prepareSearch(test)
         .addSort(FieldSortBuilder.DOC_FIELD_NAME, SortOrder.ASC)
         .setScroll(new TimeValue(60000))
         .setQuery(qb)
-        .setSize(100).execute().actionGet(); //100 hits per shard will be returned for each scroll
+        .setSize(100).execute().actionGet(); //max of 100 hits will be returned for each scroll
 //Scroll until no hits are returned
 do {
     for (SearchHit hit : scrollResp.getHits().getHits()) {
@@ -68,10 +68,6 @@ do {
     scrollResp = client.prepareSearchScroll(scrollResp.getScrollId()).setScroll(new TimeValue(60000)).execute().actionGet();
 } while(scrollResp.getHits().getHits().length != 0); // Zero hits mark the end of the scroll and the while loop.
 --------------------------------------------------
-[NOTE]
-====
-The size-parameter is per shard, so if you run a query against multiple indices (leading to many shards being involved in the query) the result might be more documents per execution of the scroll than you would expect!
-====
 
 [[java-search-msearch]]
 === MultiSearch API
diff --git a/docs/reference/search/request/scroll.asciidoc b/docs/reference/search/request/scroll.asciidoc
index bee8e158175..82a27881720 100644
--- a/docs/reference/search/request/scroll.asciidoc
+++ b/docs/reference/search/request/scroll.asciidoc
@@ -40,6 +40,7 @@ should keep the ``search context'' alive (see <<scroll-search-context>>), eg `?s
 --------------------------------------------------
 POST /twitter/tweet/_search?scroll=1m
 {
+    "size": 100,
     "query": {
         "match" : {
             "title" : "elasticsearch"
@@ -72,8 +73,10 @@ POST <1> /_search/scroll <2>
     for another `1m`.
 <4> The `scroll_id` parameter
 
-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.
+The `size` parameter allows you to configure the maximum number of hits to be 
+returned with each batch of results.  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.
 
 IMPORTANT: The initial search request and each subsequent scroll request
 returns a new `_scroll_id` -- only the most recent `_scroll_id` should be