couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j..@apache.org
Subject [24/50] [abbrv] import Couchbase docs
Date Thu, 06 Dec 2012 11:34:41 GMT
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fd643691/share/docs/couchdb-manual-1.1/couchdb-api-dbdoc-metasrc.xml
----------------------------------------------------------------------
diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-dbdoc-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-dbdoc-metasrc.xml
new file mode 100644
index 0000000..7b68006
--- /dev/null
+++ b/share/docs/couchdb-manual-1.1/couchdb-api-dbdoc-metasrc.xml
@@ -0,0 +1,1016 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
+                         'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
+<!ENTITY % every.entities SYSTEM "entities.ent">
+%every.entities;
+]>
+<chapter id="couchdb-api-dbdoc">
+
+  <title>CouchDB API Server Document Methods</title>
+
+  <para>
+    The CouchDB API Server Document methods detail how to create, read,
+    update and delete documents within a database.
+  </para>
+
+  <para>
+    A list of the available methods and URL paths are provided below:
+  </para>
+
+  <para role="meta" id="table-couchdb-api-dbdoc-summary">
+    <remark role="title">Document API Calls</remark>
+
+    <remark role="type" condition="urlapi"/>
+
+    <remark role="src" condition="couchdb"/>
+
+    <remark role="output" condition="summarytable"/>
+
+    <remark role="filter_class" condition="dbdoc"/>
+
+    <remark role="version" condition="inherit"/>
+
+    <remark role="idprefix" condition="couchdb-api-dbdoc"/>
+  </para>
+
+  <section id="couchdb-api-dbdoc_db_post">
+
+    <title><literal>POST /db</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="dbdoc"/>
+
+      <remark role="method" condition="POST"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Create a new document in the specified database, using the
+      supplied JSON document structure. If the JSON structure includes
+      the <literal>_id</literal> field, then the document will be
+      created with the specified document ID. If the
+      <literal>_id</literal> field is not specified, a new unique ID
+      will be generated.
+    </para>
+
+    <para>
+      For example, you can generate a new document with a generated UUID
+      using the following request:
+    </para>
+
+<programlisting>
+POST http://couchdb:5984/recipes/
+Content-Type: application/json
+
+{
+   "servings" : 4,
+   "subtitle" : "Delicious with fresh bread",
+   "title" : "Fish Stew"
+}
+</programlisting>
+
+    <para>
+      The return JSON will specify the automatically enerated ID and
+      revision information:
+    </para>
+
+<programlisting>
+{
+   "id" : "64575eef70ab90a2b8d55fc09e00440d",
+   "ok" : true,
+   "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+}
+</programlisting>
+
+    <section id="couchdb-api-dbdoc_db_post-docid">
+
+      <title>Specifying the Document ID</title>
+
+      <para>
+        The document ID can be specified by including the
+        <literal>_id</literal> field in the JSON of the submitted
+        record. The following request will create the same document with
+        the ID <literal>FishStew</literal>:
+      </para>
+
+<programlisting>
+POST http://couchdb:5984/recipes/
+Content-Type: application/json
+
+{
+   "_id" : "FishStew",
+   "servings" : 4,
+   "subtitle" : "Delicious with fresh bread",
+   "title" : "Fish Stew"
+}
+</programlisting>
+
+      <para>
+        The structure of the submitted document is as shown in the table
+        below:
+      </para>
+
+      <para role="meta" id="table-couchdb-api-json-document">
+        <remark role="type" condition="json"/>
+
+        <remark role="src" condition="json"/>
+
+        <remark role="output" condition="itemtable"/>
+
+        <remark role="itemid" condition="document"/>
+
+        <remark role="version" condition="inherit"/>
+      </para>
+
+      <para>
+        In either case, the returned JSON will specify the document ID,
+        revision ID, and status message:
+      </para>
+
+<programlisting>
+{
+   "id" : "FishStew",
+   "ok" : true,
+   "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+}
+    </programlisting>
+
+    </section>
+
+    <section id="couchdb-api-dbdoc_db_batchmode">
+
+      <title>Batch Mode Writes</title>
+
+      <para>
+        You can write documents to the database at a higher rate by
+        using the batch option. This collects document writes together
+        in memory (on a user-by-user basis) before they are committed to
+        disk. This increases the risk of the documents not being stored
+        in the event of a failure, since the documents are not written
+        to disk immediately.
+      </para>
+
+      <para>
+        To use the batched mode, append the <literal>batch=ok</literal>
+        query argument to the URL of the <literal>PUT</literal> or
+        <literal>POST</literal> request. The CouchDB server will respond
+        with a 202 HTTP response code immediately.
+      </para>
+
+    </section>
+
+    <section id="couchdb-api-dbdoc_db-doc-attachments">
+
+      <title>Including Attachments</title>
+
+      <para>
+        You can include one or more attachments with a given document by
+        incorporating the attachment information within the JSON of the
+        document. This provides a simpler alternative to loading
+        documents with attachments than making a separate call (see
+        <xref
+        linkend="couchdb-api-dbdoc_db-doc-attachment_put"/>).
+      </para>
+
+      <para role="meta" id="table-couchdb-api-dbdoc-documentattachments">
+        <remark role="type" condition="json"/>
+
+        <remark role="src" condition="json"/>
+
+        <remark role="output" condition="itemtable"/>
+
+        <remark role="itemid" condition="document_with_attachments"/>
+
+        <remark role="version" condition="inherit"/>
+      </para>
+
+      <para>
+        The <literal>filename</literal> will be the attachment name. For
+        example, when sending the JSON structure below:
+      </para>
+
+<programlisting>
+{
+   "_id" : "FishStew",
+   "servings" : 4,
+   "subtitle" : "Delicious with fresh bread",
+   "title" : "Fish Stew"
+   "_attachments" : {
+      "styling.css" : {
+         "content-type" : "text/css",
+         "data" : "cCB7IGZvbnQtc2l6ZTogMTJwdDsgfQo=",
+         },
+   },
+}
+    </programlisting>
+
+      <para>
+        The attachment <literal>styling.css</literal> can be accessed
+        using <literal>/recipes/FishStew/styling.css</literal>. For more
+        information on attachments, see
+        <xref
+        linkend="couchdb-api-dbdoc_db-doc-attachment_get"/>.
+      </para>
+
+      <para>
+        The document data embedded in to the structure must be encoded
+        using base64.
+      </para>
+
+    </section>
+
+  </section>
+
+  <section id="couchdb-api-dbdoc_db-doc_get">
+
+    <title><literal>GET /db/doc</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-doc"/>
+
+      <remark role="method" condition="GET"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Returns the specified <literal>doc</literal> from the specified
+      <literal>db</literal>. For example, to retrieve the document with
+      the id <literal>FishStew</literal> you would send the following
+      request:
+    </para>
+
+<programlisting>
+GET http://couchdb:5984/recipes/FishStew
+Content-Type: application/json
+Accept: application/json
+</programlisting>
+
+    <para>
+      The returned JSON is the JSON of the document, including the
+      document ID and revision number:
+    </para>
+
+<programlisting>
+{
+   "_id" : "FishStew",
+   "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c",
+   "servings" : 4,
+   "subtitle" : "Delicious with a green salad",
+   "title" : "Irish Fish Stew"
+}
+    </programlisting>
+
+    <para>
+      Unless you request a specific revision, the latest revision of the
+      document will always be returned.
+    </para>
+
+    <section id="couchdb-api-dbdoc_db-doc_get-attachments">
+
+      <title>Attachments</title>
+
+      <para>
+        If the document includes attachments, then the returned
+        structure will contain a summary of the attachments associatd
+        with the document, but not the attachment data itself.
+      </para>
+
+      <para>
+        The JSON for the returned document will include the
+        <literal>_attachments</literal> field, with one or more
+        attachment definitions. For example:
+      </para>
+
+<programlisting>
+{
+   "_id" : "FishStew",
+   "servings" : 4,
+   "subtitle" : "Delicious with fresh bread",
+   "title" : "Fish Stew"
+   "_attachments" : {
+      "styling.css" : {
+         "stub" : true,
+         "content-type" : "text/css",
+         "length" : 783426,
+         },
+   },
+}
+</programlisting>
+
+      <para>
+        The format of the returned JSON is shown in the table below:
+      </para>
+
+      <para role="meta" id="table-couchdb-api-dbdoc-returneddocumentattachments">
+        <remark role="type" condition="json"/>
+
+        <remark role="src" condition="json"/>
+
+        <remark role="output" condition="itemtable"/>
+
+        <remark role="itemid" condition="returneddocument_with_attachments"/>
+
+        <remark role="version" condition="inherit"/>
+      </para>
+
+    </section>
+
+    <section id="couchdb-api-dbdoc_db-doc_get-revs">
+
+      <title>Getting a List of Revisions</title>
+
+      <para>
+        You can obtain a list of the revisions for a given document by
+        adding the <literal>revs=true</literal> parameter to the request
+        URL. For example:
+      </para>
+
+<programlisting>
+GET http://couchdb:5984/recipes/FishStew?revs=true
+Accept: application/json
+</programlisting>
+
+      <para>
+        The returned JSON structure includes the original document,
+        including a <literal>_revisions</literal> structure that
+        includes the revision information:
+      </para>
+
+<programlisting>
+{
+   "servings" : 4,
+   "subtitle" : "Delicious with a green salad",
+   "_id" : "FishStew",
+   "title" : "Irish Fish Stew",
+   "_revisions" : {
+      "ids" : [
+         "a1a9b39ee3cc39181b796a69cb48521c",
+         "7c4740b4dcf26683e941d6641c00c39d",
+         "9c65296036141e575d32ba9c034dd3ee"
+      ],
+      "start" : 3
+   },
+   "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
+}
+</programlisting>
+
+      <para role="meta" id="table-couchdb-api-dbdoc-document_with_revs">
+        <remark role="type" condition="json"/>
+
+        <remark role="src" condition="json"/>
+
+        <remark role="output" condition="itemtable"/>
+
+        <remark role="itemid" condition="document_with_revs"/>
+
+        <remark role="version" condition="inherit"/>
+      </para>
+
+    </section>
+
+    <section id="couchdb-api-dbdoc_db-doc_get-revsextended">
+
+      <title>Obtaining an Extended Revision History</title>
+
+      <para>
+        You can get additional information about the revisions for a
+        given document by supplying the <literal>revs_info</literal>
+        argument to the query:
+      </para>
+
+<programlisting>
+GET http://couchdb:5984/recipes/FishStew?revs_info=true
+Accept: application/json
+</programlisting>
+
+      <para>
+        This returns extended revision information, including the
+        availability and status of each revision:
+      </para>
+
+<programlisting>
+{
+   "servings" : 4,
+   "subtitle" : "Delicious with a green salad",
+   "_id" : "FishStew",
+   "_revs_info" : [
+      {
+         "status" : "available",
+         "rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
+      },
+      {
+         "status" : "available",
+         "rev" : "2-7c4740b4dcf26683e941d6641c00c39d"
+      },
+      {
+         "status" : "available",
+         "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+      }
+   ],
+   "title" : "Irish Fish Stew",
+   "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
+}
+</programlisting>
+
+      <para role="meta" id="table-couchdb-api-dbdoc-document_with_revs_info">
+        <remark role="type" condition="json"/>
+
+        <remark role="src" condition="json"/>
+
+        <remark role="output" condition="itemtable"/>
+
+        <remark role="itemid" condition="document_with_revs_info"/>
+
+        <remark role="version" condition="inherit"/>
+      </para>
+
+    </section>
+
+    <section id="couchdb-api-dbdoc_db-doc_get-specrev">
+
+      <title>Obtaining a Specific Revision</title>
+
+      <para>
+        To get a specific revision, use the <literal>rev</literal>
+        argument to the request, and specify the full revision number:
+      </para>
+
+<programlisting>
+GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d
+Accept: application/json
+</programlisting>
+
+      <para>
+        The specified revision of the document will be returned,
+        including a <literal>_rev</literal> field specifying the
+        revision that was requested:
+      </para>
+
+<programlisting>
+{
+   "_id" : "FishStew",
+   "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d",
+   "servings" : 4,
+   "subtitle" : "Delicious with a green salad",
+   "title" : "Fish Stew"
+}
+</programlisting>
+
+    </section>
+
+  </section>
+
+  <section id="couchdb-api-dbdoc_db-doc_head">
+
+    <title><literal>HEAD /db/doc</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-doc"/>
+
+      <remark role="method" condition="HEAD"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Returns the HTTP Headers containing a minimal amount of
+      information about the specified document. The method supports the
+      same query arguments as the <literal>GET</literal> method, but
+      only the header information (including document size, and the
+      revision as an ETag), is returned. For example, a simple
+      <literal>HEAD</literal> request:
+    </para>
+
+<programlisting>
+HEAD http://couchdb:5984/recipes/FishStew
+Content-Type: application/json
+    </programlisting>
+
+    <para>
+      Returns the following HTTP Headers:
+    </para>
+
+<programlisting>
+HTTP/1.1 200 OK
+Server: CouchDB/1.0.1 (Erlang OTP/R13B)
+Etag: "7-a19a1a5ecd946dad70e85233ba039ab2"
+Date: Fri, 05 Nov 2010 14:54:43 GMT
+Content-Type: text/plain;charset=utf-8
+Content-Length: 136
+Cache-Control: must-revalidate
+</programlisting>
+
+    <para>
+      The <literal>Etag</literal> header shows the current revision for
+      the requested document, and the <literal>Content-Length</literal>
+      specifies the length of the data, if the document were requested
+      in full.
+    </para>
+
+    <para>
+      Adding any of the query arguments (as supported by
+      <link linkend="couchdb-api-dbdoc_db-doc_get"><literal>GET</literal></link>
+      method), then the resulting HTTP Headers will correspond to what
+      would be returned. Note that the current revision is not returned
+      when the <literal>refs_info</literal> argument is used. For
+      example:
+    </para>
+
+<programlisting>
+HTTP/1.1 200 OK
+Server: CouchDB/1.0.1 (Erlang OTP/R13B)
+Date: Fri, 05 Nov 2010 14:57:16 GMT
+Content-Type: text/plain;charset=utf-8
+Content-Length: 609
+Cache-Control: must-revalidate
+</programlisting>
+
+  </section>
+
+  <section id="couchdb-api-dbdoc_db-doc_put">
+
+    <title><literal>PUT /db/doc</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-doc"/>
+
+      <remark role="method" condition="PUT"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      The <literal>PUT</literal> method creates a new named document, or
+      creates a new revision of the existing document. Unlike the
+      <link linkend="couchdb-api-dbdoc_db_post"><literal>POST</literal></link>
+      method, you must specify the document ID in the request URL.
+    </para>
+
+    <para>
+      For example, to create the docment <literal>FishStew</literal>,
+      you would send the following request:
+    </para>
+
+<programlisting>PUT http://couchdb:5984/recipes/FishStew
+Content-Type: application/json
+
+{
+  "servings" : 4,
+  "subtitle" : "Delicious with fresh bread",
+  "title" : "Fish Stew"
+}
+</programlisting>
+
+    <para>
+      The return type is JSON of the status, document ID,and revision
+      number:
+    </para>
+
+<programlisting>
+{
+   "id" : "FishStew",
+   "ok" : true,
+   "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+}
+</programlisting>
+
+    <section id="couchdb-api-dbdoc_db-doc_put-update">
+
+      <title>Updating an Existing Document</title>
+
+      <para>
+        To update an existing document you must specify the current
+        revision number within the <literal>_rev</literal> parameter.
+        For example:
+      </para>
+
+<programlisting>
+PUT http://couchdb:5984/recipes/FishStew
+Content-Type: application/json
+
+{
+  "_rev" : "1-9c65296036141e575d32ba9c034dd3ee",
+  "servings" : 4,
+  "subtitle" : "Delicious with fresh salad",
+  "title" : "Fish Stew"
+}
+</programlisting>
+
+      <para>
+        Alternatively, you can supply the current revision number in the
+        <literal>If-Match</literal> HTTP header of the request. For
+        example:
+      </para>
+
+<programlisting>
+PUT http://couchdb:5984/recipes/FishStew
+If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea
+Content-Type: application/json
+
+{
+   "servings" : 4,
+   "subtitle" : "Delicious with fresh salad",
+   "title" : "Fish Stew"
+}
+</programlisting>
+
+      <para>
+        The JSON returned will include the updated revision number:
+      </para>
+
+<programlisting>
+{
+   "id" : "FishStew99",
+   "ok" : true,
+   "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea"
+}
+</programlisting>
+
+      <para>
+        For information on batched writes, which can provide improved
+        performance, see
+        <xref linkend="couchdb-api-dbdoc_db_batchmode"/>.
+      </para>
+
+    </section>
+
+  </section>
+
+  <section id="couchdb-api-dbdoc_db-doc_delete">
+
+    <title><literal>DELETE /db/doc</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-doc"/>
+
+      <remark role="method" condition="DELETE"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Deletes the specified document from the database. You must supply
+      the current (latest) revision, either by using the
+      <literal>rev</literal> parameter to specify the revision:
+    </para>
+
+<programlisting>
+DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c
+Content-Type: application/json
+</programlisting>
+
+    <para>
+      Alternatively, you can use ETags with the
+      <literal>If-Match</literal> field:
+    </para>
+
+<programlisting>
+DELETE http://couchdb:5984/recipes/FishStew
+If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c
+Content-Type: application/json
+    </programlisting>
+
+    <para>
+      The returned JSON contains the document ID, revision and status:
+    </para>
+
+<programlisting>
+{
+   "id" : "FishStew",
+   "ok" : true,
+   "rev" : "4-2719fd41187c60762ff584761b714cfb"
+}
+</programlisting>
+
+    <note>
+      <para>
+        Note that deletion of a record increments the revision number.
+        The use of a revision for deletion of the record allows
+        replication of the database to correctly track the deletion in
+        synchronized copies.
+      </para>
+    </note>
+
+  </section>
+
+  <section id="couchdb-api-dbdoc_db-doc_copy">
+
+    <title><literal>COPY /db/doc</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-doc"/>
+
+      <remark role="method" condition="COPY"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      The <literal>COPY</literal> command (which is non-standard HTTP)
+      copies an existing document to a new or existing document.
+    </para>
+
+    <para>
+      The source document is specified on the request line, with the
+      <literal>Destination</literal> HTTP Header of the request
+      specifying the target document.
+    </para>
+
+    <section id="couchdb-api-dbdoc_db-doc_copy-simple">
+
+      <title>Copying a Document</title>
+
+      <para>
+        You can copy the latest version of a document to a new document
+        by specifying the current document and target document:
+      </para>
+
+<programlisting>
+COPY http://couchdb:5984/recipes/FishStew
+Content-Type: application/json
+Destination: IrishFishStew
+</programlisting>
+
+      <para>
+        The above request copies the document
+        <literal>FishStew</literal> to the new document
+        <literal>IrishFishStew</literal>. The response is the ID and
+        revision of the new document.
+      </para>
+
+<programlisting>
+{
+   "id" : "IrishFishStew",
+   "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+}
+</programlisting>
+
+    </section>
+
+    <section id="couchdb-api-dbdoc_db-doc_copy-specrev">
+
+      <title>Copying from a Specific Revision</title>
+
+      <para>
+        To copy <emphasis>from</emphasis> a specific version, use the
+        <literal>rev</literal> argument to the query string:
+      </para>
+
+<programlisting>
+COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082
+Content-Type: application/json
+Destination: IrishFishStew
+</programlisting>
+
+      <para>
+        The new document will be created using the information in the
+        specified revision of the source document.
+      </para>
+
+    </section>
+
+    <section id="couchdb-api-dbdoc_db-doc_copy-existing">
+
+      <title>Copying to an Existing Document</title>
+
+      <para>
+        To copy to an existing document, you must specify the current
+        revision string for the target document, using the
+        <literal>rev</literal> parameter to the
+        <literal>Destination</literal> HTTP Header string. For example:
+      </para>
+
+<programlisting>
+COPY http://couchdb:5984/recipes/FishStew
+Content-Type: application/json
+Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee
+</programlisting>
+
+      <para>
+        The return value will be the new revision of the copied
+        document:
+      </para>
+
+<programlisting>
+{
+   "id" : "IrishFishStew",
+   "rev" : "2-55b6a1b251902a2c249b667dab1c6692"
+}
+</programlisting>
+
+    </section>
+
+  </section>
+
+  <section id="couchdb-api-dbdoc_db-doc-attachment_get">
+
+    <title><literal>GET /db/doc/attachment</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-doc-attachment"/>
+
+      <remark role="method" condition="GET"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Returns the file attachment <literal>attachment</literal>
+      associated with the document <literal>doc</literal>. The raw data
+      of the associated attachment is returned (just as if you were
+      accessing a static file. The returned HTTP
+      <literal>Content-type</literal> will be the same as the content
+      type set when the document attachment was submitted into the
+      database.
+    </para>
+
+  </section>
+
+  <section id="couchdb-api-dbdoc_db-doc-attachment_put">
+
+    <title><literal>PUT /db/doc/attachment</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-doc-attachment"/>
+
+      <remark role="method" condition="PUT"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Upload the supplied content as an attachment to the specified
+      document (<literal>doc</literal>). The
+      <literal>attachment</literal> name provided must be a URL encoded
+      string. You must also supply either the <literal>rev</literal>
+      query argument or the <literal>If-Match</literal> HTTP header for
+      validation, and the HTTP headers (to set the attacment content
+      type). The content type is used when the attachment is requested
+      as the corresponding content-type in the returned document header.
+    </para>
+
+    <para>
+      For example, you could upload a simple text document using the
+      following request:
+    </para>
+
+<programlisting>
+PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca
+Content-Length: 10
+Content-Type: text/plain
+
+Roast it
+
+</programlisting>
+
+    <para>
+      Or by using the <literal>If-Match</literal> HTTP header:
+    </para>
+
+<programlisting>
+PUT http://couchdb:5984/recipes/FishStew/basic
+If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca
+Content-Length: 10
+Content-Type: text/plain
+
+Roast it
+
+</programlisting>
+
+    <para>
+      The returned JSON contains the new document information:
+    </para>
+
+<programlisting>
+{
+   "id" : "FishStew",
+   "ok" : true,
+   "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74"
+}
+</programlisting>
+
+    <note>
+      <para>
+        Uploading an attachment updates the corresponding document
+        revision. Revisions are tracked for the parent document, not
+        individual attachments.
+      </para>
+    </note>
+
+    <section id="couchdb-api-dbdoc_db-doc-attachment_put-existing">
+
+      <title>Updating an Existing Attachment</title>
+
+      <para>
+        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.
+      </para>
+
+    </section>
+
+  </section>
+
+  <section id="couchdb-api-dbdoc_db-doc-attachment_delete">
+
+    <title><literal>DELETE /db/doc/attachment</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-doc-attachment"/>
+
+      <remark role="method" condition="DELETE"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Deletes the attachment <literal>attachment</literal> to the
+      specified <literal>doc</literal>. You must supply the
+      <literal>rev</literal> argument with the current revision to
+      delete the attachment.
+    </para>
+
+    <para>
+      For example to delete the attachment <literal>basic</literal> from
+      the recipe <literal>FishStew</literal>:
+    </para>
+
+<programlisting>
+DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74
+Content-Type: application/json
+
+    </programlisting>
+
+    <para>
+      The returned JSON contains the updated revision information:
+    </para>
+
+<programlisting>
+{
+   "id" : "FishStew",
+   "ok" : true,
+   "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e"
+}
+</programlisting>
+
+  </section>
+
+</chapter>

http://git-wip-us.apache.org/repos/asf/couchdb/blob/fd643691/share/docs/couchdb-manual-1.1/couchdb-api-design-metasrc.xml
----------------------------------------------------------------------
diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-design-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-design-metasrc.xml
new file mode 100644
index 0000000..f4edf75
--- /dev/null
+++ b/share/docs/couchdb-manual-1.1/couchdb-api-design-metasrc.xml
@@ -0,0 +1,1462 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
+                         'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
+<!ENTITY % every.entities SYSTEM "entities.ent">
+%every.entities;
+]>
+<chapter id="couchdb-api-design">
+
+  <title>CouchDB API Server Design Document Methods</title>
+
+  <para>
+    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.
+  </para>
+
+  <para>
+    Views and lists operate together to provide automated (and
+    formatted) output from your database.
+  </para>
+
+  <para>
+    A list of the available methods and URL paths are provided below:
+  </para>
+
+  <para role="meta" id="table-couchdb-api-design-summary">
+    <remark role="title">Design Document API Calls</remark>
+
+    <remark role="type" condition="urlapi"/>
+
+    <remark role="src" condition="couchdb"/>
+
+    <remark role="output" condition="summarytable"/>
+
+    <remark role="filter_class" condition="design"/>
+
+    <remark role="version" condition="inherit"/>
+
+    <remark role="idprefix" condition="couchdb-api-design"/>
+  </para>
+
+  <section id="couchdb-api-design_db-design-designdoc_get">
+
+    <title><literal>GET /db/_design/design-doc</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc"/>
+
+      <remark role="method" condition="GET"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Returns the specified design document,
+      <literal>design-doc</literal> from the specified
+      <literal>db</literal>. For example, to retrieve the design
+      document <literal>recipes</literal> you would send the following
+      request:
+    </para>
+
+<programlisting>
+GET http://couchdb:5984/recipes/_design/recipes
+Content-Type: application/json
+</programlisting>
+
+    <para>
+      The returned string will be the JSON of the design document:
+    </para>
+
+<programlisting>
+{
+   "_id" : "_design/recipes",
+   "_rev" : "5-39f56a392b86bbee57e2138921346406"
+   "language" : "javascript",
+   "views" : {
+      "by_recipe" : {
+         "map" : "function(doc) { if (doc.title != null) emit(doc.title, doc) }"
+      },
+   },
+}
+</programlisting>
+
+    <para>
+      A list of the revisions can be obtained by using the
+      <literal>revs</literal> query argument, or an extended list of
+      revisions using the <literal>revs_info</literal> query argument.
+      This operates in the same way as for other documents. Fur further
+      examples, see
+      <xref
+        linkend="couchdb-api-dbdoc_db-doc_get"/>.
+    </para>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc_put">
+
+    <title><literal>PUT /db/_design/design-doc</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc"/>
+
+      <remark role="method" condition="PUT"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Upload the specified design document,
+      <literal>design-doc</literal>, to the specified database. The
+      design document should follow the definition of a design document,
+      as summarised in the following table.
+    </para>
+
+    <para role="meta" id="table-couchdb-api-json-designdoc">
+      <remark role="type" condition="json"/>
+
+      <remark role="src" condition="json"/>
+
+      <remark role="output" condition="itemtable"/>
+
+      <remark role="itemid" condition="design-doc"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      For more information on writing views, see
+      <xref
+      linkend="couchdb-api-functional-views"/>.
+    </para>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc_delete">
+
+    <title><literal>DELETE /db/_design/design-doc</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc"/>
+
+      <remark role="method" condition="DELETE"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      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.
+    </para>
+
+    <para>
+      To delete, you must specify the current revision of the design
+      document using the <literal>rev</literal> query argument.
+    </para>
+
+    <para>
+      For example:
+    </para>
+
+<programlisting>
+DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8
+Content-Type: application/json
+</programlisting>
+
+    <para>
+      The response contains the delete document ID and revision:
+    </para>
+
+<programlisting>
+{
+   "id" : "recipe/_design/recipes"
+   "ok" : true,
+   "rev" : "3-7a05370bff53186cb5d403f861aca154",
+}
+</programlisting>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc_copy">
+
+    <title><literal>COPY /db/_design/design-doc</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc"/>
+
+      <remark role="method" condition="COPY"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      The <literal>COPY</literal> command (non-standard HTTP) copies an
+      existing design document to a new or existing document.
+    </para>
+
+    <para>
+      The source design document is specified on the request line, with
+      the <literal>Destination</literal> HTTP Header of the request
+      specifying the target document.
+    </para>
+
+    <section id="couchdb-api-design_db-design-designdoc_copy-simple">
+
+      <title>Copying a Design Document</title>
+
+      <para>
+        To copy the latest version of a design document to a new
+        document you specify the base document and target document:
+      </para>
+
+<programlisting>
+COPY http://couchdb:5984/recipes/_design/recipes
+Content-Type: application/json
+Destination: /recipes/_design/recipelist
+</programlisting>
+
+      <para>
+        The above request copies the design document
+        <literal>recipes</literal> to the new design document
+        <literal>recipelist</literal>. The response is the ID and
+        revision of the new document.
+      </para>
+
+<programlisting>
+{
+   "id" : "recipes/_design/recipelist"
+   "rev" : "1-9c65296036141e575d32ba9c034dd3ee",
+}
+</programlisting>
+
+      <note>
+        <para>
+          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.
+        </para>
+      </note>
+
+    </section>
+
+    <section id="couchdb-api-design_db-design-designdoc_copy-specrev">
+
+      <title>Copying from a Specific Revision</title>
+
+      <para>
+        To copy <emphasis>from</emphasis> a specific version, use the
+        <literal>rev</literal> argument to the query string:
+      </para>
+
+<programlisting>
+COPY http://couchdb:5984/recipes/_design/recipes?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5
+Content-Type: application/json
+Destination: recipes/_design/recipelist
+</programlisting>
+
+      <para>
+        The new design document will be created using the specified
+        revision of the source document.
+      </para>
+
+    </section>
+
+    <section id="couchdb-api-design_db-design-designdoc_copy-existing">
+
+      <title>Copying to an Existing Design Document</title>
+
+      <para>
+        To copy to an existing document, you must specify the current
+        revision string for the target document, using the
+        <literal>rev</literal> parameter to the
+        <literal>Destination</literal> HTTP Header string. For example:
+      </para>
+
+<programlisting>
+COPY http://couchdb:5984/recipes/_design/recipes
+Content-Type: application/json
+Destination: recipes/_design/recipelist?rev=1-9c65296036141e575d32ba9c034dd3ee
+</programlisting>
+
+      <para>
+        The return value will be the new revision of the copied
+        document:
+      </para>
+
+<programlisting>
+{
+   "id" : "recipes/_design/recipes"
+   "rev" : "2-55b6a1b251902a2c249b667dab1c6692",
+}
+</programlisting>
+
+    </section>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-attachment_get">
+
+    <title><literal>GET /db/_design/design-doc/attachment</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-attachment"/>
+
+      <remark role="method" condition="GET"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Returns the file attachment <literal>attachment</literal>
+      associated with the design document
+      <literal>/_design_/design-doc</literal>. The raw data of the
+      associated attachment is returned (just as if you were accessing a
+      static file. The returned HTTP <literal>Content-type</literal>
+      will be the same as the content type set when the document
+      attachment was submitted into the database.
+    </para>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-attachment_put">
+
+    <title><literal>PUT /db/_design/design-doc/attachment</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-attachment"/>
+
+      <remark role="method" condition="PUT"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Upload the supplied content as an attachment to the specified
+      design document (<literal>/_design/design-doc</literal>). The
+      <literal>attachment</literal> name provided must be a URL encoded
+      string. You must also supply either the <literal>rev</literal>
+      query argument or the <literal>If-Match</literal> HTTP header for
+      validation, and the HTTP headers (to set the attacment content
+      type). The content type is used when the attachment is requested
+      as the corresponding content-type in the returned document header.
+    </para>
+
+    <para>
+      For example, you could upload a simple text document using the
+      following request:
+    </para>
+
+<programlisting>
+PUT http://couchdb:5984/recipes/_design/recipes/view.css?rev=7-f7114d4d81124b223283f3e89eee043e
+Content-Length: 39
+Content-Type: text/plain
+
+div.recipetitle {
+font-weight: bold;
+}
+
+</programlisting>
+
+    <para>
+      Or by using the <literal>If-Match</literal> HTTP header:
+    </para>
+
+<programlisting>
+PUT http://couchdb:5984/recipes/FishStew/basic
+If-Match: 7-f7114d4d81124b223283f3e89eee043e
+Content-Length: 39
+Content-Type: text/plain
+
+div.recipetitle {
+font-weight: bold;
+}
+
+</programlisting>
+
+    <para>
+      The returned JSON contains the new document information:
+    </para>
+
+<programlisting>
+{
+   "id" : "_design/recipes"
+   "ok" : true,
+   "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5",
+}
+</programlisting>
+
+    <note>
+      <para>
+        Uploading an attachment updates the corresponding document
+        revision. Revisions are tracked for the parent document, not
+        individual attachments.
+      </para>
+    </note>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-attachment_delete">
+
+    <title><literal>DELETE /db/_design/design-doc/attachment</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-attachment"/>
+
+      <remark role="method" condition="DELETE"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Deletes the attachment <literal>attachment</literal> to the
+      specified <literal>_design/design-doc</literal>. You must supply
+      the <literal>rev</literal> argument with the current revision to
+      delete the attachment.
+    </para>
+
+    <para>
+      For example to delete the attachment <literal>view.css</literal>
+      from the design document <literal>recipes</literal>:
+    </para>
+
+<programlisting>
+DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a
+    </programlisting>
+
+    <para>
+      The returned JSON contains the updated revision information for
+      the parent document:
+    </para>
+
+<programlisting>
+{
+   "id" : "_design/recipes"
+   "ok" : true,
+   "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c",
+}
+</programlisting>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-info_get">
+
+    <title><literal>GET /db/_design/design-doc/_info</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-info"/>
+
+      <remark role="method" condition="GET"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Obtains information about a given design document, including the
+      index, index size and current status of the design document and
+      associated index information.
+    </para>
+
+    <para>
+      For example, to get the information for the
+      <literal>recipes</literal> design document:
+    </para>
+
+<programlisting>
+GET http://couchdb:5984/recipes/_design/recipes/_info
+Content-Type: application/json
+</programlisting>
+
+    <para>
+      This returns the following JSON structure:
+    </para>
+
+<programlisting>
+{
+   "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
+   },
+}
+</programlisting>
+
+    <para>
+      The individual fields in the returned JSON structure are detailed
+      in
+      <xref linkend="table-couchdb-api-design_db-designdoc-info-json"/>.
+    </para>
+
+    <para role="meta" id="table-couchdb-api-design_db-designdoc-info-json">
+      <remark role="title">Design Document Info JSON Contents</remark>
+
+      <remark role="type" condition="json"/>
+
+      <remark role="src" condition="json"/>
+
+      <remark role="output" condition="itemtable"/>
+
+      <remark role="itemid" condition="design-doc_info"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-view-viewname_get">
+
+    <title><literal>GET /db/_design/design-doc/_view/view-name</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-view-viewname"/>
+
+      <remark role="method" condition="GET"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Executes the specified <literal>view-name</literal> from the
+      specified <literal>design-doc</literal> design document.
+    </para>
+
+    <section
+          id="couchdb-api-design_db-design-designdoc-view-viewname_get-indexes">
+
+      <title>Querying Views and Indexes</title>
+
+      <para>
+        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.
+      </para>
+
+      <para>
+        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.
+      </para>
+
+      <para>
+        View indexes are updated incrementally in the following
+        situations:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            A new document has been added to the database.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            A document has been deleted from the database.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            A document in the database has been updated.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        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.
+      </para>
+
+      <note>
+        <para>
+          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.
+        </para>
+      </note>
+
+      <para>
+        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:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            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.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            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.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Use the <literal>/db/_changes</literal> method to monitor
+            for changes to the database and then access the view to
+            force the corresponding view index to be updated. See
+            <xref
+              linkend="couchdb-api-db_db-changes_get"/>
+            for more information.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Use a monitor with the
+            <literal>update_notification</literal> 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
+            <xref
+                      linkend="couchdb-single-configuration-update_notification"/>.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        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.
+      </para>
+
+      <para>
+        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.
+      </para>
+
+      <para>
+        For example, to access the existing stale view
+        <literal>by_recipe</literal> in the <literal>recipes</literal>
+        design document:
+      </para>
+
+<programlisting>http://couchdb:5984/recipes/_design/recipes/_view/by_recipe?stale=ok</programlisting>
+
+      <para>
+        Accessing a stale view:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Does not trigger a rebuild of the view indexes, even if
+            there have been changes since the last access.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Returns the current version of the view index, if a current
+            version exists.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Returns an empty result set if the given view index does
+            exist.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        As an alternative, you use the <literal>update_after</literal>
+        value to the <option>stale</option> paramater. 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.
+      </para>
+
+      <para>
+        In addition to using stale views, you can also make use of the
+        <literal>update_seq</literal> 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
+        <xref linkend="couchdb-api-db_db_get"/>).
+      </para>
+
+    </section>
+
+    <section
+      id="couchdb-api-design_db-design-designdoc-view-viewname_get-sorting">
+
+      <title>Sorting Returned Rows</title>
+
+      <para>
+        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:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <literal>null</literal>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal>false</literal>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal>true</literal>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Numbers
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Text (case sensitive, lowercase first)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Arrays (according to the values of each element, in order)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Objects (according to the values of keys, in key order)
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+<!-- TODO: Point to the view definition docs for information on the collation
+    specification -->
+
+      <para>
+        You can reverse the order of the returned view information by
+        using the <literal>descending</literal> query value set to true.
+        For example, Retrieving the list of recipes using the
+        <literal>by_title</literal> (limited to 5 records) view:
+      </para>
+
+<programlisting>
+{
+   "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
+}
+</programlisting>
+
+      <para>
+        Requesting the same in descending order will reverse the entire
+        view content. For example the request
+      </para>
+
+<programlisting>
+GET http://couchdb:5984/recipes/_design/recipes/_view/by_title?limit=5&amp;descending=true
+Accept: application/json
+Content-Type: application/json</programlisting>
+
+      <para>
+        Returns the last 5 records from the view:
+      </para>
+
+<programlisting>
+{
+   "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
+}
+</programlisting>
+
+      <para>
+        The sorting direction is applied before the filtering applied
+        using the <literal>startkey</literal> and
+        <literal>endkey</literal> query arguments. For example the
+        following query:
+      </para>
+
+<programlisting>
+GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?startkey=%22carrots%22&amp;endkey=%22egg%22
+Accept: application/json
+Content-Type: application/json
+</programlisting>
+
+      <para>
+        Will operate correctly when listing all the matching entries
+        between <quote>carrots</quote> and <literal>egg</literal>. If
+        the order of output is reversed with the
+        <literal>descending</literal> query argument, the view request
+        will return no entries:
+      </para>
+
+<programlisting>
+GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&amp;startkey=%22carrots%22&amp;endkey=%22egg%22
+Accept: application/json
+Content-Type: application/json
+</programlisting>
+
+      <para>
+        The returned result is empty:
+      </para>
+
+<programlisting>
+{
+   "total_rows" : 26453,
+   "rows" : [],
+   "offset" : 21882
+}
+</programlisting>
+
+      <para>
+        The results will be empty because the entries in the view are
+        reversed before the key filter is applied, and therefore the
+        <literal>endkey</literal> of <quote>egg</quote> will be seen
+        before the <literal>startkey</literal> of
+        <quote>carrots</quote>, resulting in an empty list.
+      </para>
+
+      <para>
+        Instead, you should reverse the values supplied to the
+        <literal>startkey</literal> and <literal>endkey</literal>
+        parameters to match the descending sorting applied to the keys.
+        Changing the previous example to:
+      </para>
+
+<programlisting>
+GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&amp;startkey=%22egg%22&amp;endkey=%22carrots%22
+Accept: application/json
+Content-Type: application/json
+</programlisting>
+
+    </section>
+
+    <section id="couchdb-api-design_db-design-designdoc-view-viewname_get-ranges">
+
+      <title>Specifying Start and End Values</title>
+
+      <para>
+        The <literal>startkey</literal> and <literal>endkey</literal>
+        query arguments can be used to specify the range of values to be
+        displayed when querying the view.
+      </para>
+
+      <note>
+        <para>
+          The values
+        </para>
+      </note>
+
+    </section>
+
+    <section id="couchdb-api-design_db-design-designdoc-view-viewname_get-limit">
+
+      <title>Using Limits and Skipping Rows</title>
+
+      <para>
+        TBC
+      </para>
+
+    </section>
+
+    <section
+      id="couchdb-api-design_db-design-designdoc-view-viewname_get-reduction">
+
+      <title>View Reduction and Grouping</title>
+
+      <para>
+        TBC
+      </para>
+
+    </section>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-view-viewname_post">
+
+    <title><literal>POST /db/_design/design-doc/_view/view-name</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-view-viewname"/>
+
+      <remark role="method" condition="POST"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para>
+      Executes the specified <literal>view-name</literal> from the
+      specified <literal>design-doc</literal> design document. Unlike
+      the <literal>GET</literal> method for accessing views, the
+      <literal>POST</literal> method supports the specification of
+      explicit keys to be retrieved from the view results. The remainder
+      of the <literal>POST</literal> view functionality is identical to
+      the
+      <xref
+              linkend="couchdb-api-design_db-design-designdoc-view-viewname_get"/>
+      fun
+    </para>
+
+    <para>
+      For example, the request below will return all the recipes where
+      the key for the view matches either <quote>claret</quote> or
+      <quote>clear apple cider</quote> :
+    </para>
+
+<programlisting>
+POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient
+Content-Type: application/json
+
+{
+   "keys" : [
+      "claret",
+      "clear apple juice"
+   ]
+}
+      </programlisting>
+
+    <para>
+      The returned view data contains the standard view information, but
+      only where the keys match.
+    </para>
+
+<programlisting>
+{
+   "total_rows" : 26484,
+   "rows" : [
+      {
+         "value" : [
+            "Scotch collops"
+         ],
+         "id" : "Scotchcollops",
+         "key" : "claret"
+      },
+      {
+         "value" : [
+            "Stand pie"
+         ],
+         "id" : "Standpie",
+         "key" : "clear apple juice"
+      }
+   ],
+   "offset" : 6324
+}
+</programlisting>
+
+    <section
+          id="couchdb-api-design_db-design-designdoc-view-viewname_post-multidoc">
+
+      <title>Multi-document Fetching</title>
+
+      <para>
+        By combining the <literal>POST</literal> method to a given view
+        with the <literal>include_docs=true</literal> query argument you
+        can obtain multiple documents from a database. The result is
+        more efficient than using multiple
+        <xref
+              linkend="couchdb-api-dbdoc_db-doc_get"/>
+        requests.
+      </para>
+
+      <para>
+        For example, sending the following request for ingredients
+        matching <quote>claret</quote> and <quote>clear apple
+        juice</quote>:
+      </para>
+
+<programlisting>
+POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?include_docs=true
+Content-Type: application/json
+
+{
+   "keys" : [
+      "claret",
+      "clear apple juice"
+   ]
+}
+</programlisting>
+
+      <para>
+        Returns the full document for each recipe:
+      </para>
+
+<programlisting>
+{
+   "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
+}
+</programlisting>
+
+    </section>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-show-showname_get">
+
+    <title><literal>POST /db/_design/design-doc/_show/show-name</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-show-showname"/>
+
+      <remark role="method" condition="GET"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para></para>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-show-showname-doc_get">
+
+    <title><literal>POST /db/_design/design-doc/_show/show-name/doc</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-show-showname-doc"/>
+
+      <remark role="method" condition="GET"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+    <para></para>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-list-listname-otherdesigndoc-viewname_get">
+
+    <title><literal>GET
+      /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-list-listname-otherdesigndoc-viewname"/>
+
+      <remark role="method" condition="GET"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-list-listname-otherdesigndoc-viewname_post">
+
+    <title><literal>POST
+      /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-list-listname-otherdesigndoc-viewname"/>
+
+      <remark role="method" condition="POST"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-list-listname-viewname_get">
+
+    <title><literal>GET /db/_design/design-doc/_list/list-name/view-name</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-list-listname-viewname"/>
+
+      <remark role="method" condition="GET"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-list-listname-viewname_post">
+
+    <title><literal>POST /db/_design/design-doc/_list/list-name/view-name</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-list-listname-viewname"/>
+
+      <remark role="method" condition="POST"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+  </section>
+
+  <section id="couchdb-api-design_db-design-designdoc-update-updatename-doc_put">
+
+    <title><literal>PUT /db/_design/design-doc/_update/updatename/doc</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid"
+                condition="db-design-designdoc-update-updatename-doc"/>
+
+      <remark role="method" condition="PUT"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+  </section>
+
+  <section
+        id="couchdb-api-design_db-design-designdoc-update-updatename_post">
+
+    <title><literal>POST /db/_design/design-doc/_update/updatename</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid"
+                condition="db-design-designdoc-update-updatename"/>
+
+      <remark role="method" condition="POST"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+  </section>
+
+  <section
+        id="couchdb-api-design_db-design-designdoc-rewrite-rewritename-anything">
+
+    <title><literal>ALL
+      /db/_design/design-doc/_rewrite/rewrite-name/anything</literal></title>
+
+    <para role="meta">
+      <remark role="type" condition="urlapi"/>
+
+      <remark role="src" condition="couchdb"/>
+
+      <remark role="output" condition="accesstable"/>
+
+      <remark role="itemid" condition="db-design-designdoc-rewrite-rewritename-anything"/>
+
+      <remark role="method" condition="ALL"/>
+
+      <remark role="version" condition="inherit"/>
+    </para>
+
+  </section>
+
+</chapter>


Mime
View raw message