elasticsearch/docs/java-api/docs/delete.asciidoc

[[java-docs-delete]]
=== Delete API

The delete API allows one to delete a typed JSON document from a specific
index based on its id. The following example deletes the JSON document
from an index called twitter, under a type called tweet, with id valued
1:

[source,java]
--------------------------------------------------
DeleteResponse response = client.prepareDelete("twitter", "tweet", "1").get();
--------------------------------------------------

For more information on the delete operation, check out the
{ref}/docs-delete.html[delete API] docs.

[[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]
--------------------------------------------------
BulkByScrollResponse 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<BulkByScrollResponse>() {           <3>
        @Override
        public void onResponse(BulkByScrollResponse 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