src/api/database/misc.rst

.. 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 Accept: - :mimetype:`application/json`
                     - :mimetype:`text/plain`
    :<header Content-Type: :mimetype:`application/json`
    :<json object: Mapping of document ID to list of revisions to purge
    :>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 Accept: - :mimetype:`application/json`
                     - :mimetype:`text/plain`
    :<header Content-Type: :mimetype:`application/json`
    :<json object: Mapping of document ID to list of revisions to lookup
    :>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 Accept: - :mimetype:`application/json`
                     - :mimetype:`text/plain`
    :<header Content-Type: :mimetype:`application/json`
    :<json object: Mapping of document ID to list of revisions to lookup
    :>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 Accept: - :mimetype:`application/json`
                     - :mimetype:`text/plain`
    :>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 Accept: - :mimetype:`application/json`
                     - :mimetype:`text/plain`
    :<header Content-Type: :mimetype:`application/json`
    :>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
        }