Imported Upstream version 1.0.3upstream/1.0.3

1 files changed, 50 insertions, 0 deletions

diff --git a/docs/java-api/percolate.asciidoc b/docs/java-api/percolate.asciidoc
new file mode 100644
index 0000000..f0187fd
--- /dev/null
+++ b/docs/java-api/percolate.asciidoc
@@ -0,0 +1,50 @@
+[[percolate]]
+== Percolate API
+
+The percolator allows to register queries against an index, and then
+send `percolate` requests which include a doc, and getting back the
+queries that match on that doc out of the set of registered queries.
+
+Read the main {ref}/search-percolate.html[percolate]
+documentation before reading this guide.
+
+[source,java]
+--------------------------------------------------
+//This is the query we're registering in the percolator
+QueryBuilder qb = termQuery("content", "amazing");
+
+//Index the query = register it in the percolator
+client.prepareIndex("myIndexName", ".percolator", "myDesignatedQueryName")
+    .setSource(jsonBuilder()
+        .startObject()
+            .field("query", qb) // Register the query
+        .endObject())
+    .setRefresh(true) // Needed when the query shall be available immediately
+    .execute().actionGet();
+--------------------------------------------------
+
+This indexes the above term query under the name
+*myDesignatedQueryName*.
+
+In order to check a document against the registered queries, use this
+code:
+
+[source,java]
+--------------------------------------------------
+//Build a document to check against the percolator
+XContentBuilder docBuilder = XContentFactory.jsonBuilder().startObject();
+docBuilder.field("doc").startObject(); //This is needed to designate the document
+docBuilder.field("content", "This is amazing!");
+docBuilder.endObject(); //End of the doc field
+docBuilder.endObject(); //End of the JSON root object
+//Percolate
+PercolateResponse response = client.preparePercolate()
+                        .setIndices("myIndexName")
+                        .setDocumentType("myDocumentType")
+                        .setSource(docBuilder).execute().actionGet();
+//Iterate over the results
+for(PercolateResponse.Match match : response) {
+    //Handle the result which is the name of
+    //the query in the percolator
+}
+--------------------------------------------------