Search Exists API: Checks if any matching documents exist for a given…

… query

Implements a new Exists API allowing users to do fast exists check on any matched documents for a given query.
This API should be faster then using the Count API as it will:
 - early terminate the search execution once any document is found to exist
 - return the response as soon as the first shard reports matched documents

closes #6995

docs/reference/search.asciidoc

@@ -95,6 +95,8 @@ include::search/multi-search.asciidoc[]
 
 include::search/count.asciidoc[]
 
+include::search/exists.asciidoc[]
+
 include::search/validate.asciidoc[]
 
 include::search/explain.asciidoc[]

docs/reference/search/exists.asciidoc

@@ -0,0 +1,86 @@
+[[search-exists]]
+== Search Exists API
+
+The exists API allows to easily determine if any
+matching documents exist for a provided query. It can be executed across one or more indices
+and across one or more types. The query can either be provided using a
+simple query string as a parameter, or using the
+<<query-dsl,Query DSL>> defined within the request
+body. Here is an example:
+
+[source,js]
+--------------------------------------------------
+$ curl -XGET 'http://localhost:9200/twitter/tweet/_search/exists?q=user:kimchy'
+
+$ curl -XGET 'http://localhost:9200/twitter/tweet/_search/exists' -d '
+{
+    "query" : {
+        "term" : { "user" : "kimchy" }
+    }
+}'
+
+--------------------------------------------------
+
+NOTE: The query being sent in the body must be nested in a `query` key, same as
+how the <<search-search,search api>> works.
+
+Both the examples above do the same thing, which is determine the existence of
+tweets from the twitter index for a certain user. The response body will be of
+the following format:
+
+[source,js]
+--------------------------------------------------
+{
+    "exists" : true
+}
+--------------------------------------------------
+
+[float]
+=== Multi index, Multi type
+
+The exists API can be applied to <<search-multi-index-type,multiple types in multiple indices>>.
+
+[float]
+=== Request Parameters
+
+When executing exists using the query parameter `q`, the query passed is
+a query string using Lucene query parser. There are additional
+parameters that can be passed:
+
+[cols="<,<",options="header",]
+|=======================================================================
+|Name |Description
+|df |The default field to use when no field prefix is defined within the
+query.
+
+|analyzer |The analyzer name to be used when analyzing the query string.
+
+|default_operator |The default operator to be used, can be `AND` or
+`OR`. Defaults to `OR`.
+
+|=======================================================================
+
+[float]
+=== Request Body
+
+The exists API can use the <<query-dsl,Query DSL>> within
+its body in order to express the query that should be executed. The body
+content can also be passed as a REST parameter named `source`.
+
+HTTP GET and HTTP POST can be used to execute exists with body.
+Since not all clients support GET with body, POST is allowed as well.
+
+[float]
+=== Distributed
+
+The exists operation is broadcast across all shards. For each shard id
+group, a replica is chosen and executed against it. This means that
+replicas increase the scalability of exists. The exists operation also
+early terminates shard requests once the first shard reports matched
+document existence.
+
+[float]
+=== Routing
+
+The routing value (a comma separated list of the routing values) can be
+specified to control which shards the exists request will be executed on.

rest-api-spec/api/search_exists.json

@@ -0,0 +1,55 @@
+{
+  "search_exists": {
+    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/exists.html",
+    "methods": ["POST", "GET"],
+    "url": {
+      "path": "/_search/exists",
+      "paths": ["/_search/exists", "/{index}/_search/exists", "/{index}/{type}/_search/exists"],
+      "parts": {
+        "index": {
+          "type" : "list",
+          "description" : "A comma-separated list of indices to restrict the results"
+        },
+        "type": {
+          "type" : "list",
+          "description" : "A comma-separated list of types to restrict the results"
+        }
+      },
+      "params": {
+        "ignore_unavailable": {
+          "type" : "boolean",
+          "description" : "Whether specified concrete indices should be ignored when unavailable (missing or closed)"
+        },
+        "allow_no_indices": {
+           "type" : "boolean",
+           "description" : "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)"
+        },
+        "expand_wildcards": {
+            "type" : "enum",
+            "options" : ["open","closed"],
+            "default" : "open",
+            "description" : "Whether to expand wildcard expression to concrete indices that are open, closed or both."
+        },
+        "min_score": {
+          "type" : "number",
+          "description" : "Include only documents with a specific `_score` value in the result"
+        },
+        "preference": {
+          "type" : "string",
+          "description" : "Specify the node or shard the operation should be performed on (default: random)"
+        },
+        "routing": {
+          "type" : "string",
+          "description" : "Specific routing value"
+        },
+        "source": {
+          "type" : "string",
+          "description" : "The URL-encoded query definition (instead of using the request body)"
+        }
+      }
+    },
+    "body": {
+      "description" : "A query to restrict the results specified with the Query DSL (optional)"
+    }
+  }
+}

src/main/java/org/elasticsearch/action/ActionModule.java

@@ -132,6 +132,8 @@
 import org.elasticsearch.action.deletebyquery.TransportDeleteByQueryAction;
 import org.elasticsearch.action.deletebyquery.TransportIndexDeleteByQueryAction;
 import org.elasticsearch.action.deletebyquery.TransportShardDeleteByQueryAction;
+import org.elasticsearch.action.exists.ExistsAction;
+import org.elasticsearch.action.exists.TransportExistsAction;
 import org.elasticsearch.action.explain.ExplainAction;
 import org.elasticsearch.action.explain.TransportExplainAction;
 import org.elasticsearch.action.get.*;
@@ -278,6 +280,7 @@ protected void configure() {
         registerAction(DeleteAction.INSTANCE, TransportDeleteAction.class,
                 TransportIndexDeleteAction.class, TransportShardDeleteAction.class);
         registerAction(CountAction.INSTANCE, TransportCountAction.class);
+        registerAction(ExistsAction.INSTANCE, TransportExistsAction.class);
         registerAction(SuggestAction.INSTANCE, TransportSuggestAction.class);
         registerAction(UpdateAction.INSTANCE, TransportUpdateAction.class);
         registerAction(MultiGetAction.INSTANCE, TransportMultiGetAction.class,

src/main/java/org/elasticsearch/action/exists/ExistsAction.java

@@ -0,0 +1,43 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.action.exists;
+
+
+import org.elasticsearch.action.ClientAction;
+import org.elasticsearch.client.Client;
+
+public class ExistsAction extends ClientAction<ExistsRequest, ExistsResponse, ExistsRequestBuilder> {
+
+    public static final ExistsAction INSTANCE = new ExistsAction();
+    public static final String NAME = "exists";
+
+    private ExistsAction() {
+        super(NAME);
+    }
+
+    @Override
+    public ExistsResponse newResponse() {
+        return new ExistsResponse();
+    }
+
+    @Override
+    public ExistsRequestBuilder newRequestBuilder(Client client) {
+        return new ExistsRequestBuilder(client);
+    }
+}