CouchDB API Server Document Methods

Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 38426 invoked by uid 99); 12 Dec 2012 20:34:00 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 12 Dec 2012 20:33:59 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id A0A3F81B9C3; Wed, 12 Dec 2012 20:33:59 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: dch@apache.org To: commits@couchdb.apache.org X-Mailer: ASF-Git Admin Mailer Subject: [23/34] import Couchbase docs Message-Id: <20121212203359.A0A3F81B9C3@tyr.zones.apache.org> Date: Wed, 12 Dec 2012 20:33:59 +0000 (UTC) http://git-wip-us.apache.org/repos/asf/couchdb/blob/749f8c8c/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 @@ + + +%every.entities; +]> + + + CouchDB API Server Document Methods + + + The CouchDB API Server Document methods detail how to create, read, + update and delete documents within a database. + + + + A list of the available methods and URL paths are provided below: + + + + Document API Calls + + + + + + + + + + + + + + +

+ + <literal>POST /db</literal> + + + + + + + + + + + + + + + + + Create a new document in the specified database, using the + supplied JSON document structure. If the JSON structure includes + the _id field, then the document will be + created with the specified document ID. If the + _id field is not specified, a new unique ID + will be generated. + + + + For example, you can generate a new document with a generated UUID + using the following request: + + + +POST http://couchdb:5984/recipes/ +Content-Type: application/json + +{ + "servings" : 4, + "subtitle" : "Delicious with fresh bread", + "title" : "Fish Stew" +} + + + + The return JSON will specify the automatically enerated ID and + revision information: + + + +{ + "id" : "64575eef70ab90a2b8d55fc09e00440d", + "ok" : true, + "rev" : "1-9c65296036141e575d32ba9c034dd3ee" +} + + +

+ + Specifying the Document ID + + + The document ID can be specified by including the + _id field in the JSON of the submitted + record. The following request will create the same document with + the ID FishStew: + + + +POST http://couchdb:5984/recipes/ +Content-Type: application/json + +{ + "_id" : "FishStew", + "servings" : 4, + "subtitle" : "Delicious with fresh bread", + "title" : "Fish Stew" +} + + + + The structure of the submitted document is as shown in the table + below: + + + + + + + + + + + + + + + + In either case, the returned JSON will specify the document ID, + revision ID, and status message: + + + +{ + "id" : "FishStew", + "ok" : true, + "rev" : "1-9c65296036141e575d32ba9c034dd3ee" +} + + +

+ +

+ + Batch Mode Writes + + + 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. + + + + To use the batched mode, append the batch=ok + query argument to the URL of the PUT or + POST request. The CouchDB server will respond + with a 202 HTTP response code immediately. + + +

+ +

+ + Including Attachments + + + 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 + ). + + + + + + + + + + + + + + + + The filename will be the attachment name. For + example, when sending the JSON structure below: + + + +{ + "_id" : "FishStew", + "servings" : 4, + "subtitle" : "Delicious with fresh bread", + "title" : "Fish Stew" + "_attachments" : { + "styling.css" : { + "content-type" : "text/css", + "data" : "cCB7IGZvbnQtc2l6ZTogMTJwdDsgfQo=", + }, + }, +} + + + + The attachment styling.css can be accessed + using /recipes/FishStew/styling.css. For more + information on attachments, see + . + + + + The document data embedded in to the structure must be encoded + using base64. + + +

+ +

+ + <literal>GET /db/doc</literal> + + + + + + + + + + + + + + + + + Returns the specified doc from the specified + db. For example, to retrieve the document with + the id FishStew you would send the following + request: + + + +GET http://couchdb:5984/recipes/FishStew +Content-Type: application/json +Accept: application/json + + + + The returned JSON is the JSON of the document, including the + document ID and revision number: + + + +{ + "_id" : "FishStew", + "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c", + "servings" : 4, + "subtitle" : "Delicious with a green salad", + "title" : "Irish Fish Stew" +} + + + + Unless you request a specific revision, the latest revision of the + document will always be returned. + + +

