Return-Path: X-Original-To: apmail-couchdb-commits-archive@www.apache.org Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id CFDF2F3B7 for ; Tue, 1 Oct 2013 13:47:11 +0000 (UTC) Received: (qmail 83043 invoked by uid 500); 1 Oct 2013 13:46:53 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 82169 invoked by uid 500); 1 Oct 2013 13:46:40 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 80517 invoked by uid 99); 1 Oct 2013 13:46:14 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 01 Oct 2013 13:46:14 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id 188AE8AC81E; Tue, 1 Oct 2013 13:46:14 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: deathbear@apache.org To: commits@couchdb.apache.org Date: Tue, 01 Oct 2013 13:46:38 -0000 Message-Id: <72c0007941be4066850a8e492169cdc0@git.apache.org> In-Reply-To: <088b553bf2854e5f8b45d967c847f1e2@git.apache.org> References: <088b553bf2854e5f8b45d967c847f1e2@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [28/50] [abbrv] git commit: updated refs/heads/replicator-redesign to 066d69b docs: update bulk-api Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/1f10129e Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/1f10129e Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/1f10129e Branch: refs/heads/replicator-redesign Commit: 1f10129e99ffe09d2b159aedbb37ea9bbefa6ad9 Parents: 2a8af95 Author: Dave Cottlehuber Authored: Fri Sep 27 21:52:02 2013 +0200 Committer: Dave Cottlehuber Committed: Fri Sep 27 21:52:02 2013 +0200 ---------------------------------------------------------------------- share/doc/src/api/database/bulk-api.rst | 34 ++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 9 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb/blob/1f10129e/share/doc/src/api/database/bulk-api.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst index 9017227..eb49a28 100644 --- a/share/doc/src/api/database/bulk-api.rst +++ b/share/doc/src/api/database/bulk-api.rst @@ -20,9 +20,9 @@ Returns a JSON structure of all of the documents in a given database. The information is returned as a JSON structure containing meta - information about the return structure, and the list documents and basic - contents, consisting the ID, revision and key. The key is generated from - the document ID. + information about the return structure, including a list of all documents + and basic contents, consisting the ID, revision and key. The key is the + from the document's ``_id``. :param db: Database name :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` @@ -64,7 +65,8 @@ :>json number offset: Offset where the document list started :>json array rows: Array of view row objects. By default the information returned contains only the document ID and revision. - :>json number total_rows: Number of documents in the database/view + :>json number total_rows: Number of documents in the database/view. Note that + this is not the number of rows returned in the actual query. :>json number update_seq: Current update sequence for the database :code 200: Request completed successfully @@ -156,7 +158,7 @@ ] } - The return JSON is the all documents structure, but with only the + The returned JSON is the all documents structure, but with only the selected keys in the output: .. code-block:: javascript @@ -223,7 +225,10 @@ :>jsonarr string error: Error type. *Optional*. :>jsonarr string reason: Error reason. *Optional*. :code 201: Document(s) have been created or updated - :code 400: Invalid request`s JSON data + :code 400: The request provided invalid JSON data. Check that your data + is both ``utf-8`` and complies to the `JSON specification`_. Tools such as + `yajl`_ are available on all platforms that CouchDB runs on to assist with + validation and pretty printing. :code 500: Malformed data provided **Request**: @@ -273,16 +278,27 @@ } ] +.. _JSON specification: http://json.org/ +.. _yajl: http://lloyd.github.io/yajl/ + Inserting Documents in Bulk --------------------------- +Each time a document is stored or updated in CouchDB, the internal B-tree +is updated. Bulk insertion provides efficiency gains in both storage space, +and time, by consolidating many of the updates to intermediate B-tree nodes. + +It is not intended as a way to perform ``ACID``-like transactions in CouchDB, +the only transaction boundary within CouchDB is a single update to a single +database. The constraints are detailed in :ref:`api/db/bulk_docs/semantics`. + To insert documents in bulk into a database you need to supply a JSON structure with the array of documents that you want to add to the database. Using this method you can either include a document ID, or allow the document ID to be automatically generated. -For example, the following inserts three new documents, two with the +For example, the following update inserts three new documents, two with the supplied document IDs, and one which will have a document ID generated: .. code-block:: javascript