[[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-thread]]
==== Operation Threading

The delete API allows to set the threading model the operation will be
performed when the actual execution of the API is performed on the same
node (the API is executed on a shard that is allocated on the same
server).

The options are to execute the operation on a different thread, or to
execute it on the calling thread (note that the API is still async). By
default, `operationThreaded` is set to `true` which means the operation
is executed on a different thread. Here is an example that sets it to
`false`:

[source,java]
--------------------------------------------------
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]
--------------------------------------------------
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<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
