.. 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/all_docs:

===================
``/{db}/_all_docs``
===================

.. http:get:: /{db}/_all_docs
    :synopsis: Returns a built-in view of all documents in this database

    Executes the built-in `_all_docs` :ref:`view <views>`, returning all of the
    documents in the database.  With the exception of the URL parameters
    (described below), this endpoint works identically to any other view. Refer
    to the :ref:`view endpoint <api/ddoc/view>` documentation for a complete
    description of the available query parameters and the format of the returned
    data.

    :param db: Database name
    :<header Content-Type: :mimetype:`application/json`
    :>header Content-Type: - :mimetype:`application/json`

    :code 200: Request completed successfully
    :code 401: Unauthorized request to a protected API
    :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
    :code 404: Requested database not found

    **Request**:

    .. code-block:: http

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

    **Response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Cache-Control: must-revalidate
        Content-Type: application/json
        Date: Sat, 10 Aug 2013 16:22:56 GMT
        ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
        Server: CouchDB (Erlang/OTP)
        Transfer-Encoding: chunked

        {
            "offset": 0,
            "rows": [
                {
                    "id": "16e458537602f5ef2a710089dffd9453",
                    "key": "16e458537602f5ef2a710089dffd9453",
                    "value": {
                        "rev": "1-967a00dff5e02add41819138abb3284d"
                    }
                },
                {
                    "id": "a4c51cdfa2069f3e905c431114001aff",
                    "key": "a4c51cdfa2069f3e905c431114001aff",
                    "value": {
                        "rev": "1-967a00dff5e02add41819138abb3284d"
                    }
                },
                {
                    "id": "a4c51cdfa2069f3e905c4311140034aa",
                    "key": "a4c51cdfa2069f3e905c4311140034aa",
                    "value": {
                        "rev": "5-6182c9c954200ab5e3c6bd5e76a1549f"
                    }
                },
                {
                    "id": "a4c51cdfa2069f3e905c431114003597",
                    "key": "a4c51cdfa2069f3e905c431114003597",
                    "value": {
                        "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
                    }
                },
                {
                    "id": "f4ca7773ddea715afebc4b4b15d4f0b3",
                    "key": "f4ca7773ddea715afebc4b4b15d4f0b3",
                    "value": {
                        "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
                    }
                }
            ],
            "total_rows": 5
        }

.. http:post:: /{db}/_all_docs
    :synopsis: Returns a built-in view of all documents in this database

    :method:`POST` `_all_docs` functionality supports identical parameters and behavior
    as specified in the :get:`/{db}/_all_docs` API but allows for the query string
    parameters to be supplied as keys in a JSON object in the body of the `POST` request.

    **Request**:

    .. code-block:: http

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

        {
            "keys" : [
                "Zingylemontart",
                "Yogurtraita"
            ]
        }

    **Response**:

    .. code-block:: javascript

        {
            "total_rows" : 2666,
            "rows" : [
                {
                    "value" : {
                        "rev" : "1-a3544d296de19e6f5b932ea77d886942"
                    },
                    "id" : "Zingylemontart",
                    "key" : "Zingylemontart"
                },
                {
                    "value" : {
                        "rev" : "1-91635098bfe7d40197a1b98d7ee085fc"
                    },
                    "id" : "Yogurtraita",
                    "key" : "Yogurtraita"
                }
            ],
            "offset" : 0
        }

.. _api/db/design_docs:

======================
``/{db}/_design_docs``
======================

.. versionadded:: 2.2

