Deleting a document

The steps shown here demonstrate how to delete a document.

1. Send a DELETE request with the document's most recent _rev in the query string.
2. Run the following command: https://$ACCOUNT.cloudant.com/$DATABASE/$DOCUMENT_ID. The response contains the ID and the new revision of the document, or an error message if the delete failed.

If you fail to provide the most recent _rev, IBM Cloudant responds with a 409 error. This error prevents you overwriting data that were changed by other clients. If the write quorum can't be met, a 202 response is returned.

IBM Cloudant doesn't completely delete the specified document. Instead, it leaves a tombstone with basic information about the document. The tombstone is required so that the delete action can be replicated to other copies of the database. Since the tombstones stay in the database indefinitely, creating new documents and deleting them increases the disk space usage of a database. They might also increase the query time for the primary index, which is used to look up documents by their ID.

The following steps show you how to delete a request by using HTTP.

1. Send a DELETE request with the document's most recent _rev in the query string by using HTTP.

2. Run the following command: DELETE /$DATABASE/$DOCUMENT_ID?rev=$REV HTTP/1.1.

The following code examples show you how to delete a document by using the command line.

# make sure $JSON contains the correct `_rev` value!

curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X DELETE "$SERVICE_URL/events/0007241142412418284?rev=2-9a0d1cd9f40472509e9aac6461837367"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.DeleteDocumentOptions;
import com.ibm.cloud.cloudant.v1.model.DocumentResult;

Cloudant service = Cloudant.newInstance();

DeleteDocumentOptions documentOptions =
    new DeleteDocumentOptions.Builder()
        .db("events")
        .docId("0007241142412418284")
        .rev("2-9a0d1cd9f40472509e9aac6461837367")
        .build();

DocumentResult response =
    service.deleteDocument(documentOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});

service.deleteDocument({
 db: 'events',
 docId: '0007241142412418284',
 rev: '2-9a0d1cd9f40472509e9aac6461837367'
}).then(response => {
 console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.delete_document(
 db='events',
 doc_id='0007241142412418284',
 rev='2-9a0d1cd9f40472509e9aac6461837367'
).get_result()

print(response)

deleteDocumentOptions := service.NewDeleteDocumentOptions(
 "events",
 "0007241142412418284",
)
deleteDocumentOptions.SetRev("2-9a0d1cd9f40472509e9aac6461837367")

documentResult, response, err := service.DeleteDocument(deleteDocumentOptions)
if err != nil {
 panic(err)
}

b, _ := json.MarshalIndent(documentResult, "", "  ")
fmt.Println(string(b))

The previous Go example requires the following import block:

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

All Go examples require the service object to be initialized. For more information, see the API documentation's Authentication section for examples.

See an example response after a successful deletion request.

{
  "id": "exampleid",
  "ok": true,
  "rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
}