Skip to content

Bulk GET

Jump to bottom
Jens Alfke edited this page Apr 8, 2016 · 3 revisions

_bulk_get is a nonstandard (i.e. non-CouchDB) addition to the sync API. It improves performance of client pull replications, by allowing the client to request multiple documents in one request.

Why is this necessary?

The usual CouchDB API for bulk gets -- a POST to _all_docs with an array of docIDs in the body -- isn't suitable for the replicator because:

  • there's no way to specify which specific revisions are needed (it always returns the default revision),
  • the response doesn't contain the revision history,
  • there's no way to specify that only recently changed attachments should be included (a la atts_since),
  • and attachment bodies can only be encoded inline (base64) not as MIME multipart bodies.

Request Format

POST /db/_bulk_get

URL Query Parameters

  • ?revs=true: Each returned revision body will include its revision history as a _revisions property.
  • ?attachments=true: Attachments will be included in the response.

Body

A JSON object with a property "docs" whose value is an array of objects, each describing a revision to return. Each of these objects has properties "id", "rev", and optionally "atts_since" -- these have the same meanings as the URL query parameters on a usual single-document GET request.

Example:

    {"docs": [
        {"id": "somedoc", "rev": "2-cafebabe", "atts_since": ["1-feed1337",...]},
        {"id": "otherdoc", "rev": "5-bedbedbe"}, ...
    ]}

Response Format

The response is of type multipart/related. Each MIME body part contains one document revision. The ordering is the same as in the array in the request.

Each revision itself is encoded as multipart, in the same format as a document GET request with attachments: the main JSON body comes first, then a body for each attachment. Each attachment body has a Content-Disposition header identifying its attachment name.

If there's an error getting a document revision, most likely because it doesn't exist, its corresponding JSON body in the response will contain only the properties "id", "error", "reason" and "status", just as in a response from _all_docs.

Clone this wiki locally