9.3.11. /db/_purge — Apache CouchDB 1.7 Documentation

# 9.3.11. `/db/_purge`

`POST` `/{db}/_purge`

  A database purge permanently removes the references to deleted documents from the database. Normal deletion of a document within CouchDB does not remove the document from the database, instead, the document is marked as `_deleted=true` (and a new revision is created). This is to ensure that deleted documents can be 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 by its absence.

  Warning

  Purging a document from a database should only be done as a last resort when sensitive information has been introduced inadvertently into a database. In clustered or replicated environments it is very difficult to guarantee that a particular purged document has been removed from all replicas. Do not rely on this API as a way of doing secure deletion.

  The purge operation removes the references 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 /db/_compact), and compact views (see /db/_compact/design-doc).

  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.

  Parameters: | db – Database name
  Request Headers:
  | Accept – application/json text/plain Content-Type – application/json
  Request JSON Object:
  | object – Mapping of document ID to list of revisions to purge
  Response Headers:
  | Content-Type – application/json text/plain; charset=utf-8
  Response JSON Object:
  | purge_seq (number) – Purge sequence number purged (object) – Mapping of document ID to list of purged revisions
  Status Codes: | 200 OK – Request completed successfully 400 Bad Request – Invalid database name or JSON payload 415 Unsupported Media Type – Bad Content-Type value

  Request:

      POST /db/_purge HTTP/1.1
      Accept: application/json
      Content-Length: 76
      Content-Type: application/json
      Host: localhost:5984

      {
        "c6114c65e295552ab1019e2b046b10e": [
          "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b",
          "3-0e871ef78849b0c206091f1a7af6ec41"
        ]
      }

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 103
      Content-Type: application/json
      Date: Mon, 12 Aug 2013 10:53:24 GMT
      Server: CouchDB (Erlang/OTP)

      {
        "purge_seq":3,
        "purged":{
          "c6114c65e295552ab1019e2b046b10e": [
            "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b"
          ]
        }
      }

## Updating Indexes

The number of purges on a database is tracked using a purge sequence. This is used by the view indexer to optimize the updating of views that contain the purged documents.

When the indexer identifies that the purge sequence on a database has changed, it compares the purge sequence of the database with that stored in the view index. If the difference between the stored sequence and database is sequence is only 1, then the indexer uses a cached list of the most recently purged documents, and then removes these documents from the index individually. This prevents completely rebuilding the index from scratch.

If the difference between the stored sequence number and current database sequence is greater than 1, then the view index is entirely rebuilt. This is an expensive operation as every document in the database must be examined.

# 9.3.12. `/db/_missing_revs`

`POST` `/{db}/_missing_revs`

  With given a list of document revisions, returns the document revisions that do not exist in the database.

  Parameters: | db – Database name
  Request Headers:
  | Accept – application/json text/plain Content-Type – application/json
  Request JSON Object:
  | object – Mapping of document ID to list of revisions to lookup
  Response Headers:
  | Content-Type – application/json text/plain; charset=utf-8
  Response JSON Object:
  | missing_revs (object) – Mapping of document ID to list of missed revisions
  Status Codes: | 200 OK – Request completed successfully 400 Bad Request – Invalid database name or JSON payload

  Request:

      POST /db/_missing_revs HTTP/1.1
      Accept: application/json
      Content-Length: 76
      Content-Type: application/json
      Host: localhost:5984

      {
        "c6114c65e295552ab1019e2b046b10e": [
          "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b",
          "3-0e871ef78849b0c206091f1a7af6ec41"
        ]
      }

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 64
      Content-Type: application/json
      Date: Mon, 12 Aug 2013 10:53:24 GMT
      Server: CouchDB (Erlang/OTP)

      {
        "missed_revs":{
          "c6114c65e295552ab1019e2b046b10e": [
            "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b"
          ]
        }
      }

# 9.3.13. `/db/_revs_diff`

