couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Couchdb Wiki] Update of "HTTP Document API" by BrianCandler
Date Tue, 24 Mar 2009 13:57:20 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The following page has been changed by BrianCandler:
http://wiki.apache.org/couchdb/HTTP_Document_API

The comment on the change is:
Correct behaviour of _bulk_docs

------------------------------------------------------------------------------
  
  Note that CouchDB will return in the response an id and revision for every document passed
as content to a bulk insert, even for those that were just deleted.
  
+ If the _rev does not match the current version of the document, then that particular document
will ''not'' be saved and will be reported as a conflict, but this does not prevent other
documents in the batch from being saved.
+ 
+ {{{
+ [
+     {"_id": "0", "error:" "conflict", "reason": "Document update conflict."},
+     {"_id": "1", "_rev": "725846561", "integer": 2, "string": "2"},
+     {"_id": "2", "_rev": "517381856", "integer": 3, "string": "3"}
+ ]
+ }}}
+ 
+ 
  == Transactional Semantics with Bulk Updates ==
  
  In previous releases of CouchDB, bulk updates were transactional - in particular, all requests
in a bulk update failed if any request failed or was in conflict. There were a couple of problems
with this approach:
@@ -378, +389 @@

  
     * If your database is partitioned (aka "sharded"), different documents within the transaction
could live on different nodes in the cluster, and these kinds of transactional semantics don't
work unless you use heavy, non-scalable approaches like two-phase commit.
  
- With release 0.9 of CouchDB, transactional semantics have been changed so that a CouchDB
server behaves consistently in a single-node, replicated, and/or partitioned environment.
 There are now two transactional models supported:
+ With release 0.9 of CouchDB, bulk update semantics have been changed so that a CouchDB server
behaves consistently in a single-node, replicated, and/or partitioned environment. Note that
this change makes explicit the fact that CouchDB is not a relational store and does not guarantee
relational consistency between documents. As a developer you need to be aware of these semantics
and design your data model and your application with this in mind.
  
-    * '''non-atomic''' - This is the default behavior.  Some documents may successfully be
saved and some may not.  It is up to the application to check that all documents were successfully
saved/updated.
+ There are now two bulk update models supported:
  
-    * '''all-or-nothing''' - To use this mode, include {{{"all-or-nothing":true}}} as part
of the request.  In this case either all the documents will commit successfully or none will.
However, it does not do conflict checking, so the documents will be committed even if there
are conflicts.  If any documents have a conflict, then in the response that document will
show a conflict error, for example, given the request
+    * '''non-atomic''' - This is the default behavior.  Some documents may successfully be
saved and some may not.  The response will tell the application which documents were saved
or not. In the case of a power failure, when the database restarts some may have been saved
and some not.
+ 
+    * '''all-or-nothing''' - To use this mode, include {{{"all-or-nothing":true}}} as part
of the request.  In the case of a power failure, when the database restarts either all the
changes will have been saved or none of them.  However, it does not do conflict checking,
so the documents will be committed even if this creates conflicts.
  
  {{{
  {
@@ -395, +408 @@

  }
  }}}
  
- You could potentially get the response
+ In this case, all three documents will be saved, and the response will show success for
all of them. However if the document with id 0 had a conflict, both versions will be present
in the database, with an arbitrary choice made as to which appears in views. You can check
for this status using a GET with {{{?conflicts=true}}}
  
+ All your updates will always be accepted - even if you give a non-existent _rev - so the
term "all or nothing" really only applies to what happens in a crash scenario. (FIXME: is
the all-or-nothing transaction guaranteed across replication too?)
- {{{
- {
-   "docs": [
-     {"_id": "0", "error:" "conflict", "reason": "Document update conflict."},
-     {"_id": "1", "_rev": "725846561", "integer": 2, "string": "2"},
-     {"_id": "2", "_rev": "517381856", "integer": 3, "string": "3"}
-   ]
- }
- }}}
  
- In this case, documents with id 1 and 2 were successfully modified, while the document with
id 0 had a conflict, with both versions being saved in the database.  The application will
then need to handle any conflict resolution.
+ However, note that POSTing a single document with {{{"all_or_nothing":true}}} behaves completely
differently from a regular PUT, since it will save conflicting versions rather than rejecting
a conflict.
  
- Note that this change makes explicit the fact that CouchDB is not a relational store does
not guarantee relational consistency between documents. As a developer you need to be aware
of these semantics and design your data model and your application with this in mind.
+ {{{
+ $ DB="http://127.0.0.1:5984/tstconf"
+ $ curl -X PUT "$DB"
+ {"ok":true}
+ $ curl -X PUT -d '{"name":"fred"}' "$DB/person"
+ {"ok":true,"id":"person","rev":"1-877727288"}
+ $ curl -X POST -d '{"all_or_nothing":true,"docs":[{"_id":"person","_rev":"1-877727288","name":"jim"}]}'
"$DB/_bulk_docs"
+ [{"id":"person","rev":"2-3595405"}]
+ $ curl -X POST -d '{"all_or_nothing":true,"docs":[{"_id":"person","_rev":"1-877727288","name":"trunky"}]}'
"$DB/_bulk_docs"
+ [{"id":"person","rev":"2-2835283254"}]
+ $ curl "$DB/person?conflicts=true"
+ {"_id":"person","_rev":"2-3595405","name":"jim","_conflicts":["2-2835283254"]}
+ }}}
  
  === DELETE ===
  

Mime
View raw message