.. http:get:: /{db}/_design_docs
    :synopsis: Returns a built-in view of all design documents in this database

    Returns a JSON structure of all of the design documents in a given
    database. The information is returned as a JSON structure containing meta
    information about the return structure, including a list of all design
    documents and basic contents, consisting the ID, revision and key. The key
    is the design document's ``_id``.

    :param db: Database name
    :<header Accept: - :mimetype:`application/json`
                     - :mimetype:`text/plain`
    :query boolean conflicts: Includes `conflicts` information in response.
      Ignored if `include_docs` isn't ``true``. Default is ``false``.
    :query boolean descending: Return the design documents in descending by
      key order. Default is ``false``.
    :query string endkey: Stop returning records when the specified key is
      reached. *Optional*.
    :query string end_key: Alias for `endkey` param.
    :query string endkey_docid: Stop returning records when the specified
        design document ID is reached. *Optional*.
    :query string end_key_doc_id: Alias for `endkey_docid` param.
    :query boolean include_docs: Include the full content of the design
      documents in the return. Default is ``false``.
    :query boolean inclusive_end: Specifies whether the specified end key
      should be included in the result. Default is ``true``.
    :query string key: Return only design documents that match the specified
      key. *Optional*.
    :query string keys: Return only design documents that match the specified
      keys. *Optional*.
    :query number limit: Limit the number of the returned design documents to
      the specified number. *Optional*.
    :query number skip: Skip this number of records before starting to return
      the results. Default is ``0``.
    :query string startkey: Return records starting with the specified key.
      *Optional*.
    :query string start_key: Alias for `startkey` param.
    :query string startkey_docid: Return records starting with the specified
      design document ID. *Optional*.
    :query string start_key_doc_id: Alias for `startkey_docid` param.
    :query boolean update_seq: Response includes an ``update_seq`` value
      indicating which sequence id of the underlying database the view
      reflects. Default is ``false``.
    :>header Content-Type: - :mimetype:`application/json`
                           - :mimetype:`text/plain; charset=utf-8`
    :>header ETag: Response signature
    :>json number offset: Offset where the design document list started
    :>json array rows: Array of view row objects. By default the information
      returned contains only the design document ID and revision.
    :>json number total_rows: Number of design documents in the database. Note
      that this is not the number of rows returned in the actual query.
    :>json number update_seq: Current update sequence for the database

    :code 200: Request completed successfully
    :code 401: Unauthorized request to a protected API
    :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
    :code 404: Requested database not found

    **Request**:

    .. code-block:: http

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

    **Response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Cache-Control: must-revalidate
        Content-Type: application/json
        Date: Sat, 23 Dec 2017 16:22:56 GMT
        ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
        Server: CouchDB (Erlang/OTP)
        Transfer-Encoding: chunked

        {
            "offset": 0,
            "rows": [
                {
                    "id": "_design/ddoc01",
                    "key": "_design/ddoc01",
                    "value": {
                        "rev": "1-7407569d54af5bc94c266e70cbf8a180"
                    }
                },
                {
                    "id": "_design/ddoc02",
                    "key": "_design/ddoc02",
                    "value": {
                        "rev": "1-d942f0ce01647aa0f46518b213b5628e"
                    }
                },
                {
                    "id": "_design/ddoc03",
                    "key": "_design/ddoc03",
                    "value": {
                        "rev": "1-721fead6e6c8d811a225d5a62d08dfd0"
                    }
                },
                {
                    "id": "_design/ddoc04",
                    "key": "_design/ddoc04",
                    "value": {
                        "rev": "1-32c76b46ca61351c75a84fbcbceece2f"
                    }
                },
                {
                    "id": "_design/ddoc05",
                    "key": "_design/ddoc05",
                    "value": {
                        "rev": "1-af856babf9cf746b48ae999645f9541e"
                    }
                }
            ],
            "total_rows": 5
        }

.. http:post:: /{db}/_design_docs
    :synopsis: Returns a built-in view of all design documents in this database

    :method:`POST` `_design_docs` functionality supports identical parameters and behavior
    as specified in the :get:`/{db}/_design_docs` API but allows for the query string
    parameters to be supplied as keys in a JSON object in the body of the `POST` request.

    **Request**:

    .. code-block:: http

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

        {
            "keys" : [
                "_design/ddoc02",
                "_design/ddoc05"
            ]
        }

    The returned JSON is the all documents structure, but with only the
    selected keys in the output:

    **Response**:

    .. code-block:: javascript

        {
            "total_rows" : 5,
            "rows" : [
                {
                    "value" : {
                        "rev" : "1-d942f0ce01647aa0f46518b213b5628e"
                    },
                    "id" : "_design/ddoc02",
                    "key" : "_design/ddoc02"
                },
                {
                    "value" : {
                        "rev" : "1-af856babf9cf746b48ae999645f9541e"
                    },
                    "id" : "_design/ddoc05",
                    "key" : "_design/ddoc05"
                }
            ],
            "offset" : 0
        }

