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" : "7f7638c86173eb440b8890839ff35433",
"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:
[
{
"id" : "FishStew",
"rev" : "2-e7af4c4e9981d960ecf78605d79b06d1"
},
{
"id" : "LambStew",
"rev" : "2-0786321986194c92dd3b57dfbfc741ce"
},
{
"id" : "7f7638c86173eb440b8890839ff35433",
"rev" : "2-bdd3bf3563bee516b96885a66c743f8e"
}
]
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 in the table below:
Table 5.5. Conflicts on Bulk Inserts
| Transaction Mode | Transaction | Cause | Resolution |
|---|---|---|---|
| Non-atomic | Insert | Requested document ID already exists | Resubmit with different document ID, or update the existing document |
| Non-atomic | Update | Revision missing or incorrect | Resubmit with correct revision |
| All-or-nothing | Insert | Additional revision inserted | Resolve conflicted revisions |
| All-or-nothing | Update | Additional revision inserted | 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.