5.11. POST /db/_purge

5.11.1. Updating Indexes
MethodPOST /db/_purge
Request JSON of the document IDs/revisions to be purged
Response JSON structure with purged documents and purge sequence
Admin Privileges Requiredno

A database purge permanently removes the references to deleted documents from the database. Deleting a document within CouchDB does not actually remove the documen from the database, instead, the document is marked as a deleted (and a new revision is created). This is to ensure that deleted documents are replicated to other databases as having been deleted. This also means that you can check the status of a document and identify that the document has been deleted.

The purge operation removes the refernces to the deleted documents from the database. The purging of old documents is not replicated to other databases. If you are replicating between databases and have deleted a large number of documents you should run purge on each database.

Note

Purging documents does not remove the space used by them on disk. To reclaim disk space, you should run a database compact (see Section 5.5, “POST /db/_compact, and compact views (see Section 5.6, “POST /db/_compact/design-doc).

To perform a purge operation you must send a request including the JSON of the document IDs that you want to purge. For example:

POST http://couchdb:5984/recipes/_purge
Content-Type: application/json

{
  "FishStew" : [
    "17-b3eb5ac6fbaef4428d712e66483dcb79"
    ]
}

The format of the request must include the document ID and one or more revisions that must be purged.

The response will contain the purge sequence number, and a list of the document IDs and revisions successfully purged.

{
   "purged" : {
      "FishStew" : [
         "17-b3eb5ac6fbaef4428d712e66483dcb79"
      ]
   },
   "purge_seq" : 11
}