Sending multiple queries to a database
======================================

.. _api/db/_all_docs/queries:

``/{db}/_all_docs/queries``
---------------------------

.. versionadded:: 2.2

.. http:post:: /{db}/_all_docs/queries
    :synopsis: Returns results for the specified queries

    Executes multiple specified built-in view queries of all documents in this
    database. This enables you to request multiple queries in a single
    request, in place of multiple :post:`/{db}/_all_docs` requests.

    :param db: Database name

    :<header Content-Type: - :mimetype:`application/json`
    :<header Accept: - :mimetype:`application/json`

    :<json queries: An array of query objects with fields for the
        parameters of each individual view query to be executed. The field names
        and their meaning are the same as the query parameters of a
        regular :ref:`_all_docs request <api/db/all_docs>`.

    :>header Content-Type: - :mimetype:`application/json`
                           - :mimetype:`text/plain; charset=utf-8`
    :>header ETag: Response signature
    :>header Transfer-Encoding: ``chunked``

    :>json array results: An array of result objects - one for each query. Each
        result object contains the same fields as the response to a regular
        :ref:`_all_docs request <api/db/all_docs>`.

    :code 200: Request completed successfully
    :code 400: Invalid request
    :code 401: Unauthorized request to a protected API
    :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
    :code 404: Specified database is missing
    :code 500: Query execution error

    **Request**:

    .. code-block:: http

        POST /db/_all_docs/queries HTTP/1.1
        Content-Type: application/json
        Accept: application/json
        Host: localhost:5984

        {
            "queries": [
                {
                    "keys": [
                        "meatballs",
                        "spaghetti"
                    ]
                },
                {
                    "limit": 3,
                    "skip": 2
                }
            ]
        }

    **Response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Cache-Control: must-revalidate
        Content-Type: application/json
        Date: Wed, 20 Dec 2017 11:17:07 GMT
        ETag: "1H8RGBCK3ABY6ACDM7ZSC30QK"
        Server: CouchDB (Erlang/OTP)
        Transfer-Encoding: chunked

        {
            "results" : [
                {
                    "rows": [
                        {
                            "id": "meatballs",
                            "key": "meatballs",
                            "value": 1
                        },
                        {
                            "id": "spaghetti",
                            "key": "spaghetti",
                            "value": 1
                        }
                    ],
                    "total_rows": 3
                },
                {
                    "offset" : 2,
                    "rows" : [
                        {
                            "id" : "Adukiandorangecasserole-microwave",
                            "key" : "Aduki and orange casserole - microwave",
                            "value" : [
                                null,
                                "Aduki and orange casserole - microwave"
                            ]
                        },
                        {
                            "id" : "Aioli-garlicmayonnaise",
                            "key" : "Aioli - garlic mayonnaise",
                            "value" : [
                                null,
                                "Aioli - garlic mayonnaise"
                            ]
                        },
                        {
                            "id" : "Alabamapeanutchicken",
                            "key" : "Alabama peanut chicken",
                            "value" : [
                                null,
                                "Alabama peanut chicken"
                            ]
                        }
                    ],
                    "total_rows" : 2667
                }
            ]
        }

    .. Note::
        The multiple queries are also supported in
        :ref:`/{db}/_local_docs/queries <api/db/_local_docs/queries>` and
        :ref:`/{db}/_design_docs/queries <api/db/_design_docs/queries>`
        (similar to :ref:`/{db}/_all_docs/queries <api/db/_all_docs/queries>`).

.. _api/db/_design_docs/queries:

``/{db}/_design_docs/queries``
------------------------------

