From 72ee65f914099f83f30c46dd35ccc4836ef3f50c Mon Sep 17 00:00:00 2001
From: David Pilato <david@pilato.fr>
Date: Fri, 16 Dec 2016 18:11:55 +0100
Subject: [PATCH] Add documentation for Delete By Query Java API

Closes #22114
---
 docs/java-api/docs.asciidoc        |  1 +
 docs/java-api/docs/delete.asciidoc | 45 ++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/docs/java-api/docs.asciidoc b/docs/java-api/docs.asciidoc
index 9ace406ee42..c355714bdd6 100644
--- a/docs/java-api/docs.asciidoc
+++ b/docs/java-api/docs.asciidoc
@@ -7,6 +7,7 @@ This section describes the following CRUD APIs:
 * <<java-docs-index>>
 * <<java-docs-get>>
 * <<java-docs-delete>>
+* <<java-docs-delete-by-query>>
 * <<java-docs-update>>
 
 .Multi-document APIs
diff --git a/docs/java-api/docs/delete.asciidoc b/docs/java-api/docs/delete.asciidoc
index b9efd01242d..392132aa129 100644
--- a/docs/java-api/docs/delete.asciidoc
+++ b/docs/java-api/docs/delete.asciidoc
@@ -35,3 +35,48 @@ DeleteResponse response = client.prepareDelete("twitter", "tweet", "1")
         .setOperationThreaded(false)
         .get();
 --------------------------------------------------
+
+[[java-docs-delete-by-query]]
+=== Delete By Query API
+
+The delete by query API allows one to delete a given set of documents based on
+the result of a query:
+
+[source,java]
+--------------------------------------------------
+BulkIndexByScrollResponse response =
+    DeleteByQueryAction.INSTANCE.newRequestBuilder(client)
+        .filter(QueryBuilders.matchQuery("gender", "male")) <1>
+        .source("persons")                                  <2>
+        .get();                                             <3>
+
+long deleted = response.getDeleted();                       <4>
+--------------------------------------------------
+<1> query
+<2> index
+<3> execute the operation
+<4> number of deleted documents
+
+As it can be a long running operation, if you wish to do it asynchronously, you can call `execute` instead of `get`
+and provide a listener like:
+
+[source,java]
+--------------------------------------------------
+DeleteByQueryAction.INSTANCE.newRequestBuilder(client)
+    .filter(QueryBuilders.matchQuery("gender", "male"))                  <1>
+    .source("persons")                                                   <2>
+    .execute(new ActionListener<BulkIndexByScrollResponse>() {           <3>
+        @Override
+        public void onResponse(BulkIndexByScrollResponse response) {
+            long deleted = response.getDeleted();                        <4>
+        }
+        @Override
+        public void onFailure(Exception e) {
+            // Handle the exception
+        }
+    });
+--------------------------------------------------
+<1> query
+<2> index
+<3> listener
+<4> number of deleted documents