`POST` `/{db}/_revs_diff`

  Given a set of document/revision IDs, returns the subset of those that do not correspond to revisions stored in the database.

  Its primary use is by the replicator, as an important optimization: after receiving a set of new revision IDs from the source database, the replicator sends this set to the destination database’s `_revs_diff` to find out which of them already exist there. It can then avoid fetching and sending already-known document bodies.

  Both the request and response bodies are JSON objects whose keys are document IDs; but the values are structured differently:

  - In the request, a value is an array of revision IDs for that document.
  - In the response, a value is an object with a `missing`: key, whose value is a list of revision IDs for that document (the ones that are not stored in the database) and optionally a `possible_ancestors` key, whose value is an array of revision IDs that are known that might be ancestors of the missing revisions.

  Parameters: | db – Database name
  Request Headers:
  | Accept – application/json text/plain Content-Type – application/json
  Request JSON Object:
  | object – Mapping of document ID to list of revisions to lookup
  Response Headers:
  | Content-Type – application/json text/plain; charset=utf-8
  Response JSON Object:
  | missing (array) – List of missed revisions for specified document possible_ancestors (array) – List of revisions that may be ancestors for specified document and its current revision in requested database
  Status Codes: | 200 OK – Request completed successfully 400 Bad Request – Invalid database name or JSON payload

  Request:

      POST /db/_revs_diff HTTP/1.1
      Accept: application/json
      Content-Length: 113
      Content-Type: application/json
      Host: localhost:5984

      {
        "190f721ca3411be7aa9477db5f948bbb": [
          "3-bb72a7682290f94a985f7afac8b27137",
          "4-10265e5a26d807a3cfa459cf1a82ef2e",
          "5-067a00dff5e02add41819138abb3284d"
        ]
      }

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 88
      Content-Type: application/json
      Date: Mon, 12 Aug 2013 16:56:02 GMT
      Server: CouchDB (Erlang/OTP)

      {
        "190f721ca3411be7aa9477db5f948bbb": {
          "missing": [
            "3-bb72a7682290f94a985f7afac8b27137",
            "5-067a00dff5e02add41819138abb3284d"
          ],
          "possible_ancestors": [
            "4-10265e5a26d807a3cfa459cf1a82ef2e"
          ]
        }
      }

# 9.3.14. `/db/_revs_limit`

`GET` `/{db}/_revs_limit`

  Gets the current `revs_limit` (revision limit) setting.

  Parameters: | db – Database name
  Request Headers:
  | Accept – application/json text/plain
  Response Headers:
  | Content-Type – application/json text/plain; charset=utf-8
  Status Codes: | 200 OK – Request completed successfully

  Request:

      GET /db/_revs_limit HTTP/1.1
      Accept: application/json
      Host: localhost:5984

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 5
      Content-Type: application/json
      Date: Mon, 12 Aug 2013 17:27:30 GMT
      Server: CouchDB (Erlang/OTP)

      1000

`PUT` `/{db}/_revs_limit`

  Sets the maximum number of document revisions that will be tracked by CouchDB, even after compaction has occurred. You can set the revision limit on a database with a scalar integer of the limit that you want to set as the request body.

  Parameters: | db – Database name
  Request Headers:
  | Accept – application/json text/plain Content-Type – application/json
  Response Headers:
  | Content-Type – application/json text/plain; charset=utf-8
  Response JSON Object:
  | ok (boolean) – Operation status
  Status Codes: | 200 OK – Request completed successfully 400 Bad Request – Invalid JSON data

  Request:

      PUT /db/_revs_limit HTTP/1.1
      Accept: application/json
      Content-Length: 5
      Content-Type: application/json
      Host: localhost:5984

      1000

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 12
      Content-Type: application/json
      Date: Mon, 12 Aug 2013 17:47:52 GMT
      Server: CouchDB (Erlang/OTP)

      {
          "ok": true
      }