couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kxe...@apache.org
Subject [28/50] [abbrv] Split API articles into small files focused on specific problem.
Date Wed, 24 Jul 2013 12:25:05 GMT
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d67c2733/share/doc/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
new file mode 100644
index 0000000..abc9e05
--- /dev/null
+++ b/share/doc/src/api/ddoc/views.rst
@@ -0,0 +1,708 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+
+.. _api/ddoc/view:
+.. _api/ddoc/view.get:
+
+``GET /db/_design/design-doc/_view/view-name``
+==============================================
+
+* **Method**: ``GET /db/_design/design-doc/_view/view-name``
+* **Request**: None
+* **Response**: JSON of the documents returned by the view
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+  * **Argument**: descending
+
+    * **Description**:  Return the documents in descending by key order
+    * **Optional**: yes
+    * **Type**: boolean
+    * **Default**: false
+
+  * **Argument**: endkey
+
+    * **Description**:  Stop returning records when the specified key is reached
+    * **Optional**: yes
+    * **Type**: string
+
+  * **Argument**: endkey_docid
+
+    * **Description**:  Stop returning records when the specified document
+      ID is reached
+    * **Optional**: yes
+    * **Type**: string
+
+  * **Argument**: group
+
+    * **Description**:  Group the results using the reduce function to a
+      group or single row
+    * **Optional**: yes
+    * **Type**: boolean
+    * **Default**: false
+
+  * **Argument**: group_level
+
+    * **Description**:  Specify the group level to be used
+    * **Optional**: yes
+    * **Type**: numeric
+
+  * **Argument**: include_docs
+
+    * **Description**:  Include the full content of the documents in the return
+    * **Optional**: yes
+    * **Type**: boolean
+    * **Default**: false
+
+  * **Argument**: inclusive_end
+
+    * **Description**:  Specifies whether the specified end key should be
+      included in the result
+    * **Optional**: yes
+    * **Type**: boolean
+    * **Default**: true
+
+  * **Argument**: key
+
+    * **Description**:  Return only documents that match the specified key
+    * **Optional**: yes
+    * **Type**: string
+
+  * **Argument**: limit
+
+    * **Description**:  Limit the number of the returned documents to the
+      specified number
+    * **Optional**: yes
+    * **Type**: numeric
+
+  * **Argument**: reduce
+
+    * **Description**:  Use the reduction function
+    * **Optional**: yes
+    * **Type**: boolean
+    * **Default**: true
+
+  * **Argument**: skip
+
+    * **Description**:  Skip this number of records before starting to return
+      the results
+    * **Optional**: yes
+    * **Type**: numeric
+    * **Default**: 0
+
+  * **Argument**: stale
+
+    * **Description**:  Allow the results from a stale view to be used
+    * **Optional**: yes
+    * **Type**: string
+    * **Default**:
+    * **Supported Values**
+
+      * **ok**: Allow stale views
+
+  * **Argument**: startkey
+
+    * **Description**:  Return records starting with the specified key
+    * **Optional**: yes
+    * **Type**: string
+
+  * **Argument**: startkey_docid
+
+    * **Description**:  Return records starting with the specified document ID
+    * **Optional**: yes
+    * **Type**: string
+
+  * **Argument**: update_seq
+
+    * **Description**:  Include the update sequence in the generated results
+    * **Optional**: yes
+    * **Type**: boolean
+    * **Default**: false
+
+Executes the specified ``view-name`` from the specified ``design-doc``
+design document.
+
+Querying Views and Indexes
+--------------------------
+
+The definition of a view within a design document also creates an index
+based on the key information defined within each view. The production
+and use of the index significantly increases the speed of access and
+searching or selecting documents from the view.
+
+However, the index is not updated when new documents are added or
+modified in the database. Instead, the index is generated or updated,
+either when the view is first accessed, or when the view is accessed
+after a document has been updated. In each case, the index is updated
+before the view query is executed against the database.
+
+View indexes are updated incrementally in the following situations:
+
+-  A new document has been added to the database.
+
+-  A document has been deleted from the database.
+
+-  A document in the database has been updated.
+
+View indexes are rebuilt entirely when the view definition changes. To
+achieve this, a 'fingerprint' of the view definition is created when the
+design document is updated. If the fingerprint changes, then the view
+indexes are entirely rebuilt. This ensures that changes to the view
+definitions are reflected in the view indexes.
+
+.. note::
+   View index rebuilds occur when one view from the same the view group
+   (i.e. all the views defined within a single a design document) has
+   been determined as needing a rebuild. For example, if if you have a
+   design document with different views, and you update the database,
+   all three view indexes within the design document will be updated.
+
+Because the view is updated when it has been queried, it can result in a
+delay in returned information when the view is accessed, especially if
+there are a large number of documents in the database and the view index
+does not exist. There are a number of ways to mitigate, but not
+completely eliminate, these issues. These include:
+
+-  Create the view definition (and associated design documents) on your
+   database before allowing insertion or updates to the documents. If
+   this is allowed while the view is being accessed, the index can be
+   updated incrementally.
+
+-  Manually force a view request from the database. You can do this
+   either before users are allowed to use the view, or you can access
+   the view manually after documents are added or updated.
+
+-  Use the ``/db/_changes`` method to monitor for changes to the
+   database and then access the view to force the corresponding view
+   index to be updated. See :ref:`api/db/changes` for more information.
+
+-  Use a monitor with the ``update_notification`` section of the CouchDB
+   configuration file to monitor for changes to your database, and
+   trigger a view query to force the view to be updated. For more
+   information, see :ref:`update-notifications`.
+
+None of these can completely eliminate the need for the indexes to be
+rebuilt or updated when the view is accessed, but they may lessen the
+effects on end-users of the index update affecting the user experience.
+
+Another alternative is to allow users to access a 'stale' version of the
+view index, rather than forcing the index to be updated and displaying
+the updated results. Using a stale view may not return the latest
+information, but will return the results of the view query using an
+existing version of the index.
+
+For example, to access the existing stale view ``by_recipe`` in the
+``recipes`` design document:
+
+.. code-block:: text
+
+    http://couchdb:5984/recipes/_design/recipes/_view/by_recipe?stale=ok
+
+Accessing a stale view:
+
+-  Does not trigger a rebuild of the view indexes, even if there have
+   been changes since the last access.
+
+-  Returns the current version of the view index, if a current version
+   exists.
+
+-  Returns an empty result set if the given view index does exist.
+
+As an alternative, you use the ``update_after`` value to the ``stale``
+parameter. This causes the view to be returned as a stale view, but for
+the update process to be triggered after the view information has been
+returned to the client.
+
+In addition to using stale views, you can also make use of the
+``update_seq`` query argument. Using this query argument generates the
+view information including the update sequence of the database from
+which the view was generated. The returned value can be compared this to
+the current update sequence exposed in the database information
+(returned by :ref:`api/db.get`).
+
+Sorting Returned Rows
+---------------------
+
+Each element within the returned array is sorted using native UTF-8
+sorting according to the contents of the key portion of the emitted
+content. The basic order of output is as follows:
+
+-  ``null``
+
+-  ``false``
+
+-  ``true``
+
+-  Numbers
+
+-  Text (case sensitive, lowercase first)
+
+-  Arrays (according to the values of each element, in order)
+
+-  Objects (according to the values of keys, in key order)
+
+You can reverse the order of the returned view information by using the
+``descending`` query value set to true. For example, Retrieving the list
+of recipes using the ``by_title`` (limited to 5 records) view:
+
+.. code-block:: javascript
+
+    {
+       "offset" : 0,
+       "rows" : [
+          {
+             "id" : "3-tiersalmonspinachandavocadoterrine",
+             "key" : "3-tier salmon, spinach and avocado terrine",
+             "value" : [
+                null,
+                "3-tier salmon, spinach and avocado terrine"
+             ]
+          },
+          {
+             "id" : "Aberffrawcake",
+             "key" : "Aberffraw cake",
+             "value" : [
+                null,
+                "Aberffraw cake"
+             ]
+          },
+          {
+             "id" : "Adukiandorangecasserole-microwave",
+             "key" : "Aduki and orange casserole - microwave",
+             "value" : [
+                null,
+                "Aduki and orange casserole - microwave"
+             ]
+          },
+          {
+             "id" : "Aioli-garlicmayonnaise",
+             "key" : "Aioli - garlic mayonnaise",
+             "value" : [
+                null,
+                "Aioli - garlic mayonnaise"
+             ]
+          },
+          {
+             "id" : "Alabamapeanutchicken",
+             "key" : "Alabama peanut chicken",
+             "value" : [
+                null,
+                "Alabama peanut chicken"
+             ]
+          }
+       ],
+       "total_rows" : 2667
+    }
+
+Requesting the same in descending order will reverse the entire view
+content. For example the request
+
+.. code-block:: http
+
+    GET http://couchdb:5984/recipes/_design/recipes/_view/by_title?limit=5&descending=true
+    Accept: application/json
+    Content-Type: application/json
+
+Returns the last 5 records from the view:
+
+.. code-block:: javascript
+
+    {
+       "offset" : 0,
+       "rows" : [
+          {
+             "id" : "Zucchiniinagrodolcesweet-sourcourgettes",
+             "key" : "Zucchini in agrodolce (sweet-sour courgettes)",
+             "value" : [
+                null,
+                "Zucchini in agrodolce (sweet-sour courgettes)"
+             ]
+          },
+          {
+             "id" : "Zingylemontart",
+             "key" : "Zingy lemon tart",
+             "value" : [
+                null,
+                "Zingy lemon tart"
+             ]
+          },
+          {
+             "id" : "Zestyseafoodavocado",
+             "key" : "Zesty seafood avocado",
+             "value" : [
+                null,
+                "Zesty seafood avocado"
+             ]
+          },
+          {
+             "id" : "Zabaglione",
+             "key" : "Zabaglione",
+             "value" : [
+                null,
+                "Zabaglione"
+             ]
+          },
+          {
+             "id" : "Yogurtraita",
+             "key" : "Yogurt raita",
+             "value" : [
+                null,
+                "Yogurt raita"
+             ]
+          }
+       ],
+       "total_rows" : 2667
+    }
+
+The sorting direction is applied before the filtering applied using the
+``startkey`` and ``endkey`` query arguments. For example the following
+query:
+
+.. code-block:: http
+
+    GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?startkey=%22carrots%22&endkey=%22egg%22
+    Accept: application/json
+    Content-Type: application/json
+
+Will operate correctly when listing all the matching entries between
+“carrots” and ``egg``. If the order of output is reversed with the
+``descending`` query argument, the view request will return no entries:
+
+.. code-block:: http
+
+    GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22carrots%22&endkey=%22egg%22
+    Accept: application/json
+    Content-Type: application/json
+
+The returned result is empty:
+
+.. code-block:: javascript
+
+    {
+       "total_rows" : 26453,
+       "rows" : [],
+       "offset" : 21882
+    }
+
+The results will be empty because the entries in the view are reversed
+before the key filter is applied, and therefore the ``endkey`` of “egg”
+will be seen before the ``startkey`` of “carrots”, resulting in an empty
+list.
+
+Instead, you should reverse the values supplied to the ``startkey`` and
+``endkey`` parameters to match the descending sorting applied to the
+keys. Changing the previous example to:
+
+.. code-block:: http
+
+    GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22egg%22&endkey=%22carrots%22
+    Accept: application/json
+    Content-Type: application/json
+
+Specifying Start and End Values
+-------------------------------
+
+.. todo:: Specifying Start and End Values
+
+The ``startkey`` and ``endkey`` query arguments can be used to specify
+the range of values to be displayed when querying the view.
+
+Using Limits and Skipping Rows
+------------------------------
+
+.. todo:: Using Limits and Skipping Rows
+
+TBC
+
+View Reduction and Grouping
+---------------------------
+
+.. todo:: View Reduction and Grouping
+
+TBC
+
+.. _api/ddoc/view.post:
+
+``POST /db/_design/design-doc/_view/view-name``
+===============================================
+
+* **Method**: ``POST /db/_design/design-doc/_view/view-name``
+* **Request**:  List of keys to be returned from specified view
+* **Response**:  JSON of the documents returned by the view
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+  * **Argument**: descending
+
+    * **Description**:  Return the documents in descending by key order
+    * **Optional**: yes
+    * **Type**: boolean
+    * **Default**: false
+
+  * **Argument**: endkey
+
+    * **Description**:  Stop returning records when the specified key is reached
+    * **Optional**: yes
+    * **Type**: string
+
+  * **Argument**: endkey_docid
+
+    * **Description**:  Stop returning records when the specified document ID
+      is reached
+    * **Optional**: yes
+    * **Type**: string
+
+  * **Argument**: group
+
+    * **Description**:  Group the results using the reduce function to a group
+      or single row
+    * **Optional**: yes
+    * **Type**: boolean
+    * **Default**: false
+
+  * **Argument**: group_level
+
+    * **Description**:  Specify the group level to be used
+    * **Optional**: yes
+    * **Type**: numeric
+
+  * **Argument**: include_docs
+
+    * **Description**:  Include the full content of the documents in the return
+    * **Optional**: yes
+    * **Type**: boolean
+    * **Default**: false
+
+  * **Argument**: inclusive_end
+
+    * **Description**:  Specifies whether the specified end key should be
+      included in the result
+    * **Optional**: yes
+    * **Type**: boolean
+    * **Default**: true
+
+  * **Argument**: key
+
+    * **Description**:  Return only documents that match the specified key
+    * **Optional**: yes
+    * **Type**: string
+
+  * **Argument**: limit
+
+    * **Description**:  Limit the number of the returned documents to the
+      specified number
+    * **Optional**: yes
+    * **Type**: numeric
+
+  * **Argument**: reduce
+
+    * **Description**:  Use the reduction function
+    * **Optional**: yes
+    * **Type**: boolean
+    * **Default**: true
+
+  * **Argument**: skip
+
+    * **Description**:  Skip this number of records before starting to return
+      the results
+    * **Optional**: yes
+    * **Type**: numeric
+    * **Default**: 0
+
+  * **Argument**: stale
+
+    * **Description**:  Allow the results from a stale view to be used
+    * **Optional**: yes
+    * **Type**: string
+    * **Default**:
+    * **Supported Values**:
+
+      * **ok**: Allow stale views
+
+  * **Argument**: startkey
+
+    * **Description**:  Return records starting with the specified key
+    * **Optional**: yes
+    * **Type**: string
+
+  * **Argument**: startkey_docid
+
+    * **Description**:  Return records starting with the specified document ID
+    * **Optional**: yes
+    * **Type**: string
+
+  * **Argument**: update_seq
+
+    * **Description**:  Include the update sequence in the generated results
+    * **Optional**: yes
+    * **Type**: boolean
+    * **Default**: false
+
+Executes the specified ``view-name`` from the specified ``design-doc``
+design document. Unlike the ``GET`` method for accessing views, the
+``POST`` method supports the specification of explicit keys to be
+retrieved from the view results. The remainder of the ``POST`` view
+functionality is identical to the :ref:`api/ddoc/view.get` API.
+
+For example, the request below will return all the recipes where the key
+for the view matches either “claret” or “clear apple cider” :
+
+.. code-block:: http
+
+    POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient
+    Content-Type: application/json
+
+    {
+       "keys" : [
+          "claret",
+          "clear apple juice"
+       ]
+    }
+
+
+The returned view data contains the standard view information, but only
+where the keys match.
+
+.. code-block:: javascript
+
+    {
+       "total_rows" : 26484,
+       "rows" : [
+          {
+             "value" : [
+                "Scotch collops"
+             ],
+             "id" : "Scotchcollops",
+             "key" : "claret"
+          },
+          {
+             "value" : [
+                "Stand pie"
+             ],
+             "id" : "Standpie",
+             "key" : "clear apple juice"
+          }
+       ],
+       "offset" : 6324
+    }
+
+Multi-document Fetching
+-----------------------
+
+By combining the ``POST`` method to a given view with the
+``include_docs=true`` query argument you can obtain multiple documents
+from a database. The result is more efficient than using multiple
+:ref:`api/doc.get` requests.
+
+For example, sending the following request for ingredients matching
+“claret” and “clear apple juice”:
+
+.. code-block:: http
+
+    POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?include_docs=true
+    Content-Type: application/json
+
+    {
+       "keys" : [
+          "claret",
+          "clear apple juice"
+       ]
+    }
+
+Returns the full document for each recipe:
+
+.. code-block:: javascript
+
+    {
+       "offset" : 6324,
+       "rows" : [
+          {
+             "doc" : {
+                "_id" : "Scotchcollops",
+                "_rev" : "1-bcbdf724f8544c89697a1cbc4b9f0178",
+                "cooktime" : "8",
+                "ingredients" : [
+                   {
+                      "ingredient" : "onion",
+                      "ingredtext" : "onion, peeled and chopped",
+                      "meastext" : "1"
+                   },
+                ...
+                ],
+                "keywords" : [
+                   "cook method.hob, oven, grill@hob",
+                   "diet@wheat-free",
+                   "diet@peanut-free",
+                   "special collections@classic recipe",
+                   "cuisine@british traditional",
+                   "diet@corn-free",
+                   "diet@citrus-free",
+                   "special collections@very easy",
+                   "diet@shellfish-free",
+                   "main ingredient@meat",
+                   "occasion@christmas",
+                   "meal type@main",
+                   "diet@egg-free",
+                   "diet@gluten-free"
+                ],
+                "preptime" : "10",
+                "servings" : "4",
+                "subtitle" : "This recipe comes from an old recipe book of 1683 called 'The Gentlewoman's Kitchen'. This is an excellent way of making a rich and full-flavoured meat dish in a very short time.",
+                "title" : "Scotch collops",
+                "totaltime" : "18"
+             },
+             "id" : "Scotchcollops",
+             "key" : "claret",
+             "value" : [
+                "Scotch collops"
+             ]
+          },
+          {
+             "doc" : {
+                "_id" : "Standpie",
+                "_rev" : "1-bff6edf3ca2474a243023f2dad432a5a",
+                "cooktime" : "92",
+                "ingredients" : [
+    ...            ],
+                "keywords" : [
+                   "diet@dairy-free",
+                   "diet@peanut-free",
+                   "special collections@classic recipe",
+                   "cuisine@british traditional",
+                   "diet@corn-free",
+                   "diet@citrus-free",
+                   "occasion@buffet party",
+                   "diet@shellfish-free",
+                   "occasion@picnic",
+                   "special collections@lunchbox",
+                   "main ingredient@meat",
+                   "convenience@serve with salad for complete meal",
+                   "meal type@main",
+                   "cook method.hob, oven, grill@hob / oven",
+                   "diet@cow dairy-free"
+                ],
+                "preptime" : "30",
+                "servings" : "6",
+                "subtitle" : "Serve this pie with pickled vegetables and potato salad.",
+                "title" : "Stand pie",
+                "totaltime" : "437"
+             },
+             "id" : "Standpie",
+             "key" : "clear apple juice",
+             "value" : [
+                "Stand pie"
+             ]
+          }
+       ],
+       "total_rows" : 26484
+    }