.. http:post:: /{db}/_design_docs/queries
    :synopsis: Returns results for the specified queries

    Querying with specified ``keys`` will return design documents only.
    You can also combine ``keys`` with other query parameters,
    such as ``limit`` and ``skip``.

    :param db: Database name

    :<header Content-Type: - :mimetype:`application/json`
    :<header Accept: - :mimetype:`application/json`

    :<json queries: An array of query objects with fields for the
        parameters of each individual view query to be executed.
        The field names and their meaning are the same as the query
        parameters of a regular
        :ref:`_design_docs request <api/db/design_docs>`.

    :>header Content-Type: - :mimetype:`application/json`
                           - :mimetype:`text/plain; charset=utf-8`
    :>header Transfer-Encoding: ``chunked``

    :>json array results: An array of result objects - one for each query. Each
        result object contains the same fields as the response to a regular
        :ref:`_design_docs request <api/db/design_docs>`.

    :code 200: Request completed successfully
    :code 400: Invalid request
    :code 401: Unauthorized request to a protected API
    :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
    :code 404: Specified database is missing
    :code 500: Query execution error

    **Request**:

    .. code-block:: http

        POST /db/_design_docs/queries HTTP/1.1
        Content-Type: application/json
        Accept: application/json
        Host: localhost:5984

        {
            "queries": [
                {
                    "keys": [
                        "_design/recipe",
                        "_design/not-exist",
                        "spaghetti"
                    ]
                }
            ]
        }

    **Response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Cache-Control: must-revalidate
        Content-Type: application/json
        Date: Thu, 20 Jul 2023 20:06:44 GMT
        Server: CouchDB (Erlang/OTP)
        Transfer-Encoding: chunked

        {
            "results": [
                {
                    "total_rows": 1,
                    "offset": null,
                    "rows": [
                        {
                            "id": "_design/recipe",
                            "key": "_design/recipe",
                            "value": {
                                "rev": "1-ad0e29fe6b473658514742a7c2317766"
                            }
                        },
                        {
                            "key": "_design/not-exist",
                            "error": "not_found"
                        }
                    ]
                }
            ]
        }

    .. Note::
        /{db}/_design_docs/queries with keys will only return design documents,
        or ``"error": "not_found"`` if the design document doesn't exist. If
        ``key`` is not a design document id, it will not be included in the
        response.

.. _api/db/bulk_get:

===================
``/{db}/_bulk_get``
===================

