1 files changed, 77 insertions, 0 deletions
diff --git a/docs/reference/search/validate.asciidoc b/docs/reference/search/validate.asciidoc
new file mode 100644
index 0000000..cdf9981
--- /dev/null
+++ b/docs/reference/search/validate.asciidoc
@@ -0,0 +1,77 @@
+[[search-validate]]
+== Validate API
+
+The validate API allows a user to validate a potentially expensive query
+without executing it. The following example shows how it can be used:
+
+[source,js]
+--------------------------------------------------
+curl -XPUT 'http://localhost:9200/twitter/tweet/1' -d '{
+    "user" : "kimchy",
+    "post_date" : "2009-11-15T14:12:12",
+    "message" : "trying out Elasticsearch"
+}'
+--------------------------------------------------
+
+When the query is valid, the response contains `valid:true`:
+
+[source,js]
+--------------------------------------------------
+curl -XGET 'http://localhost:9200/twitter/_validate/query?q=user:foo'
+{"valid":true,"_shards":{"total":1,"successful":1,"failed":0}}
+--------------------------------------------------
+
+Or, with a request body:
+
+[source,js]
+--------------------------------------------------
+curl -XGET 'http://localhost:9200/twitter/tweet/_validate/query' -d '{
+  "query" : {
+    "filtered" : {
+      "query" : {
+        "query_string" : {
+          "query" : "*:*"
+        }
+      },
+      "filter" : {
+        "term" : { "user" : "kimchy" }
+      }
+    }
+  }
+}'
+{"valid":true,"_shards":{"total":1,"successful":1,"failed":0}}
+--------------------------------------------------
+
+NOTE: The query being sent in the body must be nested in a `query` key, same as
+the <<search-search,search api>> works added[1.0.0.RC1,The query was previously the top-level object].
+
+If the query is invalid, `valid` will be `false`. Here the query is
+invalid because Elasticsearch knows the post_date field should be a date
+due to dynamic mapping, and 'foo' does not correctly parse into a date:
+
+[source,js]
+--------------------------------------------------
+curl -XGET 'http://localhost:9200/twitter/tweet/_validate/query?q=post_date:foo'
+{"valid":false,"_shards":{"total":1,"successful":1,"failed":0}}
+--------------------------------------------------
+
+An `explain` parameter can be specified to get more detailed information
+about why a query failed:
+
+[source,js]
+--------------------------------------------------
+curl -XGET 'http://localhost:9200/twitter/tweet/_validate/query?q=post_date:foo&pretty=true&explain=true'
+{
+  "valid" : false,
+  "_shards" : {
+    "total" : 1,
+    "successful" : 1,
+    "failed" : 0
+  },
+  "explanations" : [ {
+    "index" : "twitter",
+    "valid" : false,
+    "error" : "org.elasticsearch.index.query.QueryParsingException: [twitter] Failed to parse; org.elasticsearch.ElasticsearchParseException: failed to parse date field [foo], tried both date format [dateOptionalTime], and timestamp number; java.lang.IllegalArgumentException: Invalid format: \"foo\""
+  } ]
+}
+--------------------------------------------------