.. Licensed under the Apache License, Version 2.0 (the "License"); you may not .. use this file except in compliance with the License. You may obtain a copy of .. the License at .. .. http://www.apache.org/licenses/LICENSE-2.0 .. .. Unless required by applicable law or agreed to in writing, software .. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT .. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the .. License for the specific language governing permissions and limitations under .. the License. .. _api/db/purge: ============== ``/db/_purge`` ============== .. http:post:: /{db}/_purge :synopsis: Purges some historical documents entirely from database history 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 :ref:`api/db/compact`), and compact views (see :ref:`api/db/compact/ddoc`). 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. :param db: Database name :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :>json number purge_seq: Purge sequence number :>json object purged: Mapping of document ID to list of purged revisions :code 200: Request completed successfully :code 400: Invalid database name or JSON payload :code 415: Bad :header:`Content-Type` value **Request**: .. code-block:: http 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**: .. code-block:: http 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. .. _api/db/missing_revs: ===================== ``/db/_missing_revs`` ===================== .. http:post:: /{db}/_missing_revs :synopsis: By given list of document revisions returns the document revisions that do not exist in the database With given a list of document revisions, returns the document revisions that do not exist in the database. :param db: Database name :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :>json object missing_revs: Mapping of document ID to list of missed revisions :code 200: Request completed successfully :code 400: Invalid database name or JSON payload **Request**: .. code-block:: http 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**: .. code-block:: http 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" ] } } .. _api/db/revs_diff: ================== ``/db/_revs_diff`` ================== .. http:post:: /{db}/_revs_diff :synopsis: By given list of document revisions returns differences between the given revisions and ones that are in the database 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. :param db: Database name :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :>json array missing: List of missed revisions for specified document :>json array possible_ancestors: List of revisions that *may be* ancestors for specified document and its current revision in requested database :code 200: Request completed successfully :code 400: Invalid database name or JSON payload **Request**: .. code-block:: http 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**: .. code-block:: http 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" ] } } .. _api/db/revs_limit: =================== ``/db/_revs_limit`` =================== .. http:get:: /{db}/_revs_limit :synopsis: Returns the limit of historical revisions to store for a single document in the database Gets the current ``revs_limit`` (revision limit) setting. :param db: Database name :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :code 200: Request completed successfully **Request**: .. code-block:: http GET /db/_revs_limit HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http 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 .. http:put:: /{db}/_revs_limit :synopsis: Sets the limit of historical revisions to store for a single document in the database 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. :param db: Database name :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :>json boolean ok: Operation status :code 200: Request completed successfully :code 400: Invalid JSON data **Request**: .. code-block:: http PUT /db/_revs_limit HTTP/1.1 Accept: application/json Content-Length: 5 Content-Type: application/json Host: localhost:5984 1000 **Response**: .. code-block:: http 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 }