+ + Attachments + + + 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. + + + + The JSON for the returned document will include the + _attachments field, with one or more + attachment definitions. For example: + + + +{ + "_id" : "FishStew", + "servings" : 4, + "subtitle" : "Delicious with fresh bread", + "title" : "Fish Stew" + "_attachments" : { + "styling.css" : { + "stub" : true, + "content-type" : "text/css", + "length" : 783426, + }, + }, +} + + + + The format of the returned JSON is shown in the table below: + + + + + + + + + + + + + + +

+ +

+ + Getting a List of Revisions + + + You can obtain a list of the revisions for a given document by + adding the revs=true parameter to the request + URL. For example: + + + +GET http://couchdb:5984/recipes/FishStew?revs=true +Accept: application/json + + + + The returned JSON structure includes the original document, + including a _revisions structure that + includes the revision information: + + + +{ + "servings" : 4, + "subtitle" : "Delicious with a green salad", + "_id" : "FishStew", + "title" : "Irish Fish Stew", + "_revisions" : { + "ids" : [ + "a1a9b39ee3cc39181b796a69cb48521c", + "7c4740b4dcf26683e941d6641c00c39d", + "9c65296036141e575d32ba9c034dd3ee" + ], + "start" : 3 + }, + "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" +} + + + + + + + + + + + + + + +

+ +

+ + Obtaining an Extended Revision History + + + You can get additional information about the revisions for a + given document by supplying the revs_info + argument to the query: + + + +GET http://couchdb:5984/recipes/FishStew?revs_info=true +Accept: application/json + + + + This returns extended revision information, including the + availability and status of each revision: + + + +{ + "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" +} + + + + + + + + + + + + + + +

+ +

+ + Obtaining a Specific Revision + + + To get a specific revision, use the rev + argument to the request, and specify the full revision number: + + + +GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d +Accept: application/json + + + + The specified revision of the document will be returned, + including a _rev field specifying the + revision that was requested: + + + +{ + "_id" : "FishStew", + "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d", + "servings" : 4, + "subtitle" : "Delicious with a green salad", + "title" : "Fish Stew" +} + + +

+ +

+ + <literal>HEAD /db/doc</literal> + + + + + + + + + + + + + + + + + Returns the HTTP Headers containing a minimal amount of + information about the specified document. The method supports the + same query arguments as the GET method, but + only the header information (including document size, and the + revision as an ETag), is returned. For example, a simple + HEAD request: + + + +HEAD http://couchdb:5984/recipes/FishStew +Content-Type: application/json + + + + Returns the following HTTP Headers: + + + +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 + + + + The Etag header shows the current revision for + the requested document, and the Content-Length + specifies the length of the data, if the document were requested + in full. + + + + Adding any of the query arguments (as supported by + GET + method), then the resulting HTTP Headers will correspond to what + would be returned. Note that the current revision is not returned + when the refs_info argument is used. For + example: + + + +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 + + +

+ +

+ + <literal>PUT /db/doc</literal> + + + + + + + + + + + + + + + + + The PUT method creates a new named document, or + creates a new revision of the existing document. Unlike the + POST + method, you must specify the document ID in the request URL. + + + + For example, to create the docment FishStew, + you would send the following request: + + +PUT http://couchdb:5984/recipes/FishStew +Content-Type: application/json + +{ + "servings" : 4, + "subtitle" : "Delicious with fresh bread", + "title" : "Fish Stew" +} + + + + The return type is JSON of the status, document ID,and revision + number: + + + +{ + "id" : "FishStew", + "ok" : true, + "rev" : "1-9c65296036141e575d32ba9c034dd3ee" +} + + +

+ + Updating an Existing Document + + + To update an existing document you must specify the current + revision number within the _rev parameter. + For example: + + + +PUT http://couchdb:5984/recipes/FishStew +Content-Type: application/json + +{ + "_rev" : "1-9c65296036141e575d32ba9c034dd3ee", + "servings" : 4, + "subtitle" : "Delicious with fresh salad", + "title" : "Fish Stew" +} + + + + Alternatively, you can supply the current revision number in the + If-Match HTTP header of the request. For + example: + + + +PUT http://couchdb:5984/recipes/FishStew +If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea +Content-Type: application/json + +{ + "servings" : 4, + "subtitle" : "Delicious with fresh salad", + "title" : "Fish Stew" +} + + + + The JSON returned will include the updated revision number: + + + +{ + "id" : "FishStew99", + "ok" : true, + "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea" +} + + + + For information on batched writes, which can provide improved + performance, see + . + + +

+ +

+ + <literal>DELETE /db/doc</literal> + + + + + + + + + + + + + + + + + Deletes the specified document from the database. You must supply + the current (latest) revision, either by using the + rev parameter to specify the revision: + + + +DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c +Content-Type: application/json + + + + Alternatively, you can use ETags with the + If-Match field: + + + +DELETE http://couchdb:5984/recipes/FishStew +If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c +Content-Type: application/json + + + + The returned JSON contains the document ID, revision and status: + + + +{ + "id" : "FishStew", + "ok" : true, + "rev" : "4-2719fd41187c60762ff584761b714cfb" +} + + + + + 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. + + + +

+ +

+ + <literal>COPY /db/doc</literal> + + + + + + + + + + + + + + + + + The COPY command (which is non-standard HTTP) + copies an existing document to a new or existing document. + + + + The source document is specified on the request line, with the + Destination HTTP Header of the request + specifying the target document. + + +

+ + Copying a Document + + + You can copy the latest version of a document to a new document + by specifying the current document and target document: + + + +COPY http://couchdb:5984/recipes/FishStew +Content-Type: application/json +Destination: IrishFishStew + + + + The above request copies the document + FishStew to the new document + IrishFishStew. The response is the ID and + revision of the new document. + + + +{ + "id" : "IrishFishStew", + "rev" : "1-9c65296036141e575d32ba9c034dd3ee" +} + + +

+ +

+ + Copying from a Specific Revision + + + To copy from a specific version, use the + rev argument to the query string: + + + +COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082 +Content-Type: application/json +Destination: IrishFishStew + + + + The new document will be created using the information in the + specified revision of the source document. + + +

+ +

+ + Copying to an Existing 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: + + + +COPY http://couchdb:5984/recipes/FishStew +Content-Type: application/json +Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee + + + + The return value will be the new revision of the copied + document: + + + +{ + "id" : "IrishFishStew", + "rev" : "2-55b6a1b251902a2c249b667dab1c6692" +} + + +

+ +

+ + <literal>GET /db/doc/attachment</literal> + + + + + + + + + + + + + + + + + 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. + + +

+ +

+ + <literal>PUT /db/doc/attachment</literal> + + + + + + + + + + + + + + + + + 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 attacment 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: + + + +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: + + + +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: + + + +{ + "id" : "FishStew", + "ok" : true, + "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74" +} + + + + + 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. + + +

+ +

+ + <literal>DELETE /db/doc/attachment</literal> + + + + + + + + + + + + + + + + + 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: + + + +DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74 +Content-Type: application/json + + + + + The returned JSON contains the updated revision information: + + + +{ + "id" : "FishStew", + "ok" : true, + "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e" +} + + +

+ + http://git-wip-us.apache.org/repos/asf/couchdb/blob/749f8c8c/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 @@ + + +%every.entities; +]> + + + CouchDB API Server 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 + + + + + + + + + + + + + + +

+ + <literal>GET /db/_design/design-doc</literal> + + + + + + + + + + + + + + + + + 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: + + + +GET http://couchdb:5984/recipes/_design/recipes +Content-Type: application/json + + + + The returned string will be the JSON of the design document: + + + +{ + "_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 + . + + +

+ +

+ + <literal>PUT /db/_design/design-doc</literal> + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + For more information on writing views, see + . + + +

+ +

+ + <literal>DELETE /db/_design/design-doc</literal> + + + + + + + + + + + + + + + + + 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: + + + +DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8 +Content-Type: application/json + + + + The response contains the delete document ID and revision: + + + +{ + "id" : "recipe/_design/recipes" + "ok" : true, + "rev" : "3-7a05370bff53186cb5d403f861aca154", +} + + +

+ +

+ + <literal>COPY /db/_design/design-doc</literal> + + + + + + + + + + + + + + + + + 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: + + + +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. + + + +{ + "id" : "recipes/_design/recipelist" + "rev" : "1-9c65296036141e575d32ba9c034dd3ee", +} + + + + + 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: + + + +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: + + + +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: + + + +{ + "id" : "recipes/_design/recipes" + "rev" : "2-55b6a1b251902a2c249b667dab1c6692", +} + + +

+ +

+ + <literal>GET /db/_design/design-doc/attachment</literal> + + + + + + + + + + + + + + + + + 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. + + +

+ +

+ + <literal>PUT /db/_design/design-doc/attachment</literal> + + + + + + + + + + + + + + + + + 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 attacment 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: + + + +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: + + + +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: + + + +{ + "id" : "_design/recipes" + "ok" : true, + "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5", +} + + + + + Uploading an attachment updates the corresponding document + revision. Revisions are tracked for the parent document, not + individual attachments. + + + +

+ +

+ + <literal>DELETE /db/_design/design-doc/attachment</literal> + + + + + + + + + + + + + + + + + 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: + + + +DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a + + + + The returned JSON contains the updated revision information for + the parent document: + + + +{ + "id" : "_design/recipes" + "ok" : true, + "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c", +} + + +

+ +

+ + <literal>GET /db/_design/design-doc/_info</literal> + + + + + + + + + + + + + + + + + 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: + + + +GET http://couchdb:5984/recipes/_design/recipes/_info +Content-Type: application/json + + + + This returns the following JSON structure: + + + +{ + "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 + in + . + + + + Design Document Info JSON Contents + + + + + + + + + + + + +

+ +

+ + <literal>GET /db/_design/design-doc/_view/view-name</literal> + + + + + + + + + + + + + + + + + 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. + + + + + 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 + + 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 + . + + + + + + + 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: + + +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 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. + + + + 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 + ). + + +

+ +

+ + 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: + + + +{ + "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 + + + +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: + + + +{ + "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: + + + +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: + + + +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: + + + +{ + "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: + + + +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 + + + The startkey and endkey + query arguments can be used to specify the range of values to be + displayed when querying the view. + + + + + The values + + + +

+ +

+ + Using Limits and Skipping Rows + + + TBC + + +

+ +

+ + View Reduction and Grouping + + + TBC + + +

+ +

+ + <literal>POST /db/_design/design-doc/_view/view-name</literal> + + + + + + + + + + + + + + + + + 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 + + fun + + + + For example, the request below will return all the recipes where + the key for the view matches either claret or + clear apple cider : + + + +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. + + + +{ + "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 + + requests. + + + + For example, sending the following request for ingredients + matching claret and clear apple + juice: + + + +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: + + + +{ + "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 +} + + +

+ +

+ + <literal>POST /db/_design/design-doc/_show/show-name</literal> + + + + + + + + + + + + + + + + + +

+ +

+ + <literal>POST /db/_design/design-doc/_show/show-name/doc</literal> + + + + + + + + + + + + + + + + + +

+ +

+ + <literal>GET + /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal> + + + + + + + + + + + + + + + +

+ +

+ + <literal>POST + /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal> + + + + + + + + + + + + + + + +

+ +

+ + <literal>GET /db/_design/design-doc/_list/list-name/view-name</literal> + + + + + + + + + + + + + + + +

+ +

+ + <literal>POST /db/_design/design-doc/_list/list-name/view-name</literal> + + + + + + + + + + + + + + + +

+ +

+ + <literal>PUT /db/_design/design-doc/_update/updatename/doc</literal> + + + + + + + + + + + + + + + +

+ +

+ + <literal>POST /db/_design/design-doc/_update/updatename</literal> + + + + + + + + + + + + + + + +

+ +

+ + <literal>ALL + /db/_design/design-doc/_rewrite/rewrite-name/anything</literal> + + + + + + + + + + + + + + + +

+ +