Introduce search context - point in time view of indices

client/client-benchmark-noop-api-plugin/src/main/java/org/elasticsearch/plugin/noop/action/search/TransportNoopSearchAction.java

@@ -52,6 +52,6 @@ protected void doExecute(Task task, SearchRequest request, ActionListener<Search
             InternalAggregations.EMPTY,
             new Suggest(Collections.emptyList()),
             new SearchProfileShardResults(Collections.emptyMap()), false, false, 1),
-            "", 1, 1, 0, 0, ShardSearchFailure.EMPTY_ARRAY, SearchResponse.Clusters.EMPTY));
+            "", 1, 1, 0, 0, ShardSearchFailure.EMPTY_ARRAY, SearchResponse.Clusters.EMPTY, null));
     }
 }

client/rest-high-level/src/test/java/org/elasticsearch/client/RestHighLevelClientTests.java

@@ -239,7 +239,7 @@ public void testInfo() throws IOException {
     public void testSearchScroll() throws IOException {
         SearchResponse mockSearchResponse = new SearchResponse(new SearchResponseSections(SearchHits.empty(), InternalAggregations.EMPTY,
                 null, false, false, null, 1), randomAlphaOfLengthBetween(5, 10), 5, 5, 0, 100, ShardSearchFailure.EMPTY_ARRAY,
-                SearchResponse.Clusters.EMPTY);
+                SearchResponse.Clusters.EMPTY, null);
         mockResponse(mockSearchResponse);
         SearchResponse searchResponse = restHighLevelClient.scroll(
                 new SearchScrollRequest(randomAlphaOfLengthBetween(5, 10)), RequestOptions.DEFAULT);
@@ -810,7 +810,9 @@ public void testApiNamingConventions() throws Exception {
             "scripts_painless_execute",
             "indices.simulate_template",
             "indices.resolve_index",
-            "indices.add_block"
+            "indices.add_block",
+            "open_search_context",
+            "close_search_context",
         };
         //These API are not required for high-level client feature completeness
         String[] notRequiredApi = new String[] {

client/rest-high-level/src/test/java/org/elasticsearch/client/asyncsearch/AsyncSearchResponseTests.java

@@ -45,7 +45,7 @@ protected org.elasticsearch.xpack.core.search.action.AsyncSearchResponse createS
         // add search response, minimal object is okay since the full randomization of parsing is tested in SearchResponseTests
         SearchResponse searchResponse = randomBoolean() ? null
                 : new SearchResponse(InternalSearchResponse.empty(), randomAlphaOfLength(10), 1, 1, 0, randomIntBetween(0, 10000),
-                        ShardSearchFailure.EMPTY_ARRAY, Clusters.EMPTY);
+                        ShardSearchFailure.EMPTY_ARRAY, Clusters.EMPTY, null);
         org.elasticsearch.xpack.core.search.action.AsyncSearchResponse testResponse =
                 new org.elasticsearch.xpack.core.search.action.AsyncSearchResponse(id, searchResponse, error, isPartial, isRunning,
                         startTimeMillis, expirationTimeMillis);

docs/reference/search/search_context.asciidoc

@@ -0,0 +1,112 @@
+[[search-context]]
+==== Search Context
+
+A search request by default executes against the most recent point in time view
+of the target indices, which is called a search context. In some cases, it's
+preferred to perform multiple search requests using the same search context.
+For example, if <<indices-refresh,refreshes>> happen between search_after requests,
+then the results of those requests might not be consistent as changes happening between
+searches are only visible to the more recent search context.
+
+A search context must be opened explicitly before being used in search requests. The
+keep_alive parameter tells Elasticsearch how long it should keep the seach context alive,
+e.g. `?keep_alive=5m`.
+
+[source,console]
+--------------------------------------------------
+POST /twitter/_search_context?keep_alive=1m
+--------------------------------------------------
+// TEST[setup:twitter]
+
+The result from the above request includes a `id`, which should
+be passed to the `id` of the `search_context` parameter of a search request.
+
+[source,console]
+--------------------------------------------------
+POST /_search <1>
+{
+    "size": 100,
+    "query": {
+        "match" : {
+            "title" : "elasticsearch"
+        }
+    },
+    "search_context": {
+	    "id":  "46ToAwMDaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQNpZHkFdXVpZDIrBm5vZGVfMwAAAAAAAAAAKgFjA2lkeQV1dWlkMioGbm9kZV8yAAAAAAAAAAAMAWICBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==", <2>
+	    "keep_alive": "1m"  <3>
+    }
+}
+--------------------------------------------------
+// TEST[catch:missing]
+
+<1> A search request with `search_context` must not specify `index`, `routing`,
+and `preferences` as these parameters are copied from the `search_context`.
+<2> The `id` parameter tells Elasticsearch to execute the request using
+the point-in-time readers from this search context id.
+<3> The `keep_alive` parameter tells Elasticsearch how long it should extend
+the time to live of the search context
+
+IMPORTANT: The open search context request and each subsequent search request can
+return different `id`; thus always use the most recently received `id` for the
+next search request.
+
+[[search-context-keep-alive]]
+===== Keeping the search context alive
+The `keep_alive` parameter, which is passed to a open search context request and
+search request, extends the time to live of the search context. The 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 for the next request.
+
+Normally, the background merge process optimizes the index by merging together
+smaller segments to create new, bigger segments. Once the smaller segments are
+no longer needed they are deleted. However, open search contexts prevents the
+old segments from being deleted since they are still in use.
+
+TIP: Keeping older segments alive means that more disk space and file handles
+are needed. Ensure that you have configured your nodes to have ample free file
+handles. See <<file-descriptors>>.
+
+Additionally, if a segment contains deleted or updated documents then the search
+context must keep track of whether each document in the segment was live at the
+time of the initial search request. Ensure that your nodes have sufficient heap
+space if you have many open search contexts on an index that is subject to ongoing
+deletes or updates.
+
+You can check how many search contexts are open with the
+<<cluster-nodes-stats,nodes stats API>>:
+
+[source,console]
+---------------------------------------
+GET /_nodes/stats/indices/search
+---------------------------------------
+
+===== Close search context API
+
+Search contexts are automatically closed when the `keep_alive` has
+been elapsed. However keeping search contexts has a cost, as discussed in the
+<<search-context-keep-alive,previous section>>. Search contexts should be closed
+as soon as they are no longer used in search requests.
+
+[source,console]
+---------------------------------------
+DELETE /_search_context
+{
+    "id" : "46ToAwMDaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQNpZHkFdXVpZDIrBm5vZGVfMwAAAAAAAAAAKgFjA2lkeQV1dWlkMioGbm9kZV8yAAAAAAAAAAAMAWIBBXV1aWQyAAA="
+}
+---------------------------------------
+// TEST[catch:missing]
+
+The API returns the following response:
+
+[source,console-result]
+--------------------------------------------------
+{
+   "succeeded": true, <1>
+   "num_freed": 3     <2>
+}
+--------------------------------------------------
+// TESTRESPONSE[s/"succeeded": true/"succeeded": $body.succeeded/]
+// TESTRESPONSE[s/"num_freed": 3/"num_freed": $body.num_freed/]
+
+<1> If true, all search contexts associated with the given id are successfully closed
+<2> The number of search contexts have been successfully closed

modules/lang-mustache/src/test/java/org/elasticsearch/script/mustache/MultiSearchTemplateResponseTests.java

@@ -53,7 +53,7 @@ protected MultiSearchTemplateResponse createTestInstance() {
             SearchResponse.Clusters clusters = randomClusters();
             SearchTemplateResponse searchTemplateResponse = new SearchTemplateResponse();
             SearchResponse searchResponse = new SearchResponse(internalSearchResponse, null, totalShards,
-                    successfulShards, skippedShards, tookInMillis, ShardSearchFailure.EMPTY_ARRAY, clusters);
+                    successfulShards, skippedShards, tookInMillis, ShardSearchFailure.EMPTY_ARRAY, clusters, null);
             searchTemplateResponse.setResponse(searchResponse);
             items[i] = new MultiSearchTemplateResponse.Item(searchTemplateResponse, null);
         }
