CouchDB Writes: Piecemeal, Bulk, or Batch?

Which write API endpoint is the right write call for you?

Glynn Bird
Jul 25, 2017 · 5 min read

CouchDB clusters 101

A 6-node CouchDB cluster.

Piecemeal writes

curl -v -X POST \
-H 'Content-type: application/json' \
-d '{"name": "Mittens", "type": "cat"}' \
"$COUCH_URL/animals"
HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 95
Content-Type: application/json
Date: Fri, 02 Jun 2017 06:33:08 GMT
Location: http://localhost:5984/animals/
{"ok":true,"id":"7bff55e2a7f9fa3a999c1f76bd00044b","rev":"1-76558a77771fb4c1f81d4d91144dc83f"}
A basic write request for the new “Mittens” document. Note that each node in the cluster does not get the write—rather, it’s each of the three shards that gets the write.

Bulk writes

curl -v -X POST \
-H 'Content-type: application/json' \
-d '{"docs": [{"name": "Snowy", "type": "cat"},{"name": "Patch", "type": "dog"}]}' \
"$COUCH_URL/animals/_bulk_docs"
HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 192
Content-Type: application/json
Date: Fri, 02 Jun 2017 06:44:45 GMT
[{"ok":true,"id":"7bff55e2a7f9fa3a999c1f76bd001d39","rev":"1-263fbfee100b3417c513b14f4dacd776"},{"ok":true,"id":"7bff55e2a7f9fa3a999c1f76bd00202b","rev":"1-591fadc21c08df0ba8efa5c5912c1cfb"}]
A basic bulk write request. Two more new documents are added, this time together as an array.
{
"docs": [
{ "name": "Paws", "type": "cat" },
{ "_id": "7bff55e2a7f9fa3a999c1f76bd001d39", "_rev": "1-263fbfee100b3417c513b14f4dacd776", "name": "Snowie", "type": "cat"},
{ "_id": "7bff55e2a7f9fa3a999c1f76bd00202b", "_rev": "1-591fadc21c08df0ba8efa5c5912c1cfb", "_deleted": true}
]
}
Bulk write requests can contain a mixture of inserts, updates, and deletes. The bulk request adds Paws, updates “Snowy” to “Snowie”, and deletes Patch.

Batch writes

curl -v -X POST \
-H 'Content-type: application/json' \
-d '{"name": "Tiddles", "type": "cat"}' \
"$COUCH_URL/animals?batch=ok"
HTTP/1.1 202 Accepted
Cache-Control: must-revalidate
Content-Length: 52
Content-Type: application/json
Date: Fri, 02 Jun 2017 07:01:50 GMT
{"ok":true,"id":"7bff55e2a7f9fa3a999c1f76bd002cec"}

References

IBM CODAIT

Things we made with data at IBM’s Center for Open Source Data and AI Technologies.

Thanks to Mike Broberg and Teri Chadbourne.

Glynn Bird

Written by

Developer @ IBM. https://glynnbird.com

IBM CODAIT

Things we made with data at IBM’s Center for Open Source Data and AI Technologies.