.. http:post:: /{db}/_bulk_get
    :synopsis: Fetches several documents at the given revisions

    This method can be called to query several documents in bulk. It is well
    suited for fetching a specific revision of documents, as replicators do for
    example, or for getting revision history.  Refer to the
    :ref:`document endpoint <api/doc>` documentation for  a complete
    description of the available query parameters.

    :param db: Database name
    :<header Accept: - :mimetype:`application/json`
                     - :mimetype:`multipart/related`
                     - :mimetype:`multipart/mixed`
    :<header Content-Type: :mimetype:`application/json`
    :<json array docs: List of document objects, with ``id``, and optionally
      ``rev`` and ``atts_since``
    :>header Content-Type: - :mimetype:`application/json`
    :>json object results: an array of results for each requested document/rev
      pair. ``id`` key lists the requested document ID, ``docs`` contains a
      single-item array of objects, each of which has either an ``error`` key and
      value describing the error, or ``ok`` key and associated value of the
      requested document, with the additional ``_revisions`` property that lists
      the parent revisions if ``revs=true``.

    :code 200: Request completed successfully
    :code 400: The request provided invalid JSON data or invalid query parameter
    :code 401: Unauthorized request to a protected API
    :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
    :code 404: Invalid database name
    :code 415: Bad :header:`Content-Type` value

    **Request**:

    .. code-block:: http

        POST /db/_bulk_get HTTP/1.1
        Accept: application/json
        Content-Type:application/json
        Host: localhost:5984

        {
            "docs": [
                {
                    "id": "foo"
                    "rev": "4-753875d51501a6b1883a9d62b4d33f91",
                },
                {
                    "id": "foo"
                    "rev": "1-4a7e4ae49c4366eaed8edeaea8f784ad",
                },
                {
                    "id": "bar"
                }
                {
                    "id": "baz"
                }
            ]
        }

    **Response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Cache-Control: must-revalidate
        Content-Type: application/json
        Date: Mon, 19 Mar 2018 15:27:34 GMT
        Server: CouchDB (Erlang/OTP)

        {
          "results": [
            {
              "id": "foo",
              "docs": [
                {
                  "ok": {
                    "_id": "foo",
                    "_rev": "4-753875d51501a6b1883a9d62b4d33f91",
                    "value": "this is foo",
                    "_revisions": {
                      "start": 4,
                      "ids": [
                        "753875d51501a6b1883a9d62b4d33f91",
                        "efc54218773c6acd910e2e97fea2a608",
                        "2ee767305024673cfb3f5af037cd2729",
                        "4a7e4ae49c4366eaed8edeaea8f784ad"
                      ]
                    }
                  }
                }
              ]
            },
            {
              "id": "foo",
              "docs": [
                {
                  "ok": {
                    "_id": "foo",
                    "_rev": "1-4a7e4ae49c4366eaed8edeaea8f784ad",
                    "value": "this is the first revision of foo",
                    "_revisions": {
                      "start": 1,
                      "ids": [
                        "4a7e4ae49c4366eaed8edeaea8f784ad"
                      ]
                    }
                  }
                }
              ]
            },
            {
              "id": "bar",
              "docs": [
                {
                  "ok": {
                    "_id": "bar",
                    "_rev": "2-9b71d36dfdd9b4815388eb91cc8fb61d",
                    "baz": true,
                    "_revisions": {
                      "start": 2,
                      "ids": [
                        "9b71d36dfdd9b4815388eb91cc8fb61d",
                        "309651b95df56d52658650fb64257b97"
                      ]
                    }
                  }
                }
              ]
            },
            {
              "id": "baz",
              "docs": [
                {
                  "error": {
                    "id": "baz",
                    "rev": "undefined",
                    "error": "not_found",
                    "reason": "missing"
                  }
                }
              ]
            }
          ]
        }

    Example response with a conflicted document:

    **Request**:

    .. code-block:: http

        POST /db/_bulk_get HTTP/1.1
        Accept: application/json
        Content-Type:application/json
        Host: localhost:5984

        {
            "docs": [
                {
                    "id": "a"
                }
            ]
        }

    **Response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Cache-Control: must-revalidate
        Content-Type: application/json
        Date: Mon, 19 Mar 2018 15:27:34 GMT
        Server: CouchDB (Erlang/OTP)

        {
          "results": [
            {
              "id": "a",
              "docs": [
                {
                  "ok": {
                    "_id": "a",
                    "_rev": "1-23202479633c2b380f79507a776743d5",
                    "a": 1
                  }
                },
                {
                  "ok": {
                    "_id": "a",
                    "_rev": "1-967a00dff5e02add41819138abb3284d"
                  }
                }
              ]
            }
          ]
        }

.. _api/db/bulk_docs:

====================
``/{db}/_bulk_docs``
====================

.. http:post:: /{db}/_bulk_docs
    :synopsis: Inserts or updates multiple documents in to the database in
               a single request

    The bulk document API allows you to create and update multiple documents
    at the same time within a single request. The basic operation is similar
    to creating or updating a single document, except that you batch the
    document structure and information.

    When creating new documents the document ID (``_id``) is optional.

    For updating existing documents, you must provide the document ID, revision
    information (``_rev``), and new document values.

    In case of batch deleting documents all fields as document ID, revision
    information and deletion status (``_deleted``) are required.

    :param db: Database name
    :<header Accept: - :mimetype:`application/json`
                     - :mimetype:`text/plain`
    :<header Content-Type: :mimetype:`application/json`

    :<json array docs: List of documents objects
    :<json boolean new_edits: If ``false``, prevents the database from
      assigning them new revision IDs. Default is ``true``. *Optional*
    :>header Content-Type: - :mimetype:`application/json`
                           - :mimetype:`text/plain; charset=utf-8`
    :>jsonarr string id: Document ID
    :>jsonarr string rev: New document revision token. Available
      if document has saved without errors. *Optional*
    :>jsonarr string error: Error type. *Optional*
    :>jsonarr string reason: Error reason. *Optional*

    :code 201: Document(s) have been created or updated
    :code 400: The request provided invalid JSON data
    :code 401: Unauthorized request to a protected API
    :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
    :code 404: Requested database not found

    **Request**:

    .. code-block:: http

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

        {
            "docs": [
                {
                    "_id": "FishStew"
                },
                {
                    "_id": "LambStew",
                    "_rev": "2-0786321986194c92dd3b57dfbfc741ce",
                    "_deleted": true
                }
            ]
        }

    **Response**:

    .. code-block:: http

        HTTP/1.1 201 Created
        Cache-Control: must-revalidate
        Content-Length: 144
        Content-Type: application/json
        Date: Mon, 12 Aug 2013 00:15:05 GMT
        Server: CouchDB (Erlang/OTP)

        [
            {
                "ok": true,
                "id": "FishStew",
                "rev":" 1-967a00dff5e02add41819138abb3284d"
            },
            {
                "ok": true,
                "id": "LambStew",
                "rev": "3-f9c62b2169d0999103e9f41949090807"
            }
        ]