@@ -82,7 +82,7 @@ private static  MultiSearchTemplateResponse createTestInstanceWithFailures() {
                 SearchResponse.Clusters clusters = randomClusters();
                 SearchTemplateResponse searchTemplateResponse = new SearchTemplateResponse();
                 SearchResponse searchResponse = new SearchResponse(internalSearchResponse, null, totalShards,
-                        successfulShards, skippedShards, tookInMillis, ShardSearchFailure.EMPTY_ARRAY, clusters);
+                        successfulShards, skippedShards, tookInMillis, ShardSearchFailure.EMPTY_ARRAY, clusters, null);
                 searchTemplateResponse.setResponse(searchResponse);
                 items[i] = new MultiSearchTemplateResponse.Item(searchTemplateResponse, null);
             } else {

modules/lang-mustache/src/test/java/org/elasticsearch/script/mustache/SearchTemplateResponseTests.java

@@ -69,7 +69,7 @@ private static SearchResponse createSearchResponse() {
         InternalSearchResponse internalSearchResponse = InternalSearchResponse.empty();
 
         return new SearchResponse(internalSearchResponse, null, totalShards, successfulShards,
-            skippedShards, tookInMillis, ShardSearchFailure.EMPTY_ARRAY, SearchResponse.Clusters.EMPTY);
+            skippedShards, tookInMillis, ShardSearchFailure.EMPTY_ARRAY, SearchResponse.Clusters.EMPTY, null);
     }
 
     private static BytesReference createSource() {
@@ -171,7 +171,7 @@ public void testSearchResponseToXContent() throws IOException {
         InternalSearchResponse internalSearchResponse = new InternalSearchResponse(
             new SearchHits(hits, new TotalHits(100, TotalHits.Relation.EQUAL_TO), 1.5f), null, null, null, false, null, 1);
         SearchResponse searchResponse = new SearchResponse(internalSearchResponse, null,
-            0, 0, 0, 0, ShardSearchFailure.EMPTY_ARRAY, SearchResponse.Clusters.EMPTY);
+            0, 0, 0, 0, ShardSearchFailure.EMPTY_ARRAY, SearchResponse.Clusters.EMPTY, null);
 
         SearchTemplateResponse response = new SearchTemplateResponse();
         response.setResponse(searchResponse);

modules/parent-join/src/main/java/org/elasticsearch/join/query/ParentChildInnerHitContextBuilder.java

@@ -158,12 +158,8 @@ public TopDocsAndMaxScore[] topDocs(SearchHit[] hits) throws IOException {
                         topDocsCollector = TopScoreDocCollector.create(topN, Integer.MAX_VALUE);
                         maxScoreCollector = new MaxScoreCollector();
                     }
-                    try {
-                        for (LeafReaderContext ctx : context.searcher().getIndexReader().leaves()) {
-                            intersect(weight, innerHitQueryWeight, MultiCollector.wrap(topDocsCollector, maxScoreCollector), ctx);
-                        }
-                    } finally {
-                        clearReleasables(Lifetime.COLLECTION);
+                    for (LeafReaderContext ctx : context.searcher().getIndexReader().leaves()) {
+                        intersect(weight, innerHitQueryWeight, MultiCollector.wrap(topDocsCollector, maxScoreCollector), ctx);
                     }
                     TopDocs topDocs = topDocsCollector.topDocs(from(), size());
                     float maxScore = Float.NaN;

modules/reindex/src/test/java/org/elasticsearch/index/reindex/AsyncBulkByScrollActionTests.java

@@ -508,7 +508,7 @@ protected RequestWrapper<?> buildRequest(Hit doc) {
             new TotalHits(0, TotalHits.Relation.EQUAL_TO),0);
         InternalSearchResponse internalResponse = new InternalSearchResponse(hits, null, null, null, false, false, 1);
         SearchResponse searchResponse = new SearchResponse(internalResponse, scrollId(), 5, 4, 0, randomLong(), null,
-            SearchResponse.Clusters.EMPTY);
+            SearchResponse.Clusters.EMPTY, null);
 
         client.lastSearch.get().listener.onResponse(searchResponse);
 

modules/reindex/src/test/java/org/elasticsearch/index/reindex/ClientScrollableHitSourceTests.java

@@ -164,7 +164,7 @@ private SearchResponse createSearchResponse() {
             new TotalHits(0, TotalHits.Relation.EQUAL_TO),0);
         InternalSearchResponse internalResponse = new InternalSearchResponse(hits, null, null, null, false, false, 1);
         return new SearchResponse(internalResponse, randomSimpleString(random(), 1, 10), 5, 4, 0, randomLong(), null,
-            SearchResponse.Clusters.EMPTY);
+            SearchResponse.Clusters.EMPTY, null);
     }
 
     private void assertSameHits(List<? extends ScrollableHitSource.Hit> actual, SearchHit[] expected) {

qa/ccs-unavailable-clusters/src/test/java/org/elasticsearch/search/CrossClusterSearchUnavailableClusterIT.java

@@ -117,7 +117,7 @@ private static MockTransportService startTransport(
                     InternalSearchResponse response = new InternalSearchResponse(new SearchHits(new SearchHit[0],
                         new TotalHits(0, TotalHits.Relation.EQUAL_TO), Float.NaN), InternalAggregations.EMPTY, null, null, false, null, 1);
                     SearchResponse searchResponse = new SearchResponse(response, null, 1, 1, 0, 100, ShardSearchFailure.EMPTY_ARRAY,
-                        SearchResponse.Clusters.EMPTY);
+                        SearchResponse.Clusters.EMPTY, null);
                     channel.sendResponse(searchResponse);
                 });
             newService.registerRequestHandler(ClusterStateAction.NAME, ThreadPool.Names.SAME, ClusterStateRequest::new,

rest-api-spec/src/main/resources/rest-api-spec/api/close_search_context.json

@@ -0,0 +1,23 @@
+{
+  "close_search_context":{
+    "documentation":{
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/search-context.html",
+      "description":"Close a search context"
+    },
+    "stability":"beta",
+    "url":{
+      "paths":[
+        {
+          "path":"/_search_context",
+          "methods":[
+            "DELETE"
+          ]
+        }
+      ]
+    },
+    "params":{},
+    "body":{
+      "description": "a search context to close"
+    }
+  }
+}

rest-api-spec/src/main/resources/rest-api-spec/api/open_search_context.json

@@ -0,0 +1,61 @@
+{
+  "open_search_context":{
+    "documentation":{
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/search-context.html",
+      "description":"Open a search context that can be used in subsequent searches"
+    },
+    "stability":"beta",
+    "url":{
+      "paths":[
+        {
+          "path":"/_search_context",
+          "methods":[
+            "POST"
+          ]
+        },
+        {
+          "path":"/{index}/_search_context",
+          "methods":[
+            "POST"
+          ],
+          "parts":{
+            "index":{
+              "type":"list",
+              "description":"A comma-separated list of index names to open search context; use `_all` or empty string to perform the operation on all indices"
+            }
+          }
+        }
+      ]
+    },
+    "params":{
+      "preference":{
+        "type":"string",
+        "description":"Specify the node or shard the operation should be performed on (default: random)"
+      },
+      "routing":{
+        "type":"string",
+        "description":"Specific routing value"
+      },
+      "ignore_unavailable":{
+        "type":"boolean",
+        "description":"Whether specified concrete indices should be ignored when unavailable (missing or closed)"
+      },
+      "expand_wildcards":{
+        "type":"enum",
+        "options":[
+          "open",
+          "closed",
+          "hidden",
+          "none",
+          "all"
+        ],
+        "default":"open",
+        "description":"Whether to expand wildcard expression to concrete indices that are open, closed or both."
+      },
+      "keep_alive": {
+        "type": "string",
+        "description": "Specific the time to live for the search context"
+      }
+    }
+  }
+}

rest-api-spec/src/main/resources/rest-api-spec/test/scroll/20_keep_alive.yml

@@ -34,7 +34,7 @@
             search.max_keep_alive: "1m"
 
   - do:
-      catch: /.*Keep alive for scroll.*is too large.*/
+      catch: /.*Keep alive for.*is too large.*/
       search:
         rest_total_hits_as_int: true
         index: test_scroll
@@ -61,7 +61,7 @@
   - length: {hits.hits:      1    }
 
   - do:
-      catch: /.*Keep alive for scroll.*is too large.*/
+      catch: /.*Keep alive for.*is too large.*/
       scroll:
         rest_total_hits_as_int: true
         scroll_id: $scroll_id