10.3.2. /db/_all_docs — Apache CouchDB 1.6 Documentation

### Navigation

- API Reference
- Config Reference |
- next |
- previous |
- Apache CouchDB 1.6 Documentation »
- 10. API Reference »
- 10.3. Databases »

# 10.3.2. `/db/_all_docs`

`GET` `/{db}/_all_docs`

  Returns a JSON structure of all of the 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 documents and basic contents, consisting the ID, revision and key. The key is the from the document’s `_id`.

  Parameters: | db – Database name
  Request Headers:
  | Accept – application/json text/plain
  Query Parameters:
  | conflicts (boolean) – Includes conflicts information in response. Ignored if include_docs isn’t `true`. Default is `false`. descending (boolean) – Return the documents in descending by key order. Default is `false`. endkey (string) – Stop returning records when the specified key is reached. Optional. end_key (string) – Alias for endkey param. endkey_docid (string) – Stop returning records when the specified document ID is reached. Optional. end_key_doc_id (string) – Alias for endkey_docid param. include_docs (boolean) – Include the full content of the documents in the return. Default is `false`. inclusive_end (boolean) – Specifies whether the specified end key should be included in the result. Default is `true`. key (string) – Return only documents that match the specified key. Optional. limit (number) – Limit the number of the returned documents to the specified number. Optional. skip (number) – Skip this number of records before starting to return the results. Default is `0`. stale (string) – Allow the results from a stale view to be used, without triggering a rebuild of all views within the encompassing design doc. Supported values: `ok` and `update_after`. Optional. startkey (string) – Return records starting with the specified key. Optional. start_key (string) – Alias for startkey param. startkey_docid (string) – Return records starting with the specified document ID. Optional. start_key_doc_id (string) – Alias for startkey_docid param. update_seq (boolean) – Response includes an `update_seq` value indicating which sequence id of the underlying database the view reflects. Default is `false`.
  Response Headers:
  | Content-Type – application/json text/plain; charset=utf-8 ETag – Response signature
  Response JSON Object:
  | offset (number) – Offset where the document list started rows (array) – Array of view row objects. By default the information returned contains only the document ID and revision. total_rows (number) – Number of documents in the database/view. Note that this is not the number of rows returned in the actual query. update_seq (number) – Current update sequence for the database
  Status Codes: | 200 OK – Request completed successfully

  Request:

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

  Response:

      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
      }

`POST` `/{db}/_all_docs`

  The `POST` to `_all_docs` allows to specify multiple keys to be selected from the database. This enables you to request multiple documents in a single request, in place of multiple `GET /{db}/{docid}` requests.

  The request body should contain a list of the keys to be returned as an array to a `keys` object. For example:

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

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

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

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

# 10.3.3. `/db/_bulk_docs`

`POST` `/{db}/_bulk_docs`

  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.

  Parameters: | db – Database name
  Request Headers:
  | Accept – application/json text/plain Content-Type – application/json X-Couch-Full-Commit – Overrides server’s `commit policy`. Possible values are: `false` and `true`. Optional
  Request JSON Object:
  | all_or_nothing (boolean) – Sets the database commit mode to use all-or-nothing semantics. Default is `false`. Optional docs (array) – List of documents objects new_edits (boolean) – If `false`, prevents the database from assigning them new revision IDs. Default is `true`. Optional
  Response Headers:
  | Content-Type – application/json text/plain; charset=utf-8
  Response JSON Array of Objects:
  | id (string) – Document ID rev (string) – New document revision token. Available if document have saved without errors. Optional error (string) – Error type. Optional reason (string) – Error reason. Optional
  Status Codes: | 201 Created – Document(s) have been created or updated 400 Bad Request – The request provided invalid JSON data 417 Expectation Failed – Occurs when `all_or_nothing` option set as `true` and at least one document was rejected by validation function 500 Internal Server Error – Malformed data provided, while it’s still valid JSON

  Request:

      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:

      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 Bulk Documents Transaction 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:

    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"
            },
            {
                "_id": "BeefStew",
                "servings": 8,
                "subtitle": "Hand-made dumplings make a great accompaniment",
                "title": "BeefStew"
            }
        ]
    }

The return type from a bulk insertion will be 201 Created, 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:

    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": "BeefStew",
            "ok": true,
            "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
        }
    ]

The content and structure of the returned JSON will depend on the transaction semantics being used for the bulk update; see Bulk Documents Transaction Semantics for more information. Conflicts and validation errors when updating documents in bulk must be handled separately; see Bulk Document Validation and Conflict Errors.

## 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:

    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:

    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 201 Created, 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 Bulk Documents Transaction Semantics for more information. Conflicts and validation errors when updating documents in bulk must be handled separately; see Bulk Document Validation and Conflict Errors.

## Bulk Documents Transaction Semantics

CouchDB supports two different modes for updating (or inserting) documents using the bulk documentation system. Each mode affects both the state of the documents in the event of system failure, and the level of conflict checking performed on each document. The two modes are:

- non-atomic

  The default mode is non-atomic, that is, CouchDB will only guarantee that some of the documents 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, and some will have been lost.

  In this mode, 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, then you will get an `error` of type `conflict`. For example:

      [
         {
            "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.

- all-or-nothing

  In all-or-nothing mode, either all documents are written to the database, or no documents are written to the database, in the event of a system failure during commit.

  In addition, the per-document conflict checking is not performed. Instead a new revision of the document is created, even if the new revision is in conflict with the current revision in the database. The returned structure contains the list of documents with new revisions:

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

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

  When updating documents using this mode the revision of a document included in views will be arbitrary. You can check the conflict status for a document by using the `conflicts=true` query argument when accessing the view. Conflicts should be handled individually to ensure the consistency of your database.

  To use this mode, you must include the `all_or_nothing` field (set to true) within the main body of the JSON of the request.

The effects of different database operations on the different modes are summarized below:

- Transaction Mode: `Non-atomic`
  - Transaction: `Insert`
    - Cause: Requested document ID already exists
    - Resolution: Resubmit with different document ID, or update the existing document
  - Transaction: `Update`
    - Cause: Revision missing or incorrect
    - Resolution: Resubmit with correct revision
- Transaction Mode: `All-or-nothing`
  - Transaction: `Insert` / `Update`
    - Cause: Additional revision inserted
    - Resolution: Resolve conflicted revisions

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. This can mean that if you make use of the all-or-nothing mode the exact list of documents, revisions (and their conflict state) may or may not be replicated to other databases correctly.

## 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. If you used the default bulk transaction mode then the new revision will not have been created and you will need to re-submit the document to the database. If you used `all-or-nothing` mode then you will need to manually resolve the conflicted revisions of the document.

  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 validation routine includes the following:

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

  The error response returned will be:

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

      {
          "error": "forbidden",
          "id": "LambStew",
          "reason": "invalid recipe ingredient",
          "rev": "1-34c318924a8f327223eed702ddfdc66d"
      }

### Navigation

- API Reference
- Config Reference |
- next |
- previous |
- Apache CouchDB 1.6 Documentation »
- 10. API Reference »
- 10.3. Databases »