http://git-wip-us.apache.org/repos/asf/couchdb/blob/d67c2733/share/doc/src/api/design.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/design.rst b/share/doc/src/api/design.rst
deleted file mode 100644
index 570c08e..0000000
--- a/share/doc/src/api/design.rst
+++ /dev/null
@@ -1,1306 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-..   http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. _api/ddoc:
-
-=======================
-Design Document Methods
-=======================
-
-In CouchDB, design documents provide the main interface for building a
-CouchDB application. The design document defines the views used to
-extract information from CouchDB through one or more views. Design
-documents are created within your CouchDB instance in the same way as
-you create database documents, but the content and definition of the
-documents is different. Design Documents are named using an ID defined
-with the design document URL path, and this URL can then be used to
-access the database contents.
-
-Views and lists operate together to provide automated (and formatted)
-output from your database.
-
-A list of the available methods and URL paths are provided below:
-
-Design Document API Calls
-
-.. _api/ddoc.get:
-
-``GET /db/_design/design-doc``
-==============================
-
-* **Method**: ``GET /db/_design/design-doc``
-* **Request**:  None
-* **Response**:  JSON of the existing design document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
-  * **Argument**: rev
-
-    * **Description**:  Specify the revision to return
-    * **Optional**: yes
-    * **Type**: string
-
-  * **Argument**: revs
-
-    * **Description**:  Return a list of the revisions for the document
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Supported Values**:
-
-        * **true**: Includes the revisions
-
-  * **Argument**: revs_info
-
-    * **Description**:  Return a list of detailed revision information for the
-      document
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Supported Values**:
-
-      * **true**: Includes the revisions
-
-Returns the specified design document, ``design-doc`` from the specified
-``db``. For example, to retrieve the design document ``recipes`` you
-would send the following request:
-
-.. code-block:: http
-
-    GET http://couchdb:5984/recipes/_design/recipes
-    Content-Type: application/json
-
-The returned string will be the JSON of the design document:
-
-.. code-block:: javascript
-
-    {
-       "_id" : "_design/recipes",
-       "_rev" : "5-39f56a392b86bbee57e2138921346406"
-       "language" : "javascript",
-       "views" : {
-          "by_recipe" : {
-             "map" : "function(doc) { if (doc.title != null) emit(doc.title, doc) }"
-          },
-       },
-    }
-
-A list of the revisions can be obtained by using the ``revs`` query
-argument, or an extended list of revisions using the ``revs_info`` query
-argument. This operates in the same way as for other documents. Fur
-further examples, see :ref:`api/doc.get`.
-
-.. _api/ddoc.put:
-
-``PUT /db/_design/design-doc``
-==============================
-
-* **Method**: ``PUT /db/_design/design-doc``
-* **Request**:  JSON of the design document
-* **Response**:  JSON status
-* **Admin Privileges Required**: no
-
-Upload the specified design document, ``design-doc``, to the specified
-database. The design document should follow the definition of a design
-document, as summarised in the following table.
-
-* **_id**:  Design Document ID
-* **_rev**:  Design Document Revision
-* **views**:  View
-
-  * **viewname**:  View Definition
-
-    * **map**:  Map Function for View
-    * **reduce (optional)**:  Reduce Function for View
-
-For more information on writing views, see :ref:`api/ddoc/view`.
-
-.. _api/ddoc.delete:
-
-``DELETE /db/_design/design-doc``
-=================================
-
-* **Method**: ``DELETE /db/_design/design-doc``
-* **Request**:  None
-* **Response**:  JSON of deleted design document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
-  * **Argument**: rev
-
-    * **Description**:  Current revision of the document for validation
-    * **Optional**: yes
-    * **Type**: string
-
-* **HTTP Headers**
-
-  * **Header**: ``If-Match``
-
-    * **Description**: Current revision of the document for validation
-    * **Optional**: yes
-
-* **Return Codes**:
-
-  * **409**:
-    Supplied revision is incorrect or missing
-
-Delete an existing design document. Deleting a design document also
-deletes all of the associated view indexes, and recovers the
-corresponding space on disk for the indexes in question.
-
-To delete, you must specify the current revision of the design document
-using the ``rev`` query argument.
-
-For example:
-
-.. code-block:: http
-
-    DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8
-    Content-Type: application/json
-
-The response contains the delete document ID and revision:
-
-.. code-block:: javascript
-
-    {
-       "id" : "recipe/_design/recipes"
-       "ok" : true,
-       "rev" : "3-7a05370bff53186cb5d403f861aca154",
-    }
-
-.. _api/ddoc.copy:
-
-``COPY /db/_design/design-doc``
-===============================
-
-* **Method**: ``COPY /db/_design/design-doc``
-* **Request**: None
-* **Response**: JSON of the new document and revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
-  * **Argument**: rev
-
-    * **Description**:  Revision to copy from
-    * **Optional**: yes
-    * **Type**: string
-
-* **HTTP Headers**
-
-  * **Header**: ``Destination``
-
-    * **Description**: Destination document (and optional revision)
-    * **Optional**: no
-
-The ``COPY`` command (non-standard HTTP) copies an existing design
-document to a new or existing document.
-
-The source design document is specified on the request line, with the
-``Destination`` HTTP Header of the request specifying the target
-document.
-
-Copying a Design Document
--------------------------
-
-To copy the latest version of a design document to a new document you
-specify the base document and target document:
-
-.. code-block:: http
-
-    COPY http://couchdb:5984/recipes/_design/recipes
-    Content-Type: application/json
-    Destination: /recipes/_design/recipelist
-
-The above request copies the design document ``recipes`` to the new
-design document ``recipelist``. The response is the ID and revision of
-the new document.
-
-.. code-block:: javascript
-
-    {
-       "id" : "recipes/_design/recipelist"
-       "rev" : "1-9c65296036141e575d32ba9c034dd3ee",
-    }
-
-.. note::
-   Copying a design document does automatically reconstruct the view
-   indexes. These will be recreated, as with other views, the first
-   time the new view is accessed.
-
-Copying from a Specific Revision
---------------------------------
-
-To copy *from* a specific version, use the ``rev`` argument to the query
-string:
-
-.. code-block:: http
-
-    COPY http://couchdb:5984/recipes/_design/recipes?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5
-    Content-Type: application/json
-    Destination: recipes/_design/recipelist
-
-The new design document will be created using the specified revision of
-the source document.
-
-Copying to an Existing Design Document
---------------------------------------
-
-To copy to an existing document, you must specify the current revision
-string for the target document, using the ``rev`` parameter to the
-``Destination`` HTTP Header string. For example:
-
-.. code-block:: http
-
-    COPY http://couchdb:5984/recipes/_design/recipes
-    Content-Type: application/json
-    Destination: recipes/_design/recipelist?rev=1-9c65296036141e575d32ba9c034dd3ee
-
-The return value will be the new revision of the copied document:
-
-.. code-block:: javascript
-
-    {
-       "id" : "recipes/_design/recipes"
-       "rev" : "2-55b6a1b251902a2c249b667dab1c6692",
-    }
-
-.. _api/ddoc/attachment:
-.. _api/ddoc/attachment.get:
-
-``GET /db/_design/design-doc/attachment``
-=========================================
-
-* **Method**: ``GET /db/_design/design-doc/attachment``
-* **Request**: None
-* **Response**: Returns the attachment data
-* **Admin Privileges Required**: no
-
-Returns the file attachment ``attachment`` associated with the design
-document ``/_design_/design-doc``. The raw data of the associated
-attachment is returned (just as if you were accessing a static file. The
-returned HTTP ``Content-type`` will be the same as the content type set
-when the document attachment was submitted into the database.
-
-.. _api/ddoc/attachment.put:
-
-``PUT /db/_design/design-doc/attachment``
-=========================================
-
-* **Method**: ``PUT /db/_design/design-doc/attachment``
-* **Request**: Raw document data
-* **Response**: JSON document status
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
-  * **Argument**: rev
-
-    * **Description**:  Current document revision
-    * **Optional**: no
-    * **Type**: string
-
-* **HTTP Headers**
-
-  * **Header**: ``Content-Length``
-
-    * **Description**: Length (bytes) of the attachment being uploaded
-    * **Optional**: no
-
-  * **Header**: ``Content-Type``
-
-    * **Description**: MIME type for the uploaded attachment
-    * **Optional**: no
-
-  * **Header**: ``If-Match``
-
-    * **Description**: Current revision of the document for validation
-    * **Optional**: yes
-
-Upload the supplied content as an attachment to the specified design
-document (``/_design/design-doc``). The ``attachment`` name provided
-must be a URL encoded string. You must also supply either the ``rev``
-query argument or the ``If-Match`` HTTP header for validation, and the
-HTTP headers (to set the attachment content type). The content type is
-used when the attachment is requested as the corresponding content-type
-in the returned document header.
-
-For example, you could upload a simple text document using the following
-request:
-
-.. code-block:: http
-
-    PUT http://couchdb:5984/recipes/_design/recipes/view.css?rev=7-f7114d4d81124b223283f3e89eee043e
-    Content-Length: 39
-    Content-Type: text/plain
-
-    div.recipetitle {
-    font-weight: bold;
-    }
-
-Or by using the ``If-Match`` HTTP header:
-
-.. code-block:: http
-
-    PUT http://couchdb:5984/recipes/FishStew/basic
-    If-Match: 7-f7114d4d81124b223283f3e89eee043e
-    Content-Length: 39
-    Content-Type: text/plain
-
-    div.recipetitle {
-    font-weight: bold;
-    }
-
-The returned JSON contains the new document information:
-
-.. code-block:: javascript
-
-    {
-       "id" : "_design/recipes"
-       "ok" : true,
-       "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5",
-    }
-
-.. note::
-   Uploading an attachment updates the corresponding document revision.
-   Revisions are tracked for the parent document, not individual attachments.
-
-.. _api/ddoc/attachment.delete:
-
-``DELETE /db/_design/design-doc/attachment``
-============================================
-
-* **Method**: ``DELETE /db/_design/design-doc/attachment``
-* **Request**: None
-* **Response**: JSON status
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
-  * **Argument**: rev
-
-    * **Description**:  Current document revision
-    * **Optional**: no
-    * **Type**: string
-
-* **HTTP Headers**
-
-  * **Header**: ``If-Match``
-
-    * **Description**: Current revision of the document for validation
-    * **Optional**: yes
-
-* **Return Codes**:
-
-  * **200**:
-    Attachment deleted successfully
-  * **409**:
-    Supplied revision is incorrect or missing
-
-Deletes the attachment ``attachment`` to the specified
-``_design/design-doc``. You must supply the ``rev`` argument with the
-current revision to delete the attachment.
-
-For example to delete the attachment ``view.css`` from the design
-document ``recipes``:
-
-.. code-block:: http
-
-    DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a
-
-The returned JSON contains the updated revision information for the
-parent document:
-
-.. code-block:: javascript
-
-    {
-       "id" : "_design/recipes"
-       "ok" : true,
-       "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c",
-    }
-
-.. _api/ddoc/info:
-.. _api/ddoc/info.get:
-
-``GET /db/_design/design-doc/_info``
-====================================
-
-* **Method**: ``GET /db/_design/design-doc/_info``
-* **Request**: None
-* **Response**: JSON of the design document information
-* **Admin Privileges Required**: no
-
-Obtains information about a given design document, including the index,
-index size and current status of the design document and associated
-index information.
-
-For example, to get the information for the ``recipes`` design document:
-
-.. code-block:: http
-
-    GET http://couchdb:5984/recipes/_design/recipes/_info
-    Content-Type: application/json
-
-This returns the following JSON structure:
-
-.. code-block:: javascript
-
-    {
-       "name" : "recipes"
-       "view_index" : {
-          "compact_running" : false,
-          "updater_running" : false,
-          "language" : "javascript",
-          "purge_seq" : 10,
-          "waiting_commit" : false,
-          "waiting_clients" : 0,
-          "signature" : "fc65594ee76087a3b8c726caf5b40687",
-          "update_seq" : 375031,
-          "disk_size" : 16491
-       },
-    }
-
-The individual fields in the returned JSON structure are detailed below:
-
-* **name**:  Name/ID of Design Document
-* **view_index**:  View Index
-
-  * **compact_running**:  Indicates whether a compaction routine is currently
-    running on the view
-  * **disk_size**:  Size in bytes of the view as stored on disk
-  * **language**:  Language for the defined views
-  * **purge_seq**:  The purge sequence that has been processed
-  * **signature**:  MD5 signature of the views for the design document
-  * **update_seq**:  The update sequence of the corresponding database that
-    has been indexed
-  * **updater_running**:  Indicates if the view is currently being updated
-  * **waiting_clients**:  Number of clients waiting on views from this design
-    document
-  * **waiting_commit**:  Indicates if there are outstanding commits to the
-    underlying database that need to processed
-
-.. _api/ddoc/view:
-.. _api/ddoc/view.get:
-
-``GET /db/_design/design-doc/_view/view-name``
-==============================================
-
-* **Method**: ``GET /db/_design/design-doc/_view/view-name``
-* **Request**: None
-* **Response**: JSON of the documents returned by the view
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
-  * **Argument**: descending
-
-    * **Description**:  Return the documents in descending by key order
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Default**: false
-
-  * **Argument**: endkey
-
-    * **Description**:  Stop returning records when the specified key is reached
-    * **Optional**: yes
-    * **Type**: string
-
-  * **Argument**: endkey_docid
-
-    * **Description**:  Stop returning records when the specified document
-      ID is reached
-    * **Optional**: yes
-    * **Type**: string
-
-  * **Argument**: group
-
-    * **Description**:  Group the results using the reduce function to a
-      group or single row
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Default**: false
-
-  * **Argument**: group_level
-
-    * **Description**:  Specify the group level to be used
-    * **Optional**: yes
-    * **Type**: numeric
-
-  * **Argument**: include_docs
-
-    * **Description**:  Include the full content of the documents in the return
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Default**: false
-
-  * **Argument**: inclusive_end
-
-    * **Description**:  Specifies whether the specified end key should be
-      included in the result
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Default**: true
-
-  * **Argument**: key
-
-    * **Description**:  Return only documents that match the specified key
-    * **Optional**: yes
-    * **Type**: string
-
-  * **Argument**: limit
-
-    * **Description**:  Limit the number of the returned documents to the
-      specified number
-    * **Optional**: yes
-    * **Type**: numeric
-
-  * **Argument**: reduce
-
-    * **Description**:  Use the reduction function
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Default**: true
-
-  * **Argument**: skip
-
-    * **Description**:  Skip this number of records before starting to return
-      the results
-    * **Optional**: yes
-    * **Type**: numeric
-    * **Default**: 0
-
-  * **Argument**: stale
-
-    * **Description**:  Allow the results from a stale view to be used
-    * **Optional**: yes
-    * **Type**: string
-    * **Default**:
-    * **Supported Values**
-
-      * **ok**: Allow stale views
-
-  * **Argument**: startkey
-
-    * **Description**:  Return records starting with the specified key
-    * **Optional**: yes
-    * **Type**: string
-
-  * **Argument**: startkey_docid
-
-    * **Description**:  Return records starting with the specified document ID
-    * **Optional**: yes
-    * **Type**: string
-
-  * **Argument**: update_seq
-
-    * **Description**:  Include the update sequence in the generated results
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Default**: false
-
-Executes the specified ``view-name`` from the specified ``design-doc``
-design document.
-
-Querying Views and Indexes
---------------------------
-
-The definition of a view within a design document also creates an index
-based on the key information defined within each view. The production
-and use of the index significantly increases the speed of access and
-searching or selecting documents from the view.
-
-However, the index is not updated when new documents are added or
-modified in the database. Instead, the index is generated or updated,
-either when the view is first accessed, or when the view is accessed
-after a document has been updated. In each case, the index is updated
-before the view query is executed against the database.
-
-View indexes are updated incrementally in the following situations:
-
--  A new document has been added to the database.
-
--  A document has been deleted from the database.
-
--  A document in the database has been updated.
-
-View indexes are rebuilt entirely when the view definition changes. To
-achieve this, a 'fingerprint' of the view definition is created when the
-design document is updated. If the fingerprint changes, then the view
-indexes are entirely rebuilt. This ensures that changes to the view
-definitions are reflected in the view indexes.
-
-.. note::
-   View index rebuilds occur when one view from the same the view group
-   (i.e. all the views defined within a single a design document) has
-   been determined as needing a rebuild. For example, if if you have a
-   design document with different views, and you update the database,
-   all three view indexes within the design document will be updated.
-
-Because the view is updated when it has been queried, it can result in a
-delay in returned information when the view is accessed, especially if
-there are a large number of documents in the database and the view index
-does not exist. There are a number of ways to mitigate, but not
-completely eliminate, these issues. These include:
-
--  Create the view definition (and associated design documents) on your
-   database before allowing insertion or updates to the documents. If
-   this is allowed while the view is being accessed, the index can be
-   updated incrementally.
-
--  Manually force a view request from the database. You can do this
-   either before users are allowed to use the view, or you can access
-   the view manually after documents are added or updated.
-
--  Use the ``/db/_changes`` method to monitor for changes to the
-   database and then access the view to force the corresponding view
-   index to be updated. See :ref:`api/db/changes` for more information.
-
--  Use a monitor with the ``update_notification`` section of the CouchDB
-   configuration file to monitor for changes to your database, and
-   trigger a view query to force the view to be updated. For more
-   information, see :ref:`update-notifications`.
-
-None of these can completely eliminate the need for the indexes to be
-rebuilt or updated when the view is accessed, but they may lessen the
-effects on end-users of the index update affecting the user experience.
-
-Another alternative is to allow users to access a 'stale' version of the
-view index, rather than forcing the index to be updated and displaying
-the updated results. Using a stale view may not return the latest
-information, but will return the results of the view query using an
-existing version of the index.
-
-For example, to access the existing stale view ``by_recipe`` in the
-``recipes`` design document:
-
-.. code-block:: text
-
-    http://couchdb:5984/recipes/_design/recipes/_view/by_recipe?stale=ok
-
-Accessing a stale view:
-
--  Does not trigger a rebuild of the view indexes, even if there have
-   been changes since the last access.
-
--  Returns the current version of the view index, if a current version
-   exists.
-
--  Returns an empty result set if the given view index does exist.
-
-As an alternative, you use the ``update_after`` value to the ``stale``
-parameter. This causes the view to be returned as a stale view, but for
-the update process to be triggered after the view information has been
-returned to the client.
-
-In addition to using stale views, you can also make use of the
-``update_seq`` query argument. Using this query argument generates the
-view information including the update sequence of the database from
-which the view was generated. The returned value can be compared this to
-the current update sequence exposed in the database information
-(returned by :ref:`api/db.get`).
-
-Sorting Returned Rows
----------------------
-
-Each element within the returned array is sorted using native UTF-8
-sorting according to the contents of the key portion of the emitted
-content. The basic order of output is as follows:
-
--  ``null``
-
--  ``false``
-
--  ``true``
-
--  Numbers
-
--  Text (case sensitive, lowercase first)
-
--  Arrays (according to the values of each element, in order)
-
--  Objects (according to the values of keys, in key order)
-
-You can reverse the order of the returned view information by using the
-``descending`` query value set to true. For example, Retrieving the list
-of recipes using the ``by_title`` (limited to 5 records) view:
-
-.. code-block:: javascript
-
-    {
-       "offset" : 0,
-       "rows" : [
-          {
-             "id" : "3-tiersalmonspinachandavocadoterrine",
-             "key" : "3-tier salmon, spinach and avocado terrine",
-             "value" : [
-                null,
-                "3-tier salmon, spinach and avocado terrine"
-             ]
-          },
-          {
-             "id" : "Aberffrawcake",
-             "key" : "Aberffraw cake",
-             "value" : [
-                null,
-                "Aberffraw cake"
-             ]
-          },
-          {
-             "id" : "Adukiandorangecasserole-microwave",
-             "key" : "Aduki and orange casserole - microwave",
-             "value" : [
-                null,
-                "Aduki and orange casserole - microwave"
-             ]
-          },
-          {
-             "id" : "Aioli-garlicmayonnaise",
-             "key" : "Aioli - garlic mayonnaise",
-             "value" : [
-                null,
-                "Aioli - garlic mayonnaise"
-             ]
-          },
-          {
-             "id" : "Alabamapeanutchicken",
-             "key" : "Alabama peanut chicken",
-             "value" : [
-                null,
-                "Alabama peanut chicken"
-             ]
-          }
-       ],
-       "total_rows" : 2667
-    }
-
-Requesting the same in descending order will reverse the entire view
-content. For example the request
-
-.. code-block:: http
-
-    GET http://couchdb:5984/recipes/_design/recipes/_view/by_title?limit=5&descending=true
-    Accept: application/json
-    Content-Type: application/json
-
-Returns the last 5 records from the view:
-
-.. code-block:: javascript
-
-    {
-       "offset" : 0,
-       "rows" : [
-          {
-             "id" : "Zucchiniinagrodolcesweet-sourcourgettes",
-             "key" : "Zucchini in agrodolce (sweet-sour courgettes)",
-             "value" : [
-                null,
-                "Zucchini in agrodolce (sweet-sour courgettes)"
-             ]
-          },
-          {
-             "id" : "Zingylemontart",
-             "key" : "Zingy lemon tart",
-             "value" : [
-                null,
-                "Zingy lemon tart"
-             ]
-          },
-          {
-             "id" : "Zestyseafoodavocado",
-             "key" : "Zesty seafood avocado",
-             "value" : [
-                null,
-                "Zesty seafood avocado"
-             ]
-          },
-          {
-             "id" : "Zabaglione",
-             "key" : "Zabaglione",
-             "value" : [
-                null,
-                "Zabaglione"
-             ]
-          },
-          {
-             "id" : "Yogurtraita",
-             "key" : "Yogurt raita",
-             "value" : [
-                null,
-                "Yogurt raita"
-             ]
-          }
-       ],
-       "total_rows" : 2667
-    }
-
-The sorting direction is applied before the filtering applied using the
-``startkey`` and ``endkey`` query arguments. For example the following
-query:
-
-.. code-block:: http
-
-    GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?startkey=%22carrots%22&endkey=%22egg%22
-    Accept: application/json
-    Content-Type: application/json
-
-Will operate correctly when listing all the matching entries between
-“carrots” and ``egg``. If the order of output is reversed with the
-``descending`` query argument, the view request will return no entries:
-
-.. code-block:: http
-
-    GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22carrots%22&endkey=%22egg%22
-    Accept: application/json
-    Content-Type: application/json
-
-The returned result is empty:
-
-.. code-block:: javascript
-
-    {
-       "total_rows" : 26453,
-       "rows" : [],
-       "offset" : 21882
-    }
-
-The results will be empty because the entries in the view are reversed
-before the key filter is applied, and therefore the ``endkey`` of “egg”
-will be seen before the ``startkey`` of “carrots”, resulting in an empty
-list.
-
-Instead, you should reverse the values supplied to the ``startkey`` and
-``endkey`` parameters to match the descending sorting applied to the
-keys. Changing the previous example to:
-
-.. code-block:: http
-
-    GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22egg%22&endkey=%22carrots%22
-    Accept: application/json
-    Content-Type: application/json
-
-Specifying Start and End Values
--------------------------------
-
-.. todo:: Specifying Start and End Values
-
-The ``startkey`` and ``endkey`` query arguments can be used to specify
-the range of values to be displayed when querying the view.
-
-Using Limits and Skipping Rows
-------------------------------
-
-.. todo:: Using Limits and Skipping Rows
-
-TBC
-
-View Reduction and Grouping
----------------------------
-
-.. todo:: View Reduction and Grouping
-
-TBC
-
-.. _api/ddoc/view.post:
-
-``POST /db/_design/design-doc/_view/view-name``
-===============================================
-
-* **Method**: ``POST /db/_design/design-doc/_view/view-name``
-* **Request**:  List of keys to be returned from specified view
-* **Response**:  JSON of the documents returned by the view
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
-  * **Argument**: descending
-
-    * **Description**:  Return the documents in descending by key order
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Default**: false
-
-  * **Argument**: endkey
-
-    * **Description**:  Stop returning records when the specified key is reached
-    * **Optional**: yes
-    * **Type**: string
-
-  * **Argument**: endkey_docid
-
-    * **Description**:  Stop returning records when the specified document ID
-      is reached
-    * **Optional**: yes
-    * **Type**: string
-
-  * **Argument**: group
-
-    * **Description**:  Group the results using the reduce function to a group
-      or single row
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Default**: false
-
-  * **Argument**: group_level
-
-    * **Description**:  Specify the group level to be used
-    * **Optional**: yes
-    * **Type**: numeric
-
-  * **Argument**: include_docs
-
-    * **Description**:  Include the full content of the documents in the return
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Default**: false
-
-  * **Argument**: inclusive_end
-
-    * **Description**:  Specifies whether the specified end key should be
-      included in the result
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Default**: true
-
-  * **Argument**: key
-
-    * **Description**:  Return only documents that match the specified key
-    * **Optional**: yes
-    * **Type**: string
-
-  * **Argument**: limit
-
-    * **Description**:  Limit the number of the returned documents to the
-      specified number
-    * **Optional**: yes
-    * **Type**: numeric
-
-  * **Argument**: reduce
-
-    * **Description**:  Use the reduction function
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Default**: true
-
-  * **Argument**: skip
-
-    * **Description**:  Skip this number of records before starting to return
-      the results
-    * **Optional**: yes
-    * **Type**: numeric
-    * **Default**: 0
-
-  * **Argument**: stale
-
-    * **Description**:  Allow the results from a stale view to be used
-    * **Optional**: yes
-    * **Type**: string
-    * **Default**:
-    * **Supported Values**:
-
-      * **ok**: Allow stale views
-
-  * **Argument**: startkey
-
-    * **Description**:  Return records starting with the specified key
-    * **Optional**: yes
-    * **Type**: string
-
-  * **Argument**: startkey_docid
-
-    * **Description**:  Return records starting with the specified document ID
-    * **Optional**: yes
-    * **Type**: string
-
-  * **Argument**: update_seq
-
-    * **Description**:  Include the update sequence in the generated results
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Default**: false
-
-Executes the specified ``view-name`` from the specified ``design-doc``
-design document. Unlike the ``GET`` method for accessing views, the
-``POST`` method supports the specification of explicit keys to be
-retrieved from the view results. The remainder of the ``POST`` view
-functionality is identical to the :ref:`api/ddoc/view.get` API.
-
-For example, the request below will return all the recipes where the key
-for the view matches either “claret” or “clear apple cider” :
-
-.. code-block:: http
-
-    POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient
-    Content-Type: application/json
-
-    {
-       "keys" : [
-          "claret",
-          "clear apple juice"
-       ]
-    }
-          
-
-The returned view data contains the standard view information, but only
-where the keys match.
-
-.. code-block:: javascript
-
-    {
-       "total_rows" : 26484,
-       "rows" : [
-          {
-             "value" : [
-                "Scotch collops"
-             ],
-             "id" : "Scotchcollops",
-             "key" : "claret"
-          },
-          {
-             "value" : [
-                "Stand pie"
-             ],
-             "id" : "Standpie",
-             "key" : "clear apple juice"
-          }
-       ],
-       "offset" : 6324
-    }
-
-Multi-document Fetching
------------------------
-
-By combining the ``POST`` method to a given view with the
-``include_docs=true`` query argument you can obtain multiple documents
-from a database. The result is more efficient than using multiple
-:ref:`api/doc.get` requests.
-
-For example, sending the following request for ingredients matching
-“claret” and “clear apple juice”:
-
-.. code-block:: http
-
-    POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?include_docs=true
-    Content-Type: application/json
-
-    {
-       "keys" : [
-          "claret",
-          "clear apple juice"
-       ]
-    }
-
-Returns the full document for each recipe:
-
-.. code-block:: javascript
-
-    {
-       "offset" : 6324,
-       "rows" : [
-          {
-             "doc" : {
-                "_id" : "Scotchcollops",
-                "_rev" : "1-bcbdf724f8544c89697a1cbc4b9f0178",
-                "cooktime" : "8",
-                "ingredients" : [
-                   {
-                      "ingredient" : "onion",
-                      "ingredtext" : "onion, peeled and chopped",
-                      "meastext" : "1"
-                   },
-                ...
-                ],
-                "keywords" : [
-                   "cook method.hob, oven, grill@hob",
-                   "diet@wheat-free",
-                   "diet@peanut-free",
-                   "special collections@classic recipe",
-                   "cuisine@british traditional",
-                   "diet@corn-free",
-                   "diet@citrus-free",
-                   "special collections@very easy",
-                   "diet@shellfish-free",
-                   "main ingredient@meat",
-                   "occasion@christmas",
-                   "meal type@main",
-                   "diet@egg-free",
-                   "diet@gluten-free"
-                ],
-                "preptime" : "10",
-                "servings" : "4",
-                "subtitle" : "This recipe comes from an old recipe book of 1683 called 'The Gentlewoman's Kitchen'. This is an excellent way of making a rich and full-flavoured meat dish in a very short time.",
-                "title" : "Scotch collops",
-                "totaltime" : "18"
-             },
-             "id" : "Scotchcollops",
-             "key" : "claret",
-             "value" : [
-                "Scotch collops"
-             ]
-          },
-          {
-             "doc" : {
-                "_id" : "Standpie",
-                "_rev" : "1-bff6edf3ca2474a243023f2dad432a5a",
-                "cooktime" : "92",
-                "ingredients" : [
-    ...            ],
-                "keywords" : [
-                   "diet@dairy-free",
-                   "diet@peanut-free",
-                   "special collections@classic recipe",
-                   "cuisine@british traditional",
-                   "diet@corn-free",
-                   "diet@citrus-free",
-                   "occasion@buffet party",
-                   "diet@shellfish-free",
-                   "occasion@picnic",
-                   "special collections@lunchbox",
-                   "main ingredient@meat",
-                   "convenience@serve with salad for complete meal",
-                   "meal type@main",
-                   "cook method.hob, oven, grill@hob / oven",
-                   "diet@cow dairy-free"
-                ],
-                "preptime" : "30",
-                "servings" : "6",
-                "subtitle" : "Serve this pie with pickled vegetables and potato salad.",
-                "title" : "Stand pie",
-                "totaltime" : "437"
-             },
-             "id" : "Standpie",
-             "key" : "clear apple juice",
-             "value" : [
-                "Stand pie"
-             ]
-          }
-       ],
-       "total_rows" : 26484
-    }
-
-.. _api/ddoc/show:
-.. _api/ddoc/show.get:
-
-``GET /db/_design/design-doc/_show/show-name``
-===============================================
-
-.. todo:: GET /db/_design/design-doc/_show/show-name
-
-* **Method**: ``GET /db/_design/design-doc/_show/show-name``
-* **Request**:  None
-* **Response**:  Returns the result of the show
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
-  * **Argument**: details
-
-    * **Description**:  Indicates whether details should be included
-    * **Optional**: yes
-    * **Type**: string
-
-  * **Argument**: format
-
-    * **Description**:  Format of the returned information
-    * **Optional**: yes
-    * **Type**: string
-
-.. _api/ddoc/show/doc.post:
-
-``POST /db/_design/design-doc/_show/show-name/doc``
-===================================================
-
-.. todo:: POST /db/_design/design-doc/_show/show-name/doc
-
-* **Method**: ``POST /db/_design/design-doc/_show/show-name``
-* **Request**:  Custom data
-* **Response**:  Returns the result of the show
-* **Admin Privileges Required**: no
-
-.. _api/ddoc/list/ddoc:
-.. _api/ddoc/list/ddoc.get:
-
-``GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
-=========================================================================
-
-.. todo:: GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name
-
-* **Method**: ``GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
-* **Request**:  TBC
-* **Response**:  TBC
-* **Admin Privileges Required**: no
-
-.. _api/ddoc/list/ddoc.post:
-
-``POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
-==========================================================================
-
-.. todo:: POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name
-
-* **Method**: ``POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
-* **Request**:  TBC
-* **Response**:  TBC
-* **Admin Privileges Required**: no
-
-.. _api/ddoc/list:
-.. _api/ddoc/list.get:
-
-``GET /db/_design/design-doc/_list/list-name/view-name``
-========================================================
-
-.. todo:: GET /db/_design/design-doc/_list/list-name/view-name
-
-* **Method**: ``GET /db/_design/design-doc/_list/list-name/view-name``
-* **Request**:  TBC
-* **Response**:  TBC
-* **Admin Privileges Required**: no
-
-.. _api/ddoc/list.post:
-
-``POST /db/_design/design-doc/_list/list-name/view-name``
-=========================================================
-
-.. todo:: POST /db/_design/design-doc/_list/list-name/view-name
-
-* **Method**: ``POST /db/_design/design-doc/_list/list-name/view-name``
-* **Request**:  TBC
-* **Response**:  TBC
-* **Admin Privileges Required**: no
-
-.. _api/ddoc/update/doc:
-.. _api/ddoc/update/doc.put:
-
-``PUT /db/_design/design-doc/_update/updatename/doc``
-=====================================================
-
-.. todo:: POST /db/_design/design-doc/_update/updatename/doc
-
-* **Method**: ``POST /db/_design/design-doc/_update/updatename/doc``
-* **Request**:  TBC
-* **Response**:  TBC
-* **Admin Privileges Required**: no
-
-.. _api/ddoc/update:
-.. _api/ddoc/update.post:
-
-``POST /db/_design/design-doc/_update/updatename``
-==================================================
-
-.. todo:: PUT /db/_design/design-doc/_update/updatename/doc
-
-* **Method**: ``PUT /db/_design/design-doc/_update/updatename/doc``
-* **Request**:  TBC
-* **Response**:  TBC
-* **Admin Privileges Required**: no
-
-.. _api/ddoc/rewrite:
-
-``ALL /db/_design/design-doc/_rewrite/rewrite-name/anything``
-=============================================================
-
-.. todo:: ALL /db/_design/design-doc/_rewrite/rewrite-name/anything
-
-* **Method**: ``ALL /db/_design/design-doc/_rewrite/rewrite-name/anything``
-* **Request**:  TBC
-* **Response**:  TBC
-* **Admin Privileges Required**: no

http://git-wip-us.apache.org/repos/asf/couchdb/blob/d67c2733/share/doc/src/api/document/attachments.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/attachments.rst b/share/doc/src/api/document/attachments.rst
new file mode 100644
index 0000000..4af8e8c
--- /dev/null
+++ b/share/doc/src/api/document/attachments.rst
@@ -0,0 +1,242 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+
+.. _api/doc/attachment:
+.. _api/doc/attachment.get:
+
+``GET /db/doc/attachment``
+==========================
+
+* **Method**: ``GET /db/doc/attachment``
+* **Request**: None
+* **Response**: Returns the attachment data
+* **Admin Privileges Required**: no
+
+Returns the file attachment ``attachment`` associated with the document
+``doc``. The raw data of the associated attachment is returned (just as
+if you were accessing a static file. The returned HTTP ``Content-type``
+will be the same as the content type set when the document attachment
+was submitted into the database.
+
+.. _api/doc/attachment/range:
+
+HTTP Range Requests
+-------------------
+
+HTTP allows you to specify byte ranges for requests. This allows the
+implementation of resumable downloads and skippable audio and video
+streams alike. This is available for all attachments inside CouchDB.
+
+This is just a real quick run through how this looks under the hood.
+Usually, you will have larger binary files to serve from CouchDB, like
+MP3s and videos, but to make things a little more obvious, I use a text
+file here (Note that I use the ``application/octet-stream`` Content-Type
+instead of ``text/plain``).
+
+.. code-block:: bash
+
+    shell> cat file.txt
+    My hovercraft is full of eels!
+
+Now let's store this text file as an attachment in CouchDB. First, we
+create a database:
+
+.. code-block:: bash
+
+    shell> curl -X PUT http://127.0.0.1:5984/test
+    {"ok":true}
+
+Then we create a new document and the file attachment in one go:
+
+.. code-block:: bash
+
+    shell> curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \
+                -H "Content-Type: application/octet-stream" -d@file.txt
+    {"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}
+
+Now we can request the whole file easily:
+
+.. code-block:: bash
+
+    shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt
+    My hovercraft is full of eels!
+
+But say we only want the first 13 bytes:
+
+.. code-block:: bash
+
+    shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt \
+                -H "Range: bytes=0-12"
+    My hovercraft
+
+HTTP supports many ways to specify single and even multiple byte
+ranges. Read all about it in `RFC 2616`_.
+
+.. note::
+   Databases that have been created with CouchDB 1.0.2 or earlier will
+   support range requests in |version|, but they are using a less-optimal
+   algorithm. If you plan to make heavy use of this feature, make sure
+   to compact your database with CouchDB |version| to take advantage of a
+   better algorithm to find byte ranges.
+
+.. _RFC 2616: http://tools.ietf.org/html/rfc2616#section-14.27
+
+
+.. _api/doc/attachment.put:
+
+``PUT /db/doc/attachment``
+==========================
+
+* **Method**: ``PUT /db/doc/attachment``
+* **Request**: Raw document data
+* **Response**: JSON document status
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+  * **Argument**: rev
+
+    * **Description**:  Current document revision
+    * **Optional**: no
+    * **Type**: string
+
+* **HTTP Headers**
+
+  * **Header**: ``Content-Length``
+
+    * **Description**: Length (bytes) of the attachment being uploaded
+    * **Optional**: no
+
+  * **Header**: ``Content-Type``
+
+    * **Description**: MIME type for the uploaded attachment
+    * **Optional**: no
+
+  * **Header**: ``If-Match``
+
+    * **Description**: Current revision of the document for validation
+    * **Optional**: yes
+
+* **Return Codes**:
+
+  * **201**:
+    Attachment has been accepted
+
+Upload the supplied content as an attachment to the specified document
+(``doc``). The ``attachment`` name provided must be a URL encoded
+string. You must also supply either the ``rev`` query argument or the
+``If-Match`` HTTP header for validation, and the HTTP headers (to set
+the attachment content type). The content type is used when the
+attachment is requested as the corresponding content-type in the
+returned document header.
+
+For example, you could upload a simple text document using the following
+request:
+
+.. code-block:: http
+
+    PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca
+    Content-Length: 10
+    Content-Type: text/plain
+
+    Roast it
+
+Or by using the ``If-Match`` HTTP header:
+
+.. code-block:: http
+
+    PUT http://couchdb:5984/recipes/FishStew/basic
+    If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca
+    Content-Length: 10
+    Content-Type: text/plain
+
+    Roast it
+
+The returned JSON contains the new document information:
+
+.. code-block:: javascript
+
+    {
+       "id" : "FishStew",
+       "ok" : true,
+       "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74"
+    }
+
+.. note:: Uploading an attachment updates the corresponding document revision.
+   Revisions are tracked for the parent document, not individual
+   attachments.
+
+Updating an Existing Attachment
+-------------------------------
+
+Uploading an attachment using an existing attachment name will update
+the corresponding stored content of the database. Since you must supply
+the revision information to add an attachment to a document, this serves
+as validation to update the existing attachment.
+
+.. _api/doc/attachment.delete:
+
+``DELETE /db/doc/attachment``
+=============================
+
+* **Method**: ``DELETE /db/doc/attachment``
+* **Request**: None
+* **Response**: JSON status
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+  * **Argument**: rev
+
+    * **Description**:  Current document revision
+    * **Optional**: no
+    * **Type**: string
+
+* **HTTP Headers**
+
+  * **Header**: ``If-Match``
+
+    * **Description**: Current revision of the document for validation
+    * **Optional**: yes
+
+* **Return Codes**:
+
+  * **200**:
+    Attachment deleted successfully
+  * **409**:
+    Supplied revision is incorrect or missing
+
+Deletes the attachment ``attachment`` to the specified ``doc``. You must
+supply the ``rev`` argument with the current revision to delete the
+attachment.
+
+For example to delete the attachment ``basic`` from the recipe
+``FishStew``:
+
+.. code-block:: http
+
+    DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74
+    Content-Type: application/json
+
+
+
+The returned JSON contains the updated revision information:
+
+.. code-block:: javascript
+
+    {
+       "id" : "FishStew",
+       "ok" : true,
+       "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e"
+    }
+
+.. _JSON object: #table-couchdb-api-db_db-json-changes
+.. _POST: #couchdb-api-dbdoc_db_post


Mime
View raw message