Inserting Documents in Bulk
===========================

Each time a document is stored or updated in CouchDB, the internal B-tree
is updated. Bulk insertion provides efficiency gains in both storage space,
and time, by consolidating many of the updates to intermediate B-tree nodes.

It is not intended as a way to perform ``ACID``-like transactions in CouchDB,
the only transaction boundary within CouchDB is a single update to a single
database. The constraints are detailed in :ref:`api/db/bulk_docs/semantics`.

To insert documents in bulk into a database you need to supply a JSON
structure with the array of documents that you want to add to the database.
You can either include a document ID, or allow the document ID to be
automatically generated.

For example, the following update inserts three new documents, two with the
supplied document IDs, and one which will have a document ID generated:

.. code-block:: http

    POST /source/_bulk_docs HTTP/1.1
    Accept: application/json
    Content-Length: 323
    Content-Type: application/json
    Host: localhost:5984

    {
        "docs": [
            {
                "_id": "FishStew",
                "servings": 4,
                "subtitle": "Delicious with freshly baked bread",
                "title": "FishStew"
            },
            {
                "_id": "LambStew",
                "servings": 6,
                "subtitle": "Serve with a whole meal scone topping",
                "title": "LambStew"
            },
            {
                "servings": 8,
                "subtitle": "Hand-made dumplings make a great accompaniment",
                "title": "BeefStew"
            }
        ]
    }

The return type from a bulk insertion will be :statuscode:`201`,
with the content of the returned structure indicating specific success
or otherwise messages on a per-document basis.

The return structure from the example above contains a list of the
documents created, here with the combination and their revision IDs:

.. code-block:: http

    HTTP/1.1 201 Created
    Cache-Control: must-revalidate
    Content-Length: 215
    Content-Type: application/json
    Date: Sat, 26 Oct 2013 00:10:39 GMT
    Server: CouchDB (Erlang OTP)

    [
        {
            "id": "FishStew",
            "ok": true,
            "rev": "1-6a466d5dfda05e613ba97bd737829d67"
        },
        {
            "id": "LambStew",
            "ok": true,
            "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
        },
        {
            "id": "00a271787f89c0ef2e10e88a0c0003f0",
            "ok": true,
            "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
        }
    ]

For details of the semantic content and structure of the returned JSON see
:ref:`api/db/bulk_docs/semantics`. Conflicts and validation errors when
updating documents in bulk must be handled separately; see
:ref:`api/db/bulk_docs/validation`.

Updating Documents in Bulk
==========================

The bulk document update procedure is similar to the insertion
procedure, except that you must specify the document ID and current
revision for every document in the bulk update JSON string.

For example, you could send the following request:

.. code-block:: http

    POST /recipes/_bulk_docs HTTP/1.1
    Accept: application/json
    Content-Length: 464
    Content-Type: application/json
    Host: localhost:5984

    {
        "docs": [
            {
                "_id": "FishStew",
                "_rev": "1-6a466d5dfda05e613ba97bd737829d67",
                "servings": 4,
                "subtitle": "Delicious with freshly baked bread",
                "title": "FishStew"
            },
            {
                "_id": "LambStew",
                "_rev": "1-648f1b989d52b8e43f05aa877092cc7c",
                "servings": 6,
                "subtitle": "Serve with a whole meal scone topping",
                "title": "LambStew"
            },
            {
                "_id": "BeefStew",
                "_rev": "1-e4602845fc4c99674f50b1d5a804fdfa",
                "servings": 8,
                "subtitle": "Hand-made dumplings make a great accompaniment",
                "title": "BeefStew"
            }
        ]
    }

