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] Trivial Update of "HTTP_Bulk_Document_API" by SebastianCohnen
Date Thu, 08 Apr 2010 17:51:45 GMT
Dear Wiki user,

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

The "HTTP_Bulk_Document_API" page has been changed by SebastianCohnen.
The comment on this change is: added toc; syntax hl; cleanup/normalisation.
http://wiki.apache.org/couchdb/HTTP_Bulk_Document_API?action=diff&rev1=7&rev2=8

--------------------------------------------------

+ = HTTP Bulk Document API =
+ <<TableOfContents()>>
+ 
- === Fetch Multiple Documents With a Single Request ===
+ == Fetch Multiple Documents With a Single Request ==
  
  {{{_all_docs}}} implements the [[HTTP_view_API]] where each ''key'' is the doc _id, and
each ''value'' is a JSON object containing the rev. This means that:
  
@@ -9, +12 @@

     * By POSTing to _all_docs you can get a set of documents with arbitrary keys
  
  {{{
- $ curl -d '{"keys":["bar","baz"]}' -X POST http://127.0.0.1:5984/foo/_all_docs?include_docs=true
+ curl -d '{"keys":["bar","baz"]}' -X POST http://127.0.0.1:5984/foo/_all_docs?include_docs=true
+ }}}
- {"total_rows":3,"offset":0,"rows":[
- {"id":"bar","key":"bar","value":{"rev":"1-4057566831"},"doc":{"_id":"bar","_rev":"1-4057566831","name":"jim"}},
- {"id":"baz","key":"baz","value":{"rev":"1-2842770487"},"doc":{"_id":"baz","_rev":"1-2842770487","name":"trunky"}}
- ]}
  
- $ curl 'http://127.0.0.1:5984/foo/_all_docs?include_docs=true&startkey="ba"&endkey="bb"'
+ {{{#!highlight javascript
  {"total_rows":3,"offset":0,"rows":[
  {"id":"bar","key":"bar","value":{"rev":"1-4057566831"},"doc":{"_id":"bar","_rev":"1-4057566831","name":"jim"}},
  {"id":"baz","key":"baz","value":{"rev":"1-2842770487"},"doc":{"_id":"baz","_rev":"1-2842770487","name":"trunky"}}
  ]}
  }}}
  
+ {{{
+ curl 'http://127.0.0.1:5984/foo/_all_docs?include_docs=true&startkey="ba"&endkey="bb"'
+ }}}
+ 
+ {{{#!highlight javascript
+ {"total_rows":3,"offset":0,"rows":[
+ {"id":"bar","key":"bar","value":{"rev":"1-4057566831"},"doc":{"_id":"bar","_rev":"1-4057566831","name":"jim"}},
+ {"id":"baz","key":"baz","value":{"rev":"1-2842770487"},"doc":{"_id":"baz","_rev":"1-2842770487","name":"trunky"}}
+ ]}
+ }}}
+ 
- === Modify Multiple Documents With a Single Request ===
+ == Modify Multiple Documents With a Single Request ==
  
  CouchDB provides a bulk insert/update feature. To use this, you make a ''POST'' request
to the URI ''/{dbname}/_bulk_docs'', with the request body being a JSON document containing
a list of new documents to be inserted or updated.
  
  For example (with curl):
  {{{
  $ DB="http://127.0.0.1:5984/mydb"
- $ curl -v -d '{"docs":[{"key":"baz","name":"bazzel"},{"key":"bar","name":"barry"}]}' -X
POST $DB/_bulk_docs
+ $ curl -d '{"docs":[{"key":"baz","name":"bazzel"},{"key":"bar","name":"barry"}]}' -X POST
$DB/_bulk_docs
- $ curl -v -d @your_file.json -X POST $DB/_bulk_docs 
+ $ curl -d @your_file.json -X POST $DB/_bulk_docs 
  }}}
  
  Doc formats below are as per CouchDB 0.9.x.
  
- {{{
+ {{{#!highlight javascript
  {
    "docs": [
      {"_id": "0", "integer": 0, "string": "0"},
@@ -49, +60 @@

  
  The response to such a bulk request would look as follows (reformatted for clarity):
  
- {{{
+ {{{#!highlight javascript
  [
      {"id":"0","rev":"1-62657917"},
      {"id":"1","rev":"1-2089673485"},
@@ -59, +70 @@

  
  Updating existing documents requires setting the ''_rev'' member to the revision being updated.
To delete a document set the ''_deleted'' member to true.
  
- {{{
+ {{{#!highlight javascript
  {
    "docs": [
      {"_id": "0", "_rev": "1-62657917", "_deleted": true},
@@ -73, +84 @@

  
  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.
  
- {{{
+ {{{#!highlight javascript
  [
      {"id":"0","error":"conflict","reason":"Document update conflict."},
      {"id":"1","rev":"2-1579510027"},
@@ -82, +93 @@

  }}}
  
  
- ==== Transactional Semantics with Bulk Updates ====
+ === 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:
  
@@ -98, +109 @@

  
     * '''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.
  
- {{{
+ {{{#!highlight javascript
  {
    "all_or_nothing": true,
    "docs": [
@@ -122, +133 @@

  {{{
  $ DB="http://127.0.0.1:5984/tstconf"
  $ curl -X PUT "$DB"
+ }}}
+ 
+ {{{#!highlight javascript
  {"ok":true}
+ }}}
+ {{{
  $ curl -X PUT -d '{"name":"fred"}' "$DB/person"
+ }}}
+ 
+ {{{#!highlight javascript
  {"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"
+ }}}
+ 
+ {{{#!highlight javascript
  [{"id":"person","rev":"2-3595405"}]
+ }}}
+ 
+ {{{
  $ curl -X POST -d '{"all_or_nothing":true,"docs":[{"_id":"person","_rev":"1-877727288","name":"trunky"}]}'
"$DB/_bulk_docs"
+ }}}
+ 
+ {{{#!highlight javascript
  [{"id":"person","rev":"2-2835283254"}]
+ }}}
+ {{{
  $ curl "$DB/person?conflicts=true"
+ }}}
+ 
+ {{{#!highlight javascript
  {"_id":"person","_rev":"2-3595405","name":"jim","_conflicts":["2-2835283254"]}
  }}}
  

Mime
View raw message