Add 'validate' documentation to the API guide

dakrone · dakrone · commit a89f54a74c63 · 2012-07-05T11:02:53.000-06:00
diff --git a/_layouts/guide.html b/_layouts/guide.html
@@ -20,6 +20,7 @@ <h3>Core</h3>
             <li><a href="/guide/reference/api/count.html">Count</a></li>
             <li><a href="/guide/reference/api/delete-by-query.html">Delete By Query</a></li>
             <li><a href="/guide/reference/api/more-like-this.html">More Like This</a></li>
+            <li><a href="/guide/reference/api/validate.html">Validate</a></li>
         </ul>
 
         <h3>Indices</h3>
diff --git a/guide/reference/api/validate.textile b/guide/reference/api/validate.textile
@@ -0,0 +1,68 @@
+---
+layout: guide
+title: Validate API
+cat: guide
+sidebar: reference_api
+---
+
+p. The validate API allows a user to validate a potentially expensive query without executing it. The following example shows how it can be used:
+
+<pre class="prettyprint">
+curl -XPUT 'http://localhost:9200/twitter/tweet/1' -d '{
+    "user" : "kimchy",
+    "post_date" : "2009-11-15T14:12:12",
+    "message" : "trying out Elastic Search"
+}'
+
+</pre>
+
+When the query is valid, the response contains @valid:true@:
+
+<pre class="prettyprint">
+curl -XGET 'http://localhost:9200/twitter/_validate/query?q=user:foo'
+{"valid":true,"_shards":{"total":1,"successful":1,"failed":0}}
+</pre>
+
+Or, with a request body:
+
+<pre class="prettyprint">
+curl -XGET 'http://localhost:9200/twitter/tweet/_validate/query' -d '{
+  "filtered" : {
+    "query" : {
+      "query_string" : {
+        "query" : "*:*"
+      }
+    },
+    "filter" : {
+      "term" : { "user" : "kimchy" }
+    }
+  }
+}'
+{"valid":true,"_shards":{"total":1,"successful":1,"failed":0}}
+</pre>
+
+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:
+
+<pre class="prettyprint">
+curl -XGET 'http://localhost:9200/twitter/tweet/_validate/query?q=post_date:foo'
+{"valid":false,"_shards":{"total":1,"successful":1,"failed":0}}
+</pre>
+
+An @explain@ parameter can be specified to get more detailed information about why a query failed:
+
+<pre class="prettyprint">
+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\""
+  } ]
+}
+</pre>