The return structure is the JSON of the updated documents, with the new
revision and ID information:

.. code-block:: http

    HTTP/1.1 201 Created
    Cache-Control: must-revalidate
    Content-Length: 215
    Content-Type: application/json
    Date: Sat, 26 Oct 2013 00:10:39 GMT
    Server: CouchDB (Erlang OTP)

    [
        {
            "id": "FishStew",
            "ok": true,
            "rev": "2-2bff94179917f1dec7cd7f0209066fb8"
        },
        {
            "id": "LambStew",
            "ok": true,
            "rev": "2-6a7aae7ac481aa98a2042718d09843c4"
        },
        {
            "id": "BeefStew",
            "ok": true,
            "rev": "2-9801936a42f06a16f16c30027980d96f"
        }
    ]

You can optionally delete documents during a bulk update by adding the
``_deleted`` field with a value of ``true`` to each document ID/revision
combination within the submitted JSON structure.

The return type from a bulk insertion will be :statuscode:`201`, with the
content of the returned structure indicating specific success or otherwise
messages on a per-document basis.

The content and structure of the returned JSON will depend on the transaction
semantics being used for the bulk update; see :ref:`api/db/bulk_docs/semantics`
for more information. Conflicts and validation errors when updating documents
in bulk must be handled separately; see :ref:`api/db/bulk_docs/validation`.

.. _api/db/bulk_docs/semantics:

Bulk Documents Transaction Semantics
====================================

Bulk document operations are **non-atomic**. This means that CouchDB does not
guarantee that any individual document included in the bulk update (or insert)
will be saved when you send the request. The response will contain the list of
documents successfully inserted or updated during the process. In the event of
a crash, some of the documents may have been successfully saved, while others
lost.

The response structure will indicate whether the document was updated by
supplying the new ``_rev`` parameter indicating a new document revision was
created. If the update failed, you will get an ``error`` of type ``conflict``.
For example:

.. code-block:: javascript

   [
       {
           "id" : "FishStew",
           "error" : "conflict",
           "reason" : "Document update conflict."
       },
       {
           "id" : "LambStew",
           "error" : "conflict",
           "reason" : "Document update conflict."
       },
       {
           "id" : "BeefStew",
           "error" : "conflict",
           "reason" : "Document update conflict."
       }
   ]

In this case no new revision has been created and you will need to submit the
document update, with the correct revision tag, to update the document.

Replication of documents is independent of the type of insert or update.
The documents and revisions created during a bulk insert or update are
replicated in the same way as any other document.

.. _api/db/bulk_docs/validation:

Bulk Document Validation and Conflict Errors
============================================

The JSON returned by the ``_bulk_docs`` operation consists of an array
of JSON structures, one for each document in the original submission.
The returned JSON structure should be examined to ensure that all of the
documents submitted in the original request were successfully added to
the database.

When a document (or document revision) is not correctly committed to the
database because of an error, you should check the ``error`` field to
determine error type and course of action. Errors will be one of the
following type:

-  **conflict**

   The document as submitted is in conflict. The new revision will not have been
   created and you will need to re-submit the document to the database.

   Conflict resolution of documents added using the bulk docs interface
   is identical to the resolution procedures used when resolving
   conflict errors during replication.

-  **forbidden**

   Entries with this error type indicate that the validation routine
   applied to the document during submission has returned an error.

   For example, if your :ref:`validation routine <vdufun>` includes
   the following:

   .. code-block:: javascript

       throw({forbidden: 'invalid recipe ingredient'});

   The error response returned will be:

   .. code-block:: http

       HTTP/1.1 201 Created
       Cache-Control: must-revalidate
       Content-Length: 80
       Content-Type: application/json
       Date: Sat, 26 Oct 2013 00:05:17 GMT
       Server: CouchDB (Erlang OTP)

       [
           {
               "id": "LambStew",
               "error": "forbidden",
               "reason": "invalid recipe ingredient"
           }
       ]
