You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2015/02/20 01:26:55 UTC
[22/26] documentation commit: updated refs/heads/master to 5a81ace
src/api now follows the style
Project: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/commit/25273e7a
Tree: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/tree/25273e7a
Diff: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/diff/25273e7a
Branch: refs/heads/master
Commit: 25273e7ac2ee0c7bf427d6bb847459d02437f1e6
Parents: 71a4fc9
Author: Maria Andersson <ma...@dualpose.com>
Authored: Fri Feb 6 22:23:07 2015 +0100
Committer: Maria Andersson <ma...@dualpose.com>
Committed: Fri Feb 6 22:23:07 2015 +0100
----------------------------------------------------------------------
src/api/basics.rst | 619 ++++++------
src/api/database/bulk-api.rst | 784 ++++++++-------
src/api/database/changes.rst | 614 ++++++------
src/api/database/common.rst | 635 ++++++------
src/api/database/compact.rst | 376 +++----
src/api/database/index.rst | 15 +-
src/api/database/misc.rst | 569 ++++++-----
src/api/database/security.rst | 313 +++---
src/api/database/temp-views.rst | 122 +--
src/api/ddoc/common.rst | 267 +++--
src/api/ddoc/index.rst | 29 +-
src/api/ddoc/render.rst | 537 +++++-----
src/api/ddoc/rewrites.rst | 145 +--
src/api/ddoc/views.rst | 1199 +++++++++++------------
src/api/document/attachments.rst | 498 +++++-----
src/api/document/common.rst | 1720 ++++++++++++++++-----------------
src/api/document/index.rst | 6 +-
src/api/index.rst | 35 +-
src/api/local.rst | 49 +-
src/api/server/authn.rst | 418 ++++----
src/api/server/common.rst | 1209 ++++++++++++-----------
src/api/server/configuration.rst | 505 +++++-----
src/api/server/index.rst | 8 +-
23 files changed, 5278 insertions(+), 5394 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/basics.rst
----------------------------------------------------------------------
diff --git a/src/api/basics.rst b/src/api/basics.rst
index dfa9bfc..a7def38 100644
--- a/src/api/basics.rst
+++ b/src/api/basics.rst
@@ -16,32 +16,31 @@
API Basics
==========
-The CouchDB API is the primary method of interfacing to a CouchDB
-instance. Requests are made using HTTP and requests are used to request
-information from the database, store new data, and perform views and
-formatting of the information stored within the documents.
-
-Requests to the API can be categorised by the different areas of the
-CouchDB system that you are accessing, and the HTTP method used to send
-the request. Different methods imply different operations, for example
-retrieval of information from the database is typically handled by the
-``GET`` operation, while updates are handled by either a ``POST`` or
-``PUT`` request. There are some differences between the information that
-must be supplied for the different methods. For a guide to the basic
-HTTP methods and request structure, see :ref:`api/format`.
-
-For nearly all operations, the submitted data, and the returned data
-structure, is defined within a JavaScript Object Notation (JSON) object.
-Basic information on the content and data types for JSON are provided in
-:ref:`json`.
-
-Errors when accessing the CouchDB API are reported using standard HTTP
-Status Codes. A guide to the generic codes returned by CouchDB are
-provided in :ref:`errors`.
-
-When accessing specific areas of the CouchDB API, specific information
-and examples on the HTTP methods and request, JSON structures, and error
-codes are provided.
+The CouchDB API is the primary method of interfacing to a CouchDB instance.
+Requests are made using HTTP and requests are used to request information from
+the database, store new data, and perform views and formatting of the
+information stored within the documents.
+
+Requests to the API can be categorised by the different areas of the CouchDB
+system that you are accessing, and the HTTP method used to send the request.
+Different methods imply different operations, for example retrieval of
+information from the database is typically handled by the ``GET`` operation,
+while updates are handled by either a ``POST`` or ``PUT`` request. There are
+some differences between the information that must be supplied for the
+different methods. For a guide to the basic HTTP methods and request structure,
+see :ref:`api/format`.
+
+For nearly all operations, the submitted data, and the returned data structure,
+is defined within a JavaScript Object Notation (JSON) object. Basic information
+on the content and data types for JSON are provided in :ref:`json`.
+
+Errors when accessing the CouchDB API are reported using standard HTTP Status
+Codes. A guide to the generic codes returned by CouchDB are provided in
+:ref:`errors`.
+
+When accessing specific areas of the CouchDB API, specific information and
+examples on the HTTP methods and request, JSON structures, and error codes are
+provided.
.. _api/format:
@@ -50,43 +49,41 @@ Request Format and Responses
CouchDB supports the following HTTP request methods:
-- ``GET``
+- ``GET``
- Request the specified item. As with normal HTTP requests, the format
- of the URL defines what is returned. With CouchDB this can include
- static items, database documents, and configuration and statistical
- information. In most cases the information is returned in the form of
- a JSON document.
+ Request the specified item. As with normal HTTP requests, the format of the
+ URL defines what is returned. With CouchDB this can include static items,
+ database documents, and configuration and statistical information. In most
+ cases the information is returned in the form of a JSON document.
-- ``HEAD``
+- ``HEAD``
- The ``HEAD`` method is used to get the HTTP header of a ``GET``
- request without the body of the response.
+ The ``HEAD`` method is used to get the HTTP header of a ``GET`` request
+ without the body of the response.
-- ``POST``
+- ``POST``
- Upload data. Within CouchDB ``POST`` is used to set values, including
- uploading documents, setting document values, and starting certain
- administration commands.
+ Upload data. Within CouchDB ``POST`` is used to set values, including
+ uploading documents, setting document values, and starting certain
+ administration commands.
-- ``PUT``
+- ``PUT``
- Used to put a specified resource. In CouchDB ``PUT`` is used to
- create new objects, including databases, documents, views and design
- documents.
+ Used to put a specified resource. In CouchDB ``PUT`` is used to create new
+ objects, including databases, documents, views and design documents.
-- ``DELETE``
+- ``DELETE``
- Deletes the specified resource, including documents, views, and
- design documents.
+ Deletes the specified resource, including documents, views, and design
+ documents.
-- ``COPY``
+- ``COPY``
- A special method that can be used to copy documents and objects.
+ A special method that can be used to copy documents and objects.
-If you use an unsupported HTTP request type with an URL that does not
-support the specified type then a ``405 - Resource Not Allowed`` will be
-returned, listing the supported HTTP methods. For example:
+If you use an unsupported HTTP request type with an URL that does not support
+the specified type then a ``405 - Resource Not Allowed`` will be returned,
+listing the supported HTTP methods. For example:
.. code-block:: javascript
@@ -95,226 +92,214 @@ returned, listing the supported HTTP methods. For example:
"reason":"Only GET,HEAD allowed"
}
-
-The CouchDB design document API and the functions when returning HTML
-(for example as part of a show or list) enables you to include custom
-HTTP headers through the ``headers`` block of the return object.
+The CouchDB design document API and the functions when returning HTML (for
+example as part of a show or list) enables you to include custom HTTP headers
+through the ``headers`` block of the return object.
HTTP Headers
============
-Because CouchDB uses HTTP for all communication, you need to ensure that
-the correct HTTP headers are supplied (and processed on retrieval) so
-that you get the right format and encoding. Different environments and
-clients will be more or less strict on the effect of these HTTP headers
-(especially when not present). Where possible you should be as specific
-as possible.
+Because CouchDB uses HTTP for all communication, you need to ensure that the
+correct HTTP headers are supplied (and processed on retrieval) so that you get
+the right format and encoding. Different environments and clients will be more
+or less strict on the effect of these HTTP headers (especially when not
+present). Where possible you should be as specific as possible.
Request Headers
---------------
-- ``Accept``
-
- Specifies the list of accepted data types to be returned by the
- server (i.e. that are accepted/understandable by the client). The
- format should be a list of one or more MIME types, separated by
- colons.
+- ``Accept``
- For the majority of requests the definition should be for JSON data
- (``application/json``). For attachments you can either specify the
- MIME type explicitly, or use ``*/*`` to specify that all file types
- are supported. If the ``Accept`` header is not supplied, then the
- ``*/*`` MIME type is assumed (i.e. client accepts all formats).
+ Specifies the list of accepted data types to be returned by the server (i.e.
+ that are accepted/understandable by the client). The format should be a list
+ of one or more MIME types, separated by colons.
- The use of ``Accept`` in queries for CouchDB is not required, but is
- highly recommended as it helps to ensure that the data returned can
- be processed by the client.
+ For the majority of requests the definition should be for JSON data
+ (``application/json``). For attachments you can either specify the MIME type
+ explicitly, or use ``*/*`` to specify that all file types are supported. If
+ the ``Accept`` header is not supplied, then the ``*/*`` MIME type is assumed
+ (i.e. client accepts all formats).
- If you specify a data type using the ``Accept`` header, CouchDB will
- honor the specified type in the ``Content-type`` header field
- returned. For example, if you explicitly request ``application/json``
- in the ``Accept`` of a request, the returned HTTP headers will use
- the value in the returned ``Content-type`` field.
+ The use of ``Accept`` in queries for CouchDB is not required, but is highly
+ recommended as it helps to ensure that the data returned can be processed by
+ the client.
- For example, when sending a request without an explicit ``Accept``
- header, or when specifying ``*/*``:
+ If you specify a data type using the ``Accept`` header, CouchDB will honor
+ the specified type in the ``Content-type`` header field returned. For
+ example, if you explicitly request ``application/json`` in the ``Accept`` of
+ a request, the returned HTTP headers will use the value in the returned
+ ``Content-type`` field.
- .. code-block:: http
+ For example, when sending a request without an explicit ``Accept`` header, or
+ when specifying ``*/*``:
- GET /recipes HTTP/1.1
- Host: couchdb:5984
- Accept: */*
+ .. code-block:: http
- The returned headers are:
+ GET /recipes HTTP/1.1
+ Host: couchdb:5984
+ Accept: */*
- .. code-block:: http
+ The returned headers are:
- Server: CouchDB (Erlang/OTP)
- Date: Thu, 13 Jan 2011 13:39:34 GMT
- Content-Type: text/plain;charset=utf-8
- Content-Length: 227
- Cache-Control: must-revalidate
+ .. code-block:: http
- .. Note::
- The returned content type is ``text/plain`` even though the
- information returned by the request is in JSON format.
+ Server: CouchDB (Erlang/OTP)
+ Date: Thu, 13 Jan 2011 13:39:34 GMT
+ Content-Type: text/plain;charset=utf-8
+ Content-Length: 227
+ Cache-Control: must-revalidate
+ .. Note::
+ The returned content type is ``text/plain`` even though the information
+ returned by the request is in JSON format.
- Explicitly specifying the ``Accept`` header:
+ Explicitly specifying the ``Accept`` header:
- .. code-block:: http
+ .. code-block:: http
- GET /recipes HTTP/1.1
- Host: couchdb:5984
- Accept: application/json
+ GET /recipes HTTP/1.1
+ Host: couchdb:5984
+ Accept: application/json
- The headers returned include the ``application/json`` content type:
+ The headers returned include the ``application/json`` content type:
- .. code-block:: http
+ .. code-block:: http
- Server: CouchDB (Erlang/OTP)
- Date: Thu, 13 Jan 2013 13:40:11 GMT
- Content-Type: application/json
- Content-Length: 227
- Cache-Control: must-revalidate
+ Server: CouchDB (Erlang/OTP)
+ Date: Thu, 13 Jan 2013 13:40:11 GMT
+ Content-Type: application/json
+ Content-Length: 227
+ Cache-Control: must-revalidate
-- ``Content-type``
+- ``Content-type``
- Specifies the content type of the information being supplied within
- the request. The specification uses MIME type specifications. For the
- majority of requests this will be JSON (``application/json``). For
- some settings the MIME type will be plain text. When uploading
- attachments it should be the corresponding MIME type for the
- attachment or binary (``application/octet-stream``).
+ Specifies the content type of the information being supplied within the
+ request. The specification uses MIME type specifications. For the majority of
+ requests this will be JSON (``application/json``). For some settings the MIME
+ type will be plain text. When uploading attachments it should be the
+ corresponding MIME type for the attachment or binary
+ (``application/octet-stream``).
- The use of the ``Content-type`` on a request is highly recommended.
+ The use of the ``Content-type`` on a request is highly recommended.
Response Headers
----------------
-Response headers are returned by the server when sending back content
-and include a number of different header fields, many of which are
-standard HTTP response header and have no significance to CouchDB
-operation. The list of response headers important to CouchDB are listed
-below.
+Response headers are returned by the server when sending back content and
+include a number of different header fields, many of which are standard HTTP
+response header and have no significance to CouchDB operation. The list of
+response headers important to CouchDB are listed below.
-- ``Cache-control``
+- ``Cache-control``
- The cache control HTTP response header provides a suggestion for
- client caching mechanisms on how to treat the returned information.
- CouchDB typically returns the ``must-revalidate``, which indicates
- that the information should be revalidated if possible. This is used
- to ensure that the dynamic nature of the content is correctly
- updated.
+ The cache control HTTP response header provides a suggestion for client
+ caching mechanisms on how to treat the returned information. CouchDB
+ typically returns the ``must-revalidate``, which indicates that the
+ information should be revalidated if possible. This is used to ensure that
+ the dynamic nature of the content is correctly updated.
-- ``Content-length``
+- ``Content-length``
- The length (in bytes) of the returned content.
+ The length (in bytes) of the returned content.
-- ``Content-type``
+- ``Content-type``
- Specifies the MIME type of the returned data. For most request, the
- returned MIME type is ``text/plain``. All text is encoded in Unicode
- (UTF-8), and this is explicitly stated in the returned
- ``Content-type``, as ``text/plain;charset=utf-8``.
+ Specifies the MIME type of the returned data. For most request, the returned
+ MIME type is ``text/plain``. All text is encoded in Unicode (UTF-8), and this
+ is explicitly stated in the returned ``Content-type``, as
+ ``text/plain;charset=utf-8``.
-- ``Etag``
+- ``Etag``
- The ``Etag`` HTTP header field is used to show the revision for a
- document, or a view.
+ The ``Etag`` HTTP header field is used to show the revision for a document,
+ or a view.
- ETags have been assigned to a map/reduce group (the collection of
- views in a single design document). Any change to any of the indexes
- for those views would generate a new ETag for all view URLs in a
- single design doc, even if that specific view's results had not
- changed.
+ ETags have been assigned to a map/reduce group (the collection of views in a
+ single design document). Any change to any of the indexes for those views
+ would generate a new ETag for all view URLs in a single design doc, even if
+ that specific view's results had not changed.
- Each ``_view`` URL has its own ETag which only gets updated when
- changes are made to the database that effect that index. If the
- index for that specific view does not change, that view keeps the
- original ETag head (therefore sending back ``304 - Not Modified``
- more often).
+ Each ``_view`` URL has its own ETag which only gets updated when changes are
+ made to the database that effect that index. If the index for that specific
+ view does not change, that view keeps the original ETag head (therefore
+ sending back ``304 - Not Modified`` more often).
-- ``Transfer-Encoding``
+- ``Transfer-Encoding``
- If the response uses an encoding, then it is specified in this
- header field.
+ If the response uses an encoding, then it is specified in this header field.
- ``Transfer-Encoding: chunked`` means that the response is sent in
- parts, a method known as `chunked transfer encoding`_. This is used
- when CouchDB does not know beforehand the size of the data it will
- send (for example, the :ref:`changes feed <changes>`).
+ ``Transfer-Encoding: chunked`` means that the response is sent in parts, a
+ method known as `chunked transfer encoding`_. This is used when CouchDB does
+ not know beforehand the size of the data it will send (for example,
+ the :ref:`changes feed <changes>`).
.. _chunked transfer encoding:
- https://en.wikipedia.org/wiki/Chunked_transfer_encoding
+ https://en.wikipedia.org/wiki/Chunked_transfer_encoding
.. _json:
JSON Basics
===========
-The majority of requests and responses to CouchDB use the JavaScript
-Object Notation (JSON) for formatting the content and structure of the
-data and responses.
+The majority of requests and responses to CouchDB use the JavaScript Object
+Notation (JSON) for formatting the content and structure of the data and
+responses.
-JSON is used because it is the simplest and easiest solution for
-working with data within a web browser, as JSON structures can be
-evaluated and used as JavaScript objects within the web browser
-environment. JSON also integrates with the server-side JavaScript used
-within CouchDB.
+JSON is used because it is the simplest and easiest solution for working with
+data within a web browser, as JSON structures can be evaluated and used as
+JavaScript objects within the web browser environment. JSON also integrates
+with the server-side JavaScript used within CouchDB.
-JSON supports the same basic types as supported by JavaScript, these
-are:
+JSON supports the same basic types as supported by JavaScript, these are:
-- Array - a list of values enclosed in square brackets. For example:
+- Array - a list of values enclosed in square brackets. For example:
- .. code-block:: javascript
+ .. code-block:: javascript
- ["one", "two", "three"]
+ ["one", "two", "three"]
-- Boolean - a ``true`` or ``false`` value. You can use these strings
- directly. For example:
+- Boolean - a ``true`` or ``false`` value. You can use these strings directly.
+ For example:
- .. code-block:: javascript
+ .. code-block:: javascript
- { "value": true}
+ { "value": true}
-- Number - an integer or floating-point number.
+- Number - an integer or floating-point number.
-- Object - a set of key/value pairs (i.e. an associative array, or
- hash). The key must be a string, but the value can be any of the
- supported JSON values. For example:
+- Object - a set of key/value pairs (i.e. an associative array, or hash). The
+ key must be a string, but the value can be any of the supported JSON values.
+ For example:
- .. code-block:: javascript
+ .. code-block:: javascript
- {
+ {
"servings" : 4,
"subtitle" : "Easy to make in advance, and then cook when ready",
"cooktime" : 60,
"title" : "Chicken Coriander"
- }
+ }
- In CouchDB, the JSON object is used to represent a variety of
- structures, including the main CouchDB document.
+ In CouchDB, the JSON object is used to represent a variety of structures,
+ including the main CouchDB document.
-- String - this should be enclosed by double-quotes and supports Unicode
- characters and backslash escaping. For example:
+- String - this should be enclosed by double-quotes and supports Unicode
+ characters and backslash escaping. For example:
- .. code-block:: javascript
+ .. code-block:: javascript
- "A String"
+ "A String"
-Parsing JSON into a JavaScript object is supported through the
-``JSON.parse()`` function in JavaScript, or through various libraries that
-will perform the parsing of the content into a JavaScript object for
-you. Libraries for parsing and generating JSON are available in many
-languages, including Perl, Python, Ruby, Erlang and others.
+Parsing JSON into a JavaScript object is supported through the ``JSON.parse()``
+function in JavaScript, or through various libraries that will perform the
+parsing of the content into a JavaScript object for you. Libraries for parsing
+and generating JSON are available in many languages, including Perl, Python,
+Ruby, Erlang and others.
.. warning::
- Care should be taken to ensure that your JSON structures are
- valid, invalid structures will cause CouchDB to return an HTTP status code
- of 500 (server error).
-
+ Care should be taken to ensure that your JSON structures are valid,
+ invalid structures will cause CouchDB to return an HTTP status code of 500
+ (server error).
.. _json/numbers:
@@ -325,19 +310,19 @@ Developers and users new to computer handling of numbers often encounter
suprises when expecting that a number stored in JSON format does not
necessarily return as the same number as compared character by character.
-Any numbers defined in JSON that contain a decimal point or exponent
-will be passed through the Erlang VM's idea of the "double" data type.
-Any numbers that are used in views will pass through the view server's
-idea of a number (the common JavaScript case means even integers pass
-through a double due to JavaScript's definition of a number).
+Any numbers defined in JSON that contain a decimal point or exponent will be
+passed through the Erlang VM's idea of the "double" data type. Any numbers that
+are used in views will pass through the view server's idea of a number (the
+common JavaScript case means even integers pass through a double due to
+JavaScript's definition of a number).
Consider this document that we write to CouchDB:
.. code-block:: javascript
{
- "_id":"30b3b38cdbd9e3a587de9b8122000cff",
- "number": 1.1
+ "_id":"30b3b38cdbd9e3a587de9b8122000cff",
+ "number": 1.1
}
Now let’s read that document back from CouchDB:
@@ -345,12 +330,11 @@ Now let’s read that document back from CouchDB:
.. code-block:: javascript
{
- "_id":"30b3b38cdbd9e3a587de9b8122000cff",
- "_rev":"1-f065cee7c3fd93aa50f6c97acde93030",
- "number":1.1000000000000000888
+ "_id":"30b3b38cdbd9e3a587de9b8122000cff",
+ "_rev":"1-f065cee7c3fd93aa50f6c97acde93030",
+ "number":1.1000000000000000888
}
-
What happens is CouchDB is changing the textual representation of the
result of decoding what it was given into some numerical format. In most
cases this is an `IEEE 754`_ double precision floating point number which
@@ -358,29 +342,27 @@ is exactly what almost all other languages use as well.
.. _IEEE 754: https://en.wikipedia.org/wiki/IEEE_754-2008
-What Erlang does a bit differently than other languages is that it
-does not attempt to pretty print the resulting output to use the
-shortest number of characters. For instance, this is why we have this
-relationship:
+What Erlang does a bit differently than other languages is that it does not
+attempt to pretty print the resulting output to use the shortest number of
+characters. For instance, this is why we have this relationship:
.. code-block:: erlang
ejson:encode(ejson:decode(<<"1.1">>)).
<<"1.1000000000000000888">>
-What can be confusing here is that internally those two formats
-decode into the same IEEE-754 representation. And more importantly, it
-will decode into a fairly close representation when passed through all
-major parsers that we know about.
+What can be confusing here is that internally those two formats decode into the
+same IEEE-754 representation. And more importantly, it will decode into a
+fairly close representation when passed through all major parsers that we know
+about.
-While we've only been discussing cases where the textual
-representation changes, another important case is when an input value
-contains more precision than can actually represented in a double.
-(You could argue that this case is actually "losing" data if you don't
-accept that numbers are stored in doubles).
+While we've only been discussing cases where the textual representation
+changes, another important case is when an input value contains more precision
+than can actually represented in a double. (You could argue that this case is
+actually "losing" data if you don't accept that numbers are stored in doubles).
-Here's a log for a couple of the more common JSON libraries that happen
-to be on the author's machine:
+Here's a log for a couple of the more common JSON libraries that happen to be
+on the author's machine:
Ejson (CouchDB's current parser) at CouchDB sha 168a663b::
@@ -434,9 +416,10 @@ Ruby::
JSON.dump(JSON.load(f))
=> "[1.01234567890123]"
-.. note:: A small aside on Ruby, it requires a top level object or array, so I just
- wrapped the value. Should be obvious it doesn't affect the result of
- parsing the number though.
+.. note::
+ A small aside on Ruby, it requires a top level object or array, so I just
+ wrapped the value. Should be obvious it doesn't affect the result of
+ parsing the number though.
Spidermonkey::
@@ -449,53 +432,49 @@ Spidermonkey::
js> JSON.stringify(JSON.parse(f))
"1.0123456789012346"
-As you can see they all pretty much behave the same except for Ruby
-actually does appear to be losing some precision over the other
-libraries.
+As you can see they all pretty much behave the same except for Ruby actually
+does appear to be losing some precision over the other libraries.
-The astute observer will notice that ejson (the CouchDB JSON library)
-reported an extra three digits. While its tempting to think that this
-is due to some internal difference, its just a more specific case of
-the 1.1 input as described above.
+The astute observer will notice that ejson (the CouchDB JSON library) reported
+an extra three digits. While its tempting to think that this is due to some
+internal difference, its just a more specific case of the 1.1 input as
+described above.
-The important point to realize here is that a double can only hold a
-finite number of values. What we're doing here is generating a string
-that when passed through the "standard" floating point parsing
-algorithms (ie, ``strtod``) will result in the same bit pattern in memory
-as we started with. Or, slightly different, the bytes in a JSON
-serialized number are chosen such that they refer to a single specific
-value that a double can represent.
+The important point to realize here is that a double can only hold a finite
+number of values. What we're doing here is generating a string that when passed
+through the "standard" floating point parsing algorithms (ie, ``strtod``) will
+result in the same bit pattern in memory as we started with. Or, slightly
+different, the bytes in a JSON serialized number are chosen such that they
+refer to a single specific value that a double can represent.
-The important point to understand is that we're mapping from one
-infinite set onto a finite set. An easy way to see this is by
-reflecting on this::
+The important point to understand is that we're mapping from one infinite set
+onto a finite set. An easy way to see this is by reflecting on this::
1.0 == 1.00 == 1.000 = 1.(infinite zeroes)
-Obviously a computer can't hold infinite bytes so we have to
-decimate our infinitely sized set to a finite set that can be
-represented concisely.
+Obviously a computer can't hold infinite bytes so we have to decimate our
+infinitely sized set to a finite set that can be represented concisely.
The game that other JSON libraries are playing is merely:
-"How few characters do I have to use to select this specific value for a double"
+"How few characters do I have to use to select this specific value for a
+double"
-And that game has lots and lots of subtle details that are difficult
-to duplicate in C without a significant amount of effort (it took
-Python over a year to get it sorted with their fancy build systems
-that automatically run on a number of different architectures).
+And that game has lots and lots of subtle details that are difficult to
+duplicate in C without a significant amount of effort (it took Python over a
+year to get it sorted with their fancy build systems that automatically run on
+a number of different architectures).
-Hopefully we've shown that CouchDB is not doing anything "funky" by
-changing input. Its behaving the same as any other common JSON library
-does, its just not pretty printing its output.
+Hopefully we've shown that CouchDB is not doing anything "funky" by changing
+input. Its behaving the same as any other common JSON library does, its just
+not pretty printing its output.
-On the other hand, if you actually are in a position where an IEEE-754
-double is not a satisfactory datatype for your numbers, then the
-answer as has been stated is to not pass your numbers through this
-representation. In JSON this is accomplished by encoding them as a
-string or by using integer types (although integer types can still
-bite you if you use a platform that has a different integer
-representation than normal, ie, JavaScript).
+On the other hand, if you actually are in a position where an IEEE-754 double
+is not a satisfactory datatype for your numbers, then the answer as has been
+stated is to not pass your numbers through this representation. In JSON this is
+accomplished by encoding them as a string or by using integer types (although
+integer types can still bite you if you use a platform that has a different
+integer representation than normal, ie, JavaScript).
Further information can be found easily, including the
`Floating Point Guide`_, and `David Goldberg's Reference`_.
@@ -503,12 +482,11 @@ Further information can be found easily, including the
.. _Floating Point Guide: http://floating-point-gui.de/
.. _David Goldberg's Reference: http://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html
-Also, if anyone is really interested in changing this behavior, we're
-all ears for contributions to `jiffy`_ (which is theoretically going to
-replace ejson when we get around to updating the build system). The
-places we've looked for inspiration are TCL and Python. If you know a
-decent implementation of this float printing algorithm give us a
-holler.
+Also, if anyone is really interested in changing this behavior, we're all ears
+for contributions to `jiffy`_ (which is theoretically going to replace ejson
+when we get around to updating the build system). The places we've looked for
+inspiration are TCL and Python. If you know a decent implementation of this
+float printing algorithm give us a holler.
.. _jiffy: https://github.com/davisp/jiffy
@@ -517,96 +495,91 @@ holler.
HTTP Status Codes
=================
-With the interface to CouchDB working through HTTP, error codes and
-statuses are reported using a combination of the HTTP status code
-number, and corresponding data in the body of the response data.
+With the interface to CouchDB working through HTTP, error codes and statuses
+are reported using a combination of the HTTP status code number, and
+corresponding data in the body of the response data.
-A list of the error codes returned by CouchDB, and generic descriptions
-of the related errors are provided below. The meaning of different
-status codes for specific request types are provided in the
-corresponding API call reference.
+A list of the error codes returned by CouchDB, and generic descriptions of the
+related errors are provided below. The meaning of different status codes for
+specific request types are provided in the corresponding API call reference.
-- ``200 - OK``
+- ``200 - OK``
- Request completed successfully.
+ Request completed successfully.
-- ``201 - Created``
+- ``201 - Created``
- Document created successfully.
+ Document created successfully.
-- ``202 - Accepted``
+- ``202 - Accepted``
- Request has been accepted, but the corresponding operation may not
- have completed. This is used for background operations, such as
- database compaction.
+ Request has been accepted, but the corresponding operation may not have
+ completed. This is used for background operations, such as database
+ compaction.
-- ``304 - Not Modified``
+- ``304 - Not Modified``
- The additional content requested has not been modified. This is used
- with the ETag system to identify the version of information returned.
+ The additional content requested has not been modified. This is used with the
+ ETag system to identify the version of information returned.
-- ``400 - Bad Request``
+- ``400 - Bad Request``
- Bad request structure. The error can indicate an error with the
- request URL, path or headers. Differences in the supplied MD5 hash
- and content also trigger this error, as this may indicate message
- corruption.
+ Bad request structure. The error can indicate an error with the request URL,
+ path or headers. Differences in the supplied MD5 hash and content also
+ trigger this error, as this may indicate message corruption.
-- ``401 - Unauthorized``
+- ``401 - Unauthorized``
- The item requested was not available using the supplied
- authorization, or authorization was not supplied.
+ The item requested was not available using the supplied authorization, or
+ authorization was not supplied.
-- ``403 - Forbidden``
+- ``403 - Forbidden``
- The requested item or operation is forbidden.
+ The requested item or operation is forbidden.
-- ``404 - Not Found``
+- ``404 - Not Found``
- The requested content could not be found. The content will include
- further information, as a JSON object, if available. The structure
- will contain two keys, ``error`` and ``reason``. For example:
+ The requested content could not be found. The content will include further
+ information, as a JSON object, if available. The structure will contain two
+ keys, ``error`` and ``reason``. For example:
- .. code-block:: javascript
+ .. code-block:: javascript
- {"error":"not_found","reason":"no_db_file"}
+ {"error":"not_found","reason":"no_db_file"}
-- ``405 - Resource Not Allowed``
+- ``405 - Resource Not Allowed``
- A request was made using an invalid HTTP request type for the URL
- requested. For example, you have requested a ``PUT`` when a ``POST``
- is required. Errors of this type can also triggered by invalid URL
- strings.
+ A request was made using an invalid HTTP request type for the URL requested.
+ For example, you have requested a ``PUT`` when a ``POST`` is required. Errors
+ of this type can also triggered by invalid URL strings.
-- ``406 - Not Acceptable``
+- ``406 - Not Acceptable``
- The requested content type is not supported by the server.
+ The requested content type is not supported by the server.
-- ``409 - Conflict``
+- ``409 - Conflict``
- Request resulted in an update conflict.
+ Request resulted in an update conflict.
-- ``412 - Precondition Failed``
+- ``412 - Precondition Failed``
- The request headers from the client and the capabilities of the
- server do not match.
+ The request headers from the client and the capabilities of the server do not
+ match.
-- ``415 - Bad Content Type``
+- ``415 - Bad Content Type``
- The content types supported, and the content type of the information
- being requested or submitted indicate that the content type is not
- supported.
+ The content types supported, and the content type of the information being
+ requested or submitted indicate that the content type is not supported.
-- ``416 - Requested Range Not Satisfiable``
+- ``416 - Requested Range Not Satisfiable``
- The range specified in the request header cannot be satisfied by the
- server.
+ The range specified in the request header cannot be satisfied by the server.
-- ``417 - Expectation Failed``
+- ``417 - Expectation Failed``
- When sending documents in bulk, the bulk load operation failed.
+ When sending documents in bulk, the bulk load operation failed.
-- ``500 - Internal Server Error``
+- ``500 - Internal Server Error``
- The request was invalid, either because the supplied JSON was
- invalid, or invalid information was supplied as part of the request.
+ The request was invalid, either because the supplied JSON was invalid, or
+ invalid information was supplied as part of the request.
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/src/api/database/bulk-api.rst b/src/api/database/bulk-api.rst
index d13ff30..22a6197 100644
--- a/src/api/database/bulk-api.rst
+++ b/src/api/database/bulk-api.rst
@@ -10,280 +10,278 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/db/all_docs:
+=================
``/db/_all_docs``
=================
.. http:get:: /{db}/_all_docs
- :synopsis: Returns a built-in view of all documents in this database
-
- 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, 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 Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :query boolean conflicts: Includes `conflicts` information in response.
- Ignored if `include_docs` isn't ``true``. Default is ``false``.
- :query boolean descending: Return the documents in descending by key order.
- Default is ``false``.
- :query string endkey: Stop returning records when the specified key is
- reached. *Optional*.
- :query string end_key: Alias for `endkey` param.
- :query string endkey_docid: Stop returning records when the specified
- document ID is reached. *Optional*.
- :query string end_key_doc_id: Alias for `endkey_docid` param.
- :query boolean include_docs: Include the full content of the documents in
- the return. Default is ``false``.
- :query boolean inclusive_end: Specifies whether the specified end key should
- be included in the result. Default is ``true``.
- :query string key: Return only documents that match the specified key.
- *Optional*.
- :query number limit: Limit the number of the returned documents to the
- specified number. *Optional*.
- :query number skip: Skip this number of records before starting to return
- the results. Default is ``0``.
- :query string stale: Allow the results from a stale view to be used, without
- triggering a rebuild of all views within the encompassing design doc.
- Supported values: ``ok`` and ``update_after``. *Optional*.
- :query string startkey: Return records starting with the specified key.
- *Optional*.
- :query string start_key: Alias for `startkey` param.
- :query string startkey_docid: Return records starting with the specified
- document ID. *Optional*.
- :query string start_key_doc_id: Alias for `startkey_docid` param.
- :query boolean update_seq: Response includes an ``update_seq`` value
- indicating which sequence id of the underlying database the view reflects.
- Default is ``false``.
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>header ETag: Response signature
- :>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. 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
-
- **Request**:
-
- .. code-block:: http
-
- GET /db/_all_docs HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ :synopsis: Returns a built-in view of all documents in this database
+
+ 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, 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 Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :query boolean conflicts: Includes `conflicts` information in response.
+ Ignored if `include_docs` isn't ``true``. Default is ``false``.
+ :query boolean descending: Return the documents in descending by key order.
+ Default is ``false``.
+ :query string endkey: Stop returning records when the specified key is
+ reached. *Optional*.
+ :query string end_key: Alias for `endkey` param.
+ :query string endkey_docid: Stop returning records when the specified
+ document ID is reached. *Optional*.
+ :query string end_key_doc_id: Alias for `endkey_docid` param.
+ :query boolean include_docs: Include the full content of the documents in
+ the return. Default is ``false``.
+ :query boolean inclusive_end: Specifies whether the specified end key
+ should be included in the result. Default is ``true``.
+ :query string key: Return only documents that match the specified key.
+ *Optional*.
+ :query number limit: Limit the number of the returned documents to the
+ specified number. *Optional*.
+ :query number skip: Skip this number of records before starting to return
+ the results. Default is ``0``.
+ :query string stale: Allow the results from a stale view to be used,
+ without triggering a rebuild of all views within the encompassing design
+ doc. Supported values: ``ok`` and ``update_after``. *Optional*.
+ :query string startkey: Return records starting with the specified key.
+ *Optional*.
+ :query string start_key: Alias for `startkey` param.
+ :query string startkey_docid: Return records starting with the specified
+ document ID. *Optional*.
+ :query string start_key_doc_id: Alias for `startkey_docid` param.
+ :query boolean update_seq: Response includes an ``update_seq`` value
+ indicating which sequence id of the underlying database the view
+ reflects. Default is ``false``.
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Response signature
+ :>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. 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
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /db/_all_docs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Sat, 10 Aug 2013 16:22:56 GMT
+ ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
+ Server: CouchDB (Erlang/OTP)
+ Transfer-Encoding: chunked
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 16:22:56 GMT
- ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
- Server: CouchDB (Erlang/OTP)
- Transfer-Encoding: chunked
-
- {
- "offset": 0,
- "rows": [
- {
- "id": "16e458537602f5ef2a710089dffd9453",
- "key": "16e458537602f5ef2a710089dffd9453",
- "value": {
- "rev": "1-967a00dff5e02add41819138abb3284d"
- }
- },
- {
- "id": "a4c51cdfa2069f3e905c431114001aff",
- "key": "a4c51cdfa2069f3e905c431114001aff",
- "value": {
- "rev": "1-967a00dff5e02add41819138abb3284d"
- }
- },
- {
- "id": "a4c51cdfa2069f3e905c4311140034aa",
- "key": "a4c51cdfa2069f3e905c4311140034aa",
- "value": {
- "rev": "5-6182c9c954200ab5e3c6bd5e76a1549f"
- }
- },
- {
- "id": "a4c51cdfa2069f3e905c431114003597",
- "key": "a4c51cdfa2069f3e905c431114003597",
- "value": {
- "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
- }
- },
- {
- "id": "f4ca7773ddea715afebc4b4b15d4f0b3",
- "key": "f4ca7773ddea715afebc4b4b15d4f0b3",
- "value": {
- "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
+ {
+ "offset": 0,
+ "rows": [
+ {
+ "id": "16e458537602f5ef2a710089dffd9453",
+ "key": "16e458537602f5ef2a710089dffd9453",
+ "value": {
+ "rev": "1-967a00dff5e02add41819138abb3284d"
+ }
+ },
+ {
+ "id": "a4c51cdfa2069f3e905c431114001aff",
+ "key": "a4c51cdfa2069f3e905c431114001aff",
+ "value": {
+ "rev": "1-967a00dff5e02add41819138abb3284d"
+ }
+ },
+ {
+ "id": "a4c51cdfa2069f3e905c4311140034aa",
+ "key": "a4c51cdfa2069f3e905c4311140034aa",
+ "value": {
+ "rev": "5-6182c9c954200ab5e3c6bd5e76a1549f"
+ }
+ },
+ {
+ "id": "a4c51cdfa2069f3e905c431114003597",
+ "key": "a4c51cdfa2069f3e905c431114003597",
+ "value": {
+ "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
+ }
+ },
+ {
+ "id": "f4ca7773ddea715afebc4b4b15d4f0b3",
+ "key": "f4ca7773ddea715afebc4b4b15d4f0b3",
+ "value": {
+ "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
+ }
}
- }
- ],
- "total_rows": 5
- }
-
+ ],
+ "total_rows": 5
+ }
.. http:post:: /{db}/_all_docs
- :synopsis: Returns certain rows from the built-in view of all documents
+ :synopsis: Returns certain rows from the built-in view of all documents
- The ``POST`` to ``_all_docs`` allows to specify multiple keys to be
- selected from the database. This enables you to request multiple
- documents in a single request, in place of multiple :get:`/{db}/{docid}`
- requests.
+ The ``POST`` to ``_all_docs`` allows to specify multiple keys to be
+ selected from the database. This enables you to request multiple
+ documents in a single request, in place of multiple :get:`/{db}/{docid}`
+ requests.
- The request body should contain a list of the keys to be returned as an
- array to a ``keys`` object. For example:
+ The request body should contain a list of the keys to be returned as an
+ array to a ``keys`` object. For example:
- .. code-block:: http
+ .. code-block:: http
- POST /db/_all_docs HTTP/1.1
- Accept: application/json
- Content-Length: 70
- Content-Type: application/json
- Host: localhost:5984
+ POST /db/_all_docs HTTP/1.1
+ Accept: application/json
+ Content-Length: 70
+ Content-Type: application/json
+ Host: localhost:5984
- {
- "keys" : [
- "Zingylemontart",
- "Yogurtraita"
- ]
- }
-
- The returned JSON is the all documents structure, but with only the
- selected keys in the output:
+ {
+ "keys" : [
+ "Zingylemontart",
+ "Yogurtraita"
+ ]
+ }
- .. code-block:: javascript
+ The returned JSON is the all documents structure, but with only the
+ selected keys in the output:
- {
- "total_rows" : 2666,
- "rows" : [
- {
- "value" : {
- "rev" : "1-a3544d296de19e6f5b932ea77d886942"
- },
- "id" : "Zingylemontart",
- "key" : "Zingylemontart"
- },
- {
- "value" : {
- "rev" : "1-91635098bfe7d40197a1b98d7ee085fc"
- },
- "id" : "Yogurtraita",
- "key" : "Yogurtraita"
- }
- ],
- "offset" : 0
- }
+ .. code-block:: javascript
+ {
+ "total_rows" : 2666,
+ "rows" : [
+ {
+ "value" : {
+ "rev" : "1-a3544d296de19e6f5b932ea77d886942"
+ },
+ "id" : "Zingylemontart",
+ "key" : "Zingylemontart"
+ },
+ {
+ "value" : {
+ "rev" : "1-91635098bfe7d40197a1b98d7ee085fc"
+ },
+ "id" : "Yogurtraita",
+ "key" : "Yogurtraita"
+ }
+ ],
+ "offset" : 0
+ }
.. _api/db/bulk_docs:
+==================
``/db/_bulk_docs``
==================
.. http:post:: /{db}/_bulk_docs
- :synopsis: Inserts or updates multiple documents in to the database in a single request
-
- The bulk document API allows you to create and update multiple documents
- at the same time within a single request. The basic operation is similar
- to creating or updating a single document, except that you batch the
- document structure and information.
-
- When creating new documents the document ID (``_id``) is optional.
-
- For updating existing documents, you must provide the document ID, revision
- information (``_rev``), and new document values.
-
- In case of batch deleting documents all fields as document ID, revision
- information and deletion status (``_deleted``) are required.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :<header X-Couch-Full-Commit: Overrides server's
- :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
- are: ``false`` and ``true``. *Optional*
- :<json boolean all_or_nothing: Sets the database commit mode to use
- :ref:`all-or-nothing <api/db/bulk_docs/semantics>` semantics.
- Default is ``false``. *Optional*
- :<json array docs: List of documents objects
- :<json boolean new_edits: If ``false``, prevents the database from assigning
- them new revision IDs. Default is ``true``. *Optional*
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>jsonarr string id: Document ID
- :>jsonarr string rev: New document revision token. Available
- if document have saved without errors. *Optional*
- :>jsonarr string error: Error type. *Optional*
- :>jsonarr string reason: Error reason. *Optional*
- :code 201: Document(s) have been created or updated
- :code 400: The request provided invalid JSON data
- :code 417: Occurs when ``all_or_nothing`` option set as ``true`` and
- at least one document was rejected by :ref:`validation function <vdufun>`
- :code 500: Malformed data provided, while it's still valid JSON
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_bulk_docs HTTP/1.1
- Accept: application/json
- Content-Length: 109
- Content-Type:application/json
- Host: localhost:5984
+ :synopsis: Inserts or updates multiple documents in to the database in a single request
+
+ The bulk document API allows you to create and update multiple documents
+ at the same time within a single request. The basic operation is similar
+ to creating or updating a single document, except that you batch the
+ document structure and information.
+
+ When creating new documents the document ID (``_id``) is optional.
+
+ For updating existing documents, you must provide the document ID, revision
+ information (``_rev``), and new document values.
+
+ In case of batch deleting documents all fields as document ID, revision
+ information and deletion status (``_deleted``) are required.
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :<header X-Couch-Full-Commit: Overrides server's
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
+ are: ``false`` and ``true``. *Optional*
+ :<json boolean all_or_nothing: Sets the database commit mode to use
+ :ref:`all-or-nothing <api/db/bulk_docs/semantics>` semantics.
+ Default is ``false``. *Optional*
+ :<json array docs: List of documents objects
+ :<json boolean new_edits: If ``false``, prevents the database from
+ assigning them new revision IDs. Default is ``true``. *Optional*
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>jsonarr string id: Document ID
+ :>jsonarr string rev: New document revision token. Available
+ if document have saved without errors. *Optional*
+ :>jsonarr string error: Error type. *Optional*
+ :>jsonarr string reason: Error reason. *Optional*
+ :code 201: Document(s) have been created or updated
+ :code 400: The request provided invalid JSON data
+ :code 417: Occurs when ``all_or_nothing`` option set as ``true`` and
+ at least one document was rejected by :ref:`validation function <vdufun>`
+ :code 500: Malformed data provided, while it's still valid JSON
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db/_bulk_docs HTTP/1.1
+ Accept: application/json
+ Content-Length: 109
+ Content-Type:application/json
+ Host: localhost:5984
- {
- "docs": [
- {
- "_id": "FishStew"
- },
{
- "_id": "LambStew",
- "_rev": "2-0786321986194c92dd3b57dfbfc741ce",
- "_deleted": true
+ "docs": [
+ {
+ "_id": "FishStew"
+ },
+ {
+ "_id": "LambStew",
+ "_rev": "2-0786321986194c92dd3b57dfbfc741ce",
+ "_deleted": true
+ }
+ ]
}
- ]
- }
- **Response**:
+ **Response**:
- .. code-block:: http
+ .. code-block:: http
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 144
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 00:15:05 GMT
- Server: CouchDB (Erlang/OTP)
-
- [
- {
- "ok": true,
- "id": "FishStew",
- "rev":" 1-967a00dff5e02add41819138abb3284d"
- },
- {
- "ok": true,
- "id": "LambStew",
- "rev": "3-f9c62b2169d0999103e9f41949090807"
- }
- ]
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 144
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 00:15:05 GMT
+ Server: CouchDB (Erlang/OTP)
+ [
+ {
+ "ok": true,
+ "id": "FishStew",
+ "rev":" 1-967a00dff5e02add41819138abb3284d"
+ },
+ {
+ "ok": true,
+ "id": "LambStew",
+ "rev": "3-f9c62b2169d0999103e9f41949090807"
+ }
+ ]
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,
@@ -303,35 +301,34 @@ supplied document IDs, and one which will have a document ID generated:
.. code-block:: http
- POST /source/_bulk_docs HTTP/1.1
- Accept: application/json
- Content-Length: 323
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "docs": [
- {
- "_id": "FishStew",
- "servings": 4,
- "subtitle": "Delicious with freshly baked bread",
- "title": "FishStew"
- },
- {
- "_id": "LambStew",
- "servings": 6,
- "subtitle": "Serve with a whole meal scone topping",
- "title": "LambStew"
- },
- {
- "_id": "BeefStew",
- "servings": 8,
- "subtitle": "Hand-made dumplings make a great accompaniment",
- "title": "BeefStew"
- }
- ]
- }
+ POST /source/_bulk_docs HTTP/1.1
+ Accept: application/json
+ Content-Length: 323
+ Content-Type: application/json
+ Host: localhost:5984
+ {
+ "docs": [
+ {
+ "_id": "FishStew",
+ "servings": 4,
+ "subtitle": "Delicious with freshly baked bread",
+ "title": "FishStew"
+ },
+ {
+ "_id": "LambStew",
+ "servings": 6,
+ "subtitle": "Serve with a whole meal scone topping",
+ "title": "LambStew"
+ },
+ {
+ "_id": "BeefStew",
+ "servings": 8,
+ "subtitle": "Hand-made dumplings make a great accompaniment",
+ "title": "BeefStew"
+ }
+ ]
+ }
The return type from a bulk insertion will be :statuscode:`201`,
with the content of the returned structure indicating specific success
@@ -342,39 +339,38 @@ documents created, here with the combination and their revision IDs:
.. code-block:: http
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 215
- Content-Type: application/json
- Date: Sat, 26 Oct 2013 00:10:39 GMT
- Server: CouchDB (Erlang OTP)
-
- [
- {
- "id": "FishStew",
- "ok": true,
- "rev": "1-6a466d5dfda05e613ba97bd737829d67"
- },
- {
- "id": "LambStew",
- "ok": true,
- "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
- },
- {
- "id": "BeefStew",
- "ok": true,
- "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
- }
- ]
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 215
+ Content-Type: application/json
+ Date: Sat, 26 Oct 2013 00:10:39 GMT
+ Server: CouchDB (Erlang OTP)
+ [
+ {
+ "id": "FishStew",
+ "ok": true,
+ "rev": "1-6a466d5dfda05e613ba97bd737829d67"
+ },
+ {
+ "id": "LambStew",
+ "ok": true,
+ "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
+ },
+ {
+ "id": "BeefStew",
+ "ok": true,
+ "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
+ }
+ ]
The content and structure of the returned JSON will depend on the transaction
semantics being used for the bulk update; see :ref:`api/db/bulk_docs/semantics`
-for more information. Conflicts and validation errors when updating documents in
-bulk must be handled separately; see :ref:`api/db/bulk_docs/validation`.
+for more information. Conflicts and validation errors when updating documents
+in bulk must be handled separately; see :ref:`api/db/bulk_docs/validation`.
Updating Documents in Bulk
---------------------------
+==========================
The bulk document update procedure is similar to the insertion
procedure, except that you must specify the document ID and current
@@ -384,68 +380,67 @@ For example, you could send the following request:
.. code-block:: http
- POST /recipes/_bulk_docs HTTP/1.1
- Accept: application/json
- Content-Length: 464
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "docs": [
- {
- "_id": "FishStew",
- "_rev": "1-6a466d5dfda05e613ba97bd737829d67",
- "servings": 4,
- "subtitle": "Delicious with freshly baked bread",
- "title": "FishStew"
- },
- {
- "_id": "LambStew",
- "_rev": "1-648f1b989d52b8e43f05aa877092cc7c",
- "servings": 6,
- "subtitle": "Serve with a whole meal scone topping",
- "title": "LambStew"
- },
- {
- "_id": "BeefStew",
- "_rev": "1-e4602845fc4c99674f50b1d5a804fdfa",
- "servings": 8,
- "subtitle": "Hand-made dumplings make a great accompaniment",
- "title": "BeefStew"
- }
- ]
- }
+ POST /recipes/_bulk_docs HTTP/1.1
+ Accept: application/json
+ Content-Length: 464
+ Content-Type: application/json
+ Host: localhost:5984
+
+ {
+ "docs": [
+ {
+ "_id": "FishStew",
+ "_rev": "1-6a466d5dfda05e613ba97bd737829d67",
+ "servings": 4,
+ "subtitle": "Delicious with freshly baked bread",
+ "title": "FishStew"
+ },
+ {
+ "_id": "LambStew",
+ "_rev": "1-648f1b989d52b8e43f05aa877092cc7c",
+ "servings": 6,
+ "subtitle": "Serve with a whole meal scone topping",
+ "title": "LambStew"
+ },
+ {
+ "_id": "BeefStew",
+ "_rev": "1-e4602845fc4c99674f50b1d5a804fdfa",
+ "servings": 8,
+ "subtitle": "Hand-made dumplings make a great accompaniment",
+ "title": "BeefStew"
+ }
+ ]
+ }
The return structure is the JSON of the updated documents, with the new
revision and ID information:
.. code-block:: http
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 215
- Content-Type: application/json
- Date: Sat, 26 Oct 2013 00:10:39 GMT
- Server: CouchDB (Erlang OTP)
-
- [
- {
- "id": "FishStew",
- "ok": true,
- "rev": "2-2bff94179917f1dec7cd7f0209066fb8"
- },
- {
- "id": "LambStew",
- "ok": true,
- "rev": "2-6a7aae7ac481aa98a2042718d09843c4"
- },
- {
- "id": "BeefStew",
- "ok": true,
- "rev": "2-9801936a42f06a16f16c30027980d96f"
- }
- ]
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 215
+ Content-Type: application/json
+ Date: Sat, 26 Oct 2013 00:10:39 GMT
+ Server: CouchDB (Erlang OTP)
+ [
+ {
+ "id": "FishStew",
+ "ok": true,
+ "rev": "2-2bff94179917f1dec7cd7f0209066fb8"
+ },
+ {
+ "id": "LambStew",
+ "ok": true,
+ "rev": "2-6a7aae7ac481aa98a2042718d09843c4"
+ },
+ {
+ "id": "BeefStew",
+ "ok": true,
+ "rev": "2-9801936a42f06a16f16c30027980d96f"
+ }
+ ]
You can optionally delete documents during a bulk update by adding the
``_deleted`` field with a value of ``true`` to each document ID/revision
@@ -457,13 +452,13 @@ messages on a per-document basis.
The content and structure of the returned JSON will depend on the transaction
semantics being used for the bulk update; see :ref:`api/db/bulk_docs/semantics`
-for more information. Conflicts and validation errors when updating documents in
-bulk must be handled separately; see :ref:`api/db/bulk_docs/validation`.
+for more information. Conflicts and validation errors when updating documents
+in bulk must be handled separately; see :ref:`api/db/bulk_docs/validation`.
.. _api/db/bulk_docs/semantics:
Bulk Documents Transaction Semantics
-------------------------------------
+====================================
CouchDB supports two different modes for updating (or inserting)
documents using the bulk documentation system. Each mode affects both
@@ -487,24 +482,23 @@ of conflict checking performed on each document. The two modes are:
.. code-block:: javascript
[
- {
- "id" : "FishStew",
- "error" : "conflict",
- "reason" : "Document update conflict."
- },
- {
- "id" : "LambStew",
- "error" : "conflict",
- "reason" : "Document update conflict."
- },
- {
- "id" : "BeefStew",
- "error" : "conflict",
- "reason" : "Document update conflict."
- }
+ {
+ "id" : "FishStew",
+ "error" : "conflict",
+ "reason" : "Document update conflict."
+ },
+ {
+ "id" : "LambStew",
+ "error" : "conflict",
+ "reason" : "Document update conflict."
+ },
+ {
+ "id" : "BeefStew",
+ "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.
@@ -523,30 +517,30 @@ of conflict checking performed on each document. The two modes are:
.. code-block:: http
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 215
- Content-Type: application/json
- Date: Sat, 26 Oct 2013 00:13:33 GMT
- Server: CouchDB (Erlang OTP)
-
- [
- {
- "id": "FishStew",
- "ok": true,
- "rev": "1-6a466d5dfda05e613ba97bd737829d67"
- },
- {
- "id": "LambStew",
- "ok": true,
- "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
- },
- {
- "id": "BeefStew",
- "ok": true,
- "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
- }
- ]
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 215
+ Content-Type: application/json
+ Date: Sat, 26 Oct 2013 00:13:33 GMT
+ Server: CouchDB (Erlang OTP)
+
+ [
+ {
+ "id": "FishStew",
+ "ok": true,
+ "rev": "1-6a466d5dfda05e613ba97bd737829d67"
+ },
+ {
+ "id": "LambStew",
+ "ok": true,
+ "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
+ },
+ {
+ "id": "BeefStew",
+ "ok": true,
+ "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
+ }
+ ]
When updating documents using this mode the revision of a document
included in views will be arbitrary. You can check the conflict
@@ -590,7 +584,7 @@ other databases correctly.
.. _api/db/bulk_docs/validation:
Bulk Document Validation and Conflict Errors
---------------------------------------------
+============================================
The JSON returned by the ``_bulk_docs`` operation consists of an array
of JSON structures, one for each document in the original submission.
@@ -625,7 +619,7 @@ following type:
.. code-block:: javascript
- throw({forbidden: 'invalid recipe ingredient'});
+ throw({forbidden: 'invalid recipe ingredient'});
The error response returned will be: