From commits-return-8693-apmail-couchdb-commits-archive=couchdb.apache.org@couchdb.apache.org Fri Sep 14 10:17:10 2012 Return-Path: X-Original-To: apmail-couchdb-commits-archive@www.apache.org Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id C5989DFA3 for ; Fri, 14 Sep 2012 10:17:10 +0000 (UTC) Received: (qmail 91926 invoked by uid 500); 14 Sep 2012 10:17:09 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 91650 invoked by uid 500); 14 Sep 2012 10:17:08 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 90986 invoked by uid 99); 14 Sep 2012 10:16:59 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 14 Sep 2012 10:16:59 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id 529A036829; Fri, 14 Sep 2012 10:16:59 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: dch@apache.org To: commits@couchdb.apache.org X-Mailer: ASF-Git Admin Mailer Subject: [6/49] Align sphinx & autotools Message-Id: <20120914101659.529A036829@tyr.zones.apache.org> Date: Fri, 14 Sep 2012 10:16:59 +0000 (UTC) http://git-wip-us.apache.org/repos/asf/couchdb/blob/838cf30b/share/docs/rst/manual.rst ---------------------------------------------------------------------- diff --git a/share/docs/rst/manual.rst b/share/docs/rst/manual.rst deleted file mode 100644 index 7c56f12..0000000 --- a/share/docs/rst/manual.rst +++ /dev/null @@ -1,19092 +0,0 @@ -==================================== -CouchDB \_\_meta\_version\_\_ Manual -==================================== - -CouchDB API Server Authentication Methods -========================================= - -The CouchDB Authentication methods provide an interface for obtaining -session and authorization data. - -A list of the available methods and URL paths are provided below: - -Authentication API Calls - -CouchDB API Server Configuration Methods -======================================== - -The CouchDB API Server Configuration Methods provide an interface to -query and update the various configuration values within a running -CouchDB instance. - -A list of the available methods and URL paths are provided below: - -Configuration API Calls - -``GET /_config`` -================ - -Returns the entire CouchDB server configuration as a JSON structure. The -structure is organized by different configuration sections, with -individual values. - -For example, to get the configuration for a server: - -:: - - GET http://couchdb:5984/_config - Accept: application/json - -The response is the JSON structure: - -:: - - { - "query_server_config" : { - "reduce_limit" : "true" - }, - "couchdb" : { - "os_process_timeout" : "5000", - "max_attachment_chunk_size" : "4294967296", - "max_document_size" : "4294967296", - "uri_file" : "/var/lib/couchdb/couch.uri", - "max_dbs_open" : "100", - "view_index_dir" : "/var/lib/couchdb", - "util_driver_dir" : "/usr/lib64/couchdb/erlang/lib/couch-1.0.1/priv/lib", - "database_dir" : "/var/lib/couchdb", - "delayed_commits" : "true" - }, - "attachments" : { - "compressible_types" : "text/*, application/javascript, application/json, application/xml", - "compression_level" : "8" - }, - "uuids" : { - "algorithm" : "utc_random" - }, - "daemons" : { - "view_manager" : "{couch_view, start_link, []}", - "auth_cache" : "{couch_auth_cache, start_link, []}", - "uuids" : "{couch_uuids, start, []}", - "stats_aggregator" : "{couch_stats_aggregator, start, []}", - "query_servers" : "{couch_query_servers, start_link, []}", - "httpd" : "{couch_httpd, start_link, []}", - "stats_collector" : "{couch_stats_collector, start, []}", - "db_update_notifier" : "{couch_db_update_notifier_sup, start_link, []}", - "external_manager" : "{couch_external_manager, start_link, []}" - }, - "stats" : { - "samples" : "[0, 60, 300, 900]", - "rate" : "1000" - }, - "httpd" : { - "vhost_global_handlers" : "_utils, _uuids, _session, _oauth, _users", - "secure_rewrites" : "true", - "authentication_handlers" : "{couch_httpd_oauth, oauth_authentication_handler}, - {couch_httpd_auth, cookie_authentication_handler}, - {couch_httpd_auth, default_authentication_handler}", - "port" : "5984", - "default_handler" : "{couch_httpd_db, handle_request}", - "allow_jsonp" : "false", - "bind_address" : "192.168.0.2", - "max_connections" : "2048" - }, - "query_servers" : { - "javascript" : "/usr/bin/couchjs /usr/share/couchdb/server/main.js" - }, - "couch_httpd_auth" : { - "authentication_db" : "_users", - "require_valid_user" : "false", - "authentication_redirect" : "/_utils/session.html", - "timeout" : "600", - "auth_cache_size" : "50" - }, - "httpd_db_handlers" : { - "_design" : "{couch_httpd_db, handle_design_req}", - "_compact" : "{couch_httpd_db, handle_compact_req}", - "_view_cleanup" : "{couch_httpd_db, handle_view_cleanup_req}", - "_temp_view" : "{couch_httpd_view, handle_temp_view_req}", - "_changes" : "{couch_httpd_db, handle_changes_req}" - }, - "replicator" : { - "max_http_sessions" : "10", - "max_http_pipeline_size" : "10" - }, - "log" : { - "include_sasl" : "true", - "level" : "info", - "file" : "/var/log/couchdb/couch.log" - }, - "httpd_design_handlers" : { - "_update" : "{couch_httpd_show, handle_doc_update_req}", - "_show" : "{couch_httpd_show, handle_doc_show_req}", - "_info" : "{couch_httpd_db, handle_design_info_req}", - "_list" : "{couch_httpd_show, handle_view_list_req}", - "_view" : "{couch_httpd_view, handle_view_req}", - "_rewrite" : "{couch_httpd_rewrite, handle_rewrite_req}" - }, - "httpd_global_handlers" : { - "_replicate" : "{couch_httpd_misc_handlers, handle_replicate_req}", - "/" : "{couch_httpd_misc_handlers, handle_welcome_req, <<\"Welcome\">>}", - "_config" : "{couch_httpd_misc_handlers, handle_config_req}", - "_utils" : "{couch_httpd_misc_handlers, handle_utils_dir_req, \"/usr/share/couchdb/www\"}", - "_active_tasks" : "{couch_httpd_misc_handlers, handle_task_status_req}", - "_session" : "{couch_httpd_auth, handle_session_req}", - "_log" : "{couch_httpd_misc_handlers, handle_log_req}", - "favicon.ico" : "{couch_httpd_misc_handlers, handle_favicon_req, \"/usr/share/couchdb/www\"}", - "_all_dbs" : "{couch_httpd_misc_handlers, handle_all_dbs_req}", - "_oauth" : "{couch_httpd_oauth, handle_oauth_req}", - "_restart" : "{couch_httpd_misc_handlers, handle_restart_req}", - "_uuids" : "{couch_httpd_misc_handlers, handle_uuids_req}", - "_stats" : "{couch_httpd_stats_handlers, handle_stats_req}" - } - } - - -``GET /_config/section`` -======================== - -Gets the configuration structure for a single section. For example, to -retrieve the CouchDB configuration section values: - -:: - - GET http://couchdb:5984/_config/couchdb - Accept: application/json - -The returned JSON contains just the configuration values for this -section: - -:: - - { - "os_process_timeout" : "5000", - "max_attachment_chunk_size" : "4294967296", - "max_document_size" : "4294967296", - "uri_file" : "/var/lib/couchdb/couch.uri", - "max_dbs_open" : "100", - "view_index_dir" : "/var/lib/couchdb", - "util_driver_dir" : "/usr/lib64/couchdb/erlang/lib/couch-1.0.1/priv/lib", - "database_dir" : "/var/lib/couchdb", - "delayed_commits" : "true" - } - -``GET /_config/section/key`` -============================ - -Gets a single configuration value from within a specific configuration -section. For example, to obtain the current log level: - -:: - - GET http://couchdb:5984/_config/log/level - Accept: application/json - -Returns the string of the log level: - -:: - - "info" - - **Note** - - The returned value will be the JSON of the value, which may be a - string or numeric value, or an array or object. Some client - environments may not parse simple strings or numeric values as valid - JSON. - -``PUT /_config/section/key`` -============================ - -Updates a configuration value. The new value should be supplied in the -request body in the corresponding JSON format. For example, if you are -setting a string value, you must supply a valid JSON string. - -For example, to set the function used to generate UUIDs by the -``GET /_uuids`` API call to use the ``utc_random`` generator: - -:: - - PUT http://couchdb:5984/_config/uuids/algorithm - Content-Type: application/json - - "utc_random" - -The return value will be empty, with the response code indicating the -success or failure of the configuration setting. - -``DELETE /_config/section/key`` -=============================== - -Deletes a configuration value. The returned JSON will be the value of -the configuration parameter before it was deleted. For example, to -delete the UUID parameter: - -:: - - DELETE http://couchdb:5984/_config/uuids/algorithm - Content-Type: application/json - -The returned value is the last configured UUID function: - -:: - - "random" - -CouchDB API Server Database Methods -=================================== - -The Database methods provide an interface to an entire database withing -CouchDB. These are database, rather than document, level requests. - -A list of the available methods and URL paths are provided below: - -Database API Calls - -For all the database methods, the database name within the URL path -should be the database name that you wish to perform the operation on. -For example, to obtain the meta information for the database -``recipes``, you would use the HTTP request: - -:: - - GET /recipes - -For clarity, the form below is used in the URL paths: - -:: - - GET /db - -Where ``db`` is the name of any database. - -``GET /db`` -=========== - -Gets information about the specified database. For example, to retrieve -the information for the database ``recipe``: - -:: - - GET http://couchdb:5984/recipes - Accept: application/json - -The JSON response contains meta information about the database. A sample -of the JSON returned for an empty database is provided below: - -:: - - { - "compact_running" : false, - "committed_update_seq" : 375048, - "disk_format_version" : 5, - "disk_size" : 33153123, - "doc_count" : 18386, - "doc_del_count" : 0, - "db_name" : "recipes", - "instance_start_time" : "1290700340925570", - "purge_seq" : 10, - "update_seq" : 375048 - } - - -The elements of the returned structure are shown in the table below: - -``PUT /db`` -=========== - -Creates a new database. The database name must be composed of one or -more of the following characters: - -- Lowercase characters (``a-z``) - -- Name must begin with a lowercase letter - -- Digits (``0-9``) - -- Any of the characters ``_``, ``$``, ``(``, ``)``, ``+``, ``-``, and - ``/``. - -Trying to create a database that does not meet these requirements will -return an error quoting these restrictions. - -To create the database ``recipes``: - -:: - - PUT http://couchdb:5984/recipes - Content-Type: application/json - -The returned content contains the JSON status: - -:: - - { - "ok" : true - } - -Anything should be treated as an error, and the problem should be taken -form the HTTP response code. - -``DELETE /db`` -============== - -Deletes the specified database, and all the documents and attachments -contained within it. - -To delete the database ``recipes`` you would send the request: - -:: - - DELETE http://couchdb:5984/recipes - Content-Type: application/json - -If successful, the returned JSON will indicate success - -:: - - { - "ok" : true - } - -``GET /db/_changes`` -==================== - -Obtains a list of the changes made to the database. This can be used to -monitor for update and modifications to the database for post processing -or synchronization. There are three different types of supported changes -feeds, poll, longpoll, and continuous. All requests are poll requests by -default. You can select any feed type explicitly using the ``feed`` -query argument. - -- **Poll** - - With polling you can request the changes that have occured since a - specific sequence number. This returns the JSON structure containing - the changed document information. When you perform a poll change - request, only the changes since the specific sequence number are - returned. For example, the query - - :: - - DELETE http://couchdb:5984/recipes/_changes - Content-Type: application/json - - Will get all of the changes in the database. You can request a - starting point using the ``since`` query argument and specifying the - sequence number. You will need to record the latest sequence number - in your client and then use this when making another request as the - new value to the ``since`` parameter. - -- **Longpoll** - - With long polling the request to the server will remain open until a - change is made on the database, when the changes will be reported, - and then the connection will close. The long poll is useful when you - want to monitor for changes for a specific purpose without wanting to - monitoring continuously for changes. - - Because the wait for a change can be significant you can set a - timeout before the connection is automatically closed (the - ``timeout`` argument). You can also set a heartbeat interval (using - the ``heartbeat`` query argument), which sends a newline to keep the - connection open. - -- **Continuous** - - Continuous sends all new changes back to the client immediately, - without closing the connection. In continuous mode the format of the - changes is slightly different to accommodate the continuous nature - while ensuring that the JSON output is still valid for each change - notification. - - As with the longpoll feed type you can set both the timeout and - heartbeat intervals to ensure that the connection is kept open for - new changesand updates. - -The return structure for ``normal`` and ``longpoll`` modes is a JSON -array of changes objects, and the last update sequence number. The -structure is described in the following table. - -The return format for ``continuous`` mode the server sends a CRLF -(carriage-return, linefeed) delimited line for each change. Each line -contains the `JSON object`_. - -You can also request the full contents of each document change (instead -of just the change notification) by using the ``include_docs`` -parameter. - -Filtering ---------- - -You can filter the contents of the changes feed in a number of ways. The -most basic way is to specify one or more document IDs to the query. This -causes the returned structure value to only contain changes for the -specified IDs. Note that the value of this query argument should be a -JSON formatted array. - -You can also filter the ``_changes`` feed by defining a filter function -within a design document. The specification for the filter is the same -as for replication filters. You specify the name of the filter function -to the ``filter`` parameter, specifying the design document name and -filter name. For example: - -:: - - GET /db/_changes?filter=design_doc/filtername - -The ``_changes`` feed can be used to watch changes to specific document -ID's or the list of ``_design`` documents in a database. If the -``filters`` parameter is set to ``_doc_ids`` a list of doc IDs can be -passed in the ``doc_ids`` parameter as a JSON array. - -For more information, see ?. - -``POST /db/_compact`` -===================== - -Request compaction of the specified database. Compaction compresses the -disk database file by performing the following operations: - -- Writes a new version of the database file, removing any unused - sections from the new version during write. Because a new file is - temporary created for this purpose, you will need twice the current - storage space of the specified database in order for the compaction - routine to complete. - -- Removes old revisions of documents from the database, up to the - per-database limit specified by the ``_revs_limit`` database - parameter. See ? . - -Compaction can only be requested on an individual database; you cannot -compact all the databases for a CouchDB instance. The compaction process -runs as a background process. - -You can determine if the compaction process is operating on a database -by obtaining the database meta information, the ``compact_running`` -value of the returned database structure will be set to true. See ? . - -You can also obtain a list of running processes to determine whether -compaction is currently running. See ?. - -``POST /db/_compact/design-doc`` -================================ - -Compacts the view indexes associated with the specified design document. -You can use this in place of the full database compaction if you know a -specific set of view indexes have been affected by a recent database -change. - -For example, to compact the views associated with the ``recipes`` design -document: - -:: - - POST http://couchdb:5984/recipes/_compact/recipes - Content-Type: application/json - -CouchDB will immediately return with a status indicating that the -compaction request has been received (HTTP status code 202): - -:: - - { - "ok" : true - } - - -``POST /db/_view_cleanup`` -========================== - -Cleans up the cached view output on disk for a given view. For example: - -:: - - POST http://couchdb:5984/recipes/_view_cleanup - Content-Type: application/json - -If the request is successful, a basic status message us returned: - -:: - - { - "ok" : true - } - - -``POST /db/_ensure_full_commit`` -================================ - -Commits any recent changes to the specified database to disk. You should -call this if you want to ensure that recent changes have been written. -For example, to commit all the changes to disk for the database -``recipes`` you would use: - -:: - - POST http://couchdb:5984/recipes/_ensure_full_commit - Content-Type: application/json - -This returns a status message, containing the success message and the -timestamp for when the CouchDB instance was started: - -:: - - { - "ok" : true, - "instance_start_time" : "1288186189373361" - } - -``POST /db/_bulk_docs`` -======================= - -The bulk document API allows you to create and update multiple documents -at the same time within a single request. The basic operation is similar -to creating or updating a single document, except that you batch the -document structure and information and . When creating new documents the -document ID is optional. For updating existing documents, you must -provide the document ID, revision information, and new document values. - -For both inserts and updates the basic structure of the JSON is the -same: - -Inserting Documents in Bulk ---------------------------- - -To insert documents in bulk into a database you need to supply a JSON -structure with the array of documents that you want to add to the -database. Using this method you can either include a document ID, or -allow the document ID to be automatically generated. - -For example, the following inserts three new documents, two with the -supplied document IDs, and one which will have a document ID generated: - -:: - - { - "docs" : [ - { - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" - }, - { - "_id" : "LambStew", - "servings" : 6, - "subtitle" : "Delicious with scone topping", - "title" : "Lamb Stew" - }, - { - "servings" : 8, - "subtitle" : "Delicious with suet dumplings", - "title" : "Beef Stew" - }, - ] - } - - -The return type from a bulk insertion will be 201, with the content of -the returned structure indicating specific success or otherwise messages -on a per-document basis. - -The return structure from the example above contains a list of the -documents created, here with the combination and their revision IDs: - -:: - - POST http://couchdb:5984/recipes/_bulk_docs - Content-Type: application/json - - [ - { - "id" : "FishStew", - "rev" : "1-9c65296036141e575d32ba9c034dd3ee", - }, - { - "id" : "LambStew", - "rev" : "1-34c318924a8f327223eed702ddfdc66d", - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "rev" : "1-857c7cbeb6c8dd1dd34a0c73e8da3c44", - } - ] - - -The content and structure of the returned JSON will depend on the -transaction semantics being used for the bulk update; see ? for more -information. Conflicts and validation errors when updating documents in -bulk must be handled separately; see ?. - -Updating Documents in Bulk --------------------------- - -The bulk document update procedure is similar to the insertion -procedure, except that you must specify the document ID and current -revision for every document in the bulk update JSON string. - -For example, you could send the following request: - -:: - - POST http://couchdb:5984/recipes/_bulk_docs - Content-Type: application/json - - { - "docs" : [ - { - "_id" : "FishStew", - "_rev" : "1-9c65296036141e575d32ba9c034dd3ee", - "servings" : 4, - "subtitle" : "Delicious with freshly baked bread", - "title" : "Fish Stew" - }, - { - "_id" : "LambStew", - "_rev" : "1-34c318924a8f327223eed702ddfdc66d", - "servings" : 6, - "subtitle" : "Serve with a wholemeal scone topping", - "title" : "Lamb Stew" - }, - { - "_id" : "7f7638c86173eb440b8890839ff35433" - "_rev" : "1-857c7cbeb6c8dd1dd34a0c73e8da3c44", - "servings" : 8, - "subtitle" : "Hand-made dumplings make a great accompaniment", - "title" : "Beef Stew" - } - ] - } - -The return structure is the JSON of the updated documents, with the new -revision and ID information: - -:: - - [ - { - "id" : "FishStew", - "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1" - }, - { - "id" : "LambStew", - "rev" : "2-0786321986194c92dd3b57dfbfc741ce" - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "rev" : "2-bdd3bf3563bee516b96885a66c743f8e" - } - ] - -You can optionally delete documents during a bulk update by adding the -``_deleted`` field with a value of ``true`` to each docment ID/revision -combination within the submitted JSON structure. - -The return type from a bulk insertion will be 201, with the content of -the returned structure indicating specific success or otherwise messages -on a per-document basis. - -The content and structure of the returned JSON will depend on the -transaction semantics being used for the bulk update; see ? for more -information. Conflicts and validation errors when updating documents in -bulk must be handled separately; see ?. - -Bulk Documents Transaction Semantics ------------------------------------- - -CouchDB supports two different modes for updating (or inserting) -documents using the bulk documentation system. Each mode affects both -the state of the documents in the event of system failure, and the level -of conflict checking performed on each document. The two modes are: - -- ``non-atomic`` - - The default mode is non-atomic, that is, CouchDB will only guarantee - that some of the documents will be saved when you send the request. - The response will contain the list of documents successfully inserted - or updated during the process. In the event of a crash, some of the - documents may have been successfully saved, and some will have been - lost. - - In this mode, the response structure will indicate whether the - document was updated by supplying the new ``_rev`` parameter - indicating a new document revision was created. If the update failed, - then you will get an ``error`` of type ``conflict``. For example: - - :: - - [ - { - "id" : "FishStew", - "error" : "conflict", - "reason" : "Document update conflict." - }, - { - "id" : "LambStew", - "error" : "conflict", - "reason" : "Document update conflict." - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "error" : "conflict", - "reason" : "Document update conflict." - } - ] - - - In this case no new revision has been created and you will need to - submit the document update, with the correct revision tag, to update - the document. - -- ``all-or-nothing`` - - In all-or-nothing mode, either all documents are written to the - database, or no documents are written to the database, in the event - of a system failure during commit. - - In addition, the per-document conflict checking is not performed. - Instead a new revision of the document is created, even if the new - revision is in conflict with the current revision in the database. - The returned structure contains the list of documents with new - revisions: - - :: - - [ - { - "id" : "FishStew", - "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1" - }, - { - "id" : "LambStew", - "rev" : "2-0786321986194c92dd3b57dfbfc741ce" - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "rev" : "2-bdd3bf3563bee516b96885a66c743f8e" - } - ] - - When updating documents using this mode the revision of a document - included in views will be arbitrary. You can check the conflict - status for a document by using the ``conflicts=true`` query argument - when accessing the view. Conflicts should be handled individually to - ensure the consistency of your database. - - To use this mode, you must include the ``all_or_nothing`` field (set - to true) within the main body of the JSON of the request. - -The effects of different database operations on the different modes are -summarized in the table below: - -+--------------------+---------------+----------------------------------------+------------------------------------------------------------------------+ -| Transaction Mode | Transaction | Cause | Resolution | -+====================+===============+========================================+========================================================================+ -| Non-atomic | Insert | Requested document ID already exists | Resubmit with different document ID, or update the existing document | -+--------------------+---------------+----------------------------------------+------------------------------------------------------------------------+ -| Non-atomic | Update | Revision missing or incorrect | Resubmit with correct revision | -+--------------------+---------------+----------------------------------------+------------------------------------------------------------------------+ -| All-or-nothing | Insert | Additional revision inserted | Resolve conflicted revisions | -+--------------------+---------------+----------------------------------------+------------------------------------------------------------------------+ -| All-or-nothing | Update | Additional revision inserted | Resolve conflicted revisions | -+--------------------+---------------+----------------------------------------+------------------------------------------------------------------------+ - -Table: Conflicts on Bulk Inserts - -Replication of documents is independent of the type of insert or update. -The documents and revisions created during a bulk insert or update are -replicated in the same way as any other document. This can mean that if -you make use of the all-or-nothing mode the exact list of documents, -revisions (and their conflict state) may or may not be replicated to -other databases correctly. - -Bulk Document Validation and Conflict Errors --------------------------------------------- - -The JSON returned by the ``_bulk_docs`` operation consists of an array -of JSON structures, one for each document in the original submission. -The returned JSON structure should be examined to ensure that all of the -documents submitted in the original request were successfully added to -the database. - -The exact structure of the returned information is shown in ?. - -When a document (or document revision) is not correctly comitted to the -database because of an error, you should check the ``error`` field to -determine error type and course of action. Errors will be one of the -following type: - -- ``conflict`` - - The document as submitted is in conflict. If you used the default - bulk transaction mode then the new revision will not have been - created and you will need to re-submit the document to the database. - If you used ``all-or-nothing`` mode then you will need to manually - resolve the conflicted revisions of the document. - - Conflict resolution of documents added using the bulk docs interface - is identical to the resolution procedures used when resolving - conflict errors during replication. - -- ``forbidden`` - - Entries with this error type indicate that the validation routine - applied to the document during submission has returned an error. - - For example, if your validation routine includes the following: - - :: - - throw({forbidden: 'invalid recipe ingredient'}); - - The error returned will be: - - :: - - { - "id" : "7f7638c86173eb440b8890839ff35433", - "error" : "forbidden", - "reason" : "invalid recipe ingredient" - } - - - For more information, see ?. - -``POST /db/_temp_view`` -======================= - -Creates (and executes) a temporary view based on the view function -supplied in the JSON request. For example: - -:: - - POST http://couchdb:5984/recipes/_temp_view - Content-Type: application/json - - { - "map" : "function(doc) { if (doc.value > 9995) { emit(null, doc.value); } }" - } - -The resulting JSON response is the result from the execution of the -temporary view: - -:: - - { - "total_rows" : 3, - "rows" : [ - { - "value" : 9998.41913029012, - "id" : "05361cc6aa42033878acc1bacb1f39c2", - "key" : null - }, - { - "value" : 9998.94149934853, - "id" : "1f443f471e5929dd7b252417625ed170", - "key" : null - }, - { - "value" : 9998.01511339154, - "id" : "1f443f471e5929dd7b252417629c102b", - "key" : null - } - ], - "offset" : 0 - } - -The arguments also available to standard view requests also apply to -temporary views, but the execution of the view may take some time as it -relies on being executed at the time of the request. In addition to the -time taken, they are also computationally very expensive to produce. You -should use a defined view if you want to achieve the best performance. - -For more information, see ?. - -``POST /db/_purge`` -=================== - -A database purge permanently removes the references to deleted documents -from the database. Deleting a document within CouchDB does not actually -remove the documen from the database, instead, the document is marked as -a deleted (and a new revision is created). This is to ensure that -deleted documents are replicated to other databases as having been -deleted. This also means that you can check the status of a document and -identify that the document has been deleted. - -The purge operation removes the refernces to the deleted documents from -the database. The purging of old documents is not replicated to other -databases. If you are replicating between databases and have deleted a -large number of documents you should run purge on each database. - - **Note** - - Purging documents does not remove the space used by them on disk. To - reclaim disk space, you should run a database compact (see ?, and - compact views (see ?). - -To perform a purge operation you must send a request including the JSON -of the document IDs that you want to purge. For example: - -:: - - POST http://couchdb:5984/recipes/_purge - Content-Type: application/json - - { - "FishStew" : [ - "17-b3eb5ac6fbaef4428d712e66483dcb79" - ] - } - -The format of the request must include the document ID and one or more -revisions that must be purged. - -The response will contain the purge sequence number, and a list of the -document IDs and revisions successfully purged. - -:: - - { - "purged" : { - "FishStew" : [ - "17-b3eb5ac6fbaef4428d712e66483dcb79" - ] - }, - "purge_seq" : 11 - } - -Updating Indexes ----------------- - -The number of purges on a database is tracked using a purge sequence. -This is used by the view indexer to optimize the updating of views that -contain the purged documents. - -When the indexer identifies that the purge sequence on a database has -changed, it compares the purge sequence of the database with that stored -in the view index. If the difference between the stored sequence and -database is sequence is only 1, then the indexer uses a cached list of -the most recently purged documents, and then removes these documents -from the index individually. This prevents completely rebuilding the -index from scratch. - -If the difference between the stored sequence number and current -database sequence is greater than 1, then the view index is entirely -rebuilt. This is an expensive operation as every document in the -database must be examined. - -``GET /db/_all_docs`` -===================== - -Returns a JSON structure of all of the documents in a given database. -The information is returned as a JSON structure containing meta -information about the return structure, and the list documents and basic -contents, consisting the ID, revision and key. The key is generated from -the document ID. - -By default the information returned contains only the document ID and -revision. For example, the request: - -:: - - GET http://couchdb:5984/recipes/_all_docs - Accept: application/json - -Returns the following structure: - -:: - - { - "total_rows" : 18386, - "rows" : [ - { - "value" : { - "rev" : "1-bc0d5aed1e339b1cc1f29578f3220a45" - }, - "id" : "Aberffrawcake", - "key" : "Aberffrawcake" - }, - { - "value" : { - "rev" : "3-68a20c89a5e70357c20148f8e82ca331" - }, - "id" : "Adukiandorangecasserole-microwave", - "key" : "Adukiandorangecasserole-microwave" - }, - { - "value" : { - "rev" : "3-9b2851ed9b6f655cc4eb087808406c60" - }, - "id" : "Aioli-garlicmayonnaise", - "key" : "Aioli-garlicmayonnaise" - }, - ... - ], - "offset" : 0 - } - -The information is returned in the form of a temporary view of all the -database documents, with the returned key consisting of the ID of the -document. The remainder of the interface is therefore identical to the -View query arguments and their behavior. - -``POST /db/_all_docs`` -====================== - -The ``POST`` to ``_all_docs`` allows to specify multiple keys to be -selected from the database. This enables you to request multiple -documents in a single request, in place of multiple ? requests. - -The request body should contain a list of the keys to be returned as an -array to a ``keys`` object. For example: - -:: - - POST http://couchdb:5984/recipes/_all_docs - User-Agent: MyApp/0.1 libwww-perl/5.837 - - { - "keys" : [ - "Zingylemontart", - "Yogurtraita" - ] - } - -The return JSON is the all documents structure, but with only the -selected keys in the output: - -:: - - { - "total_rows" : 2666, - "rows" : [ - { - "value" : { - "rev" : "1-a3544d296de19e6f5b932ea77d886942" - }, - "id" : "Zingylemontart", - "key" : "Zingylemontart" - }, - { - "value" : { - "rev" : "1-91635098bfe7d40197a1b98d7ee085fc" - }, - "id" : "Yogurtraita", - "key" : "Yogurtraita" - } - ], - "offset" : 0 - } - -``POST /db/_missing_revs`` -========================== - -``POST /db/_revs_diff`` -======================= - -``GET /db/_security`` -===================== - -Gets the current secrity object from the specified database. The -security object consists of two compulsory elements, ``admins`` and -``readers``, which are used to specify the list of users and/or roles -that have admin and reader rights to the database respectively. Any -additional fields in the security object are optional. The entire -security object is made available to validation and other internal -functions so that the database can control and limit functionality. - -To get the existing security object you would send the following -request: - -:: - - { - "admins" : { - "roles" : [], - "names" : [ - "mc", - "slp" - ] - }, - "readers" : { - "roles" : [], - "names" : [ - "tim", - "brian" - ] - } - } - - **Note** - - If the security object for a database has never beent set, then the - value returned will be empty. - -``PUT /db/_security`` -===================== - -Sets the security object for the given database.For example, to set the -security object for the ``recipes`` database: - -:: - - PUT http://couchdb:5984/recipes/_security - Content-Type: application/json - - { - "admins" : { - "roles" : [], - "names" : [ - "mc", - "slp" - ] - }, - "readers" : { - "roles" : [], - "names" : [ - "tim", - "brian" - ] - } - } - -If the setting was successful, a JSON status object will be returned: - -:: - - { - "ok" : true - } - -``GET /db/_revs_limit`` -======================= - -Gets the current ``revs_limit`` (revision limit) setting. - -For example to get the current limit: - -:: - - GET http://couchdb:5984/recipes/_revs_limit - Content-Type: application/json - -The returned information is the current setting as a numerical scalar: - -:: - - 1000 - -``PUT /db/_revs_limit`` -======================= - -Sets the maximum number of document revisions that will be tracked by -CouchDB, even after compaction has occurred. You can set the revision -limit on a database by using ``PUT`` with a scalar integer of the limit -that you want to set as the request body. - -For example to set the revs limit to 100 for the ``recipes`` database: - -:: - - PUT http://couchdb:5984/recipes/_revs_limit - Content-Type: application/json - - 100 - -If the setting was successful, a JSON status object will be returned: - -:: - - { - "ok" : true - } - -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 - -``POST /db`` -============ - -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. - -``GET /db/doc`` -=============== - -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" - } - -``HEAD /db/doc`` -================ - -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 - -``PUT /db/doc`` -=============== - -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 ?. - -``DELETE /db/doc`` -================== - -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** - - 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. - -``COPY /db/doc`` -================ - -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" - } - -``GET /db/doc/attachment`` -========================== - -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. - -``PUT /db/doc/attachment`` -========================== - -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" - } - - **Note** - - Uploading an attachment updates the corresponding document revision. - Revisions are tracked for the parent document, not individual - attachments. - -Updating an Existing Attachment -------------------------------- - -Uploading an attachment using an existing attachment name will update -the corresponding stored content of the database. Since you must supply -the revision information to add an attachment to a document, this serves -as validation to update the existing attachment. - -``DELETE /db/doc/attachment`` -============================= - -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" - } - -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 - -``GET /db/_design/design-doc`` -============================== - -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 ?. - -``PUT /db/_design/design-doc`` -============================== - -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 ?. - -``DELETE /db/_design/design-doc`` -================================= - -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", - } - -``COPY /db/_design/design-doc`` -=============================== - -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", - } - - **Note** - - Copying a design document does automatically reconstruct the view - indexes. These will be recreated, as with other views, the first - time the new view is accessed. - -Copying from a Specific Revision --------------------------------- - -To copy *from* a specific version, use the ``rev`` argument to the query -string: - -:: - - 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", - } - -``GET /db/_design/design-doc/attachment`` -========================================= - -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. - -``PUT /db/_design/design-doc/attachment`` -========================================= - -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", - } - - **Note** - - Uploading an attachment updates the corresponding document revision. - Revisions are tracked for the parent document, not individual - attachments. - -``DELETE /db/_design/design-doc/attachment`` -============================================ - -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", - } - -``GET /db/_design/design-doc/_info`` -==================================== - -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 - -``GET /db/_design/design-doc/_view/view-name`` -============================================== - -Executes the specified ``view-name`` from the specified ``design-doc`` -design document. - -Querying Views and Indexes --------------------------- - -The definition of a view within a design document also creates an index -based on the key information defined within each view. The production -and use of the index significantly increases the speed of access and -searching or selecting documents from the view. - -However, the index is not updated when new documents are added or -modified in the database. Instead, the index is generated or updated, -either when the view is first accessed, or when the view is accessed -after a document has been updated. In each case, the index is updated -before the view query is executed against the database. - -View indexes are updated incrementally in the following situations: - -- A new document has been added to the database. - -- A document has been deleted from the database. - -- A document in the database has been updated. - -View indexes are rebuilt entirely when the view definition changes. To -achieve this, a 'fingerprint' of the view definition is created when the -design document is updated. If the fingerprint changes, then the view -indexes are entirely rebuilt. This ensures that changes to the view -definitions are reflected in the view indexes. - - **Note** - - View index rebuilds occur when one view from the same the view group - (i.e. all the views defined within a single a design document) has - been determined as needing a rebuild. For example, if if you have a - design document with different views, and you update the database, - all three view indexes within the design document will be updated. - -Because the view is updated when it has been queried, it can result in a -delay in returned information when the view is accessed, especially if -there are a large number of documents in the database and the view index -does not exist. There are a number of ways to mitigate, but not -completely eliminate, these issues. These include: - -- Create the view definition (and associated design documents) on your - database before allowing insertion or updates to the documents. If - this is allowed while the view is being accessed, the index can be - updated incrementally. - -- Manually force a view request from the database. You can do this - either before users are allowed to use the view, or you can access - the view manually after documents are added or updated. - -- Use the ``/db/_changes`` method to monitor for changes to the - database and then access the view to force the corresponding view - index to be updated. See ? 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 ``stale`` -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. - - **Note** - - The values - -Using Limits and Skipping Rows ------------------------------- - -TBC - -View Reduction and Grouping ---------------------------- - -TBC - -``POST /db/_design/design-doc/_view/view-name`` -=============================================== - -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 - } - -``POST /db/_design/design-doc/_show/show-name`` -=============================================== - -``POST /db/_design/design-doc/_show/show-name/doc`` -=================================================== - -``GET - /db/_design/design-doc/_list/list-name/other-design-doc/view-name`` -========================================================================= - -``POST - /db/_design/design-doc/_list/list-name/other-design-doc/view-name`` -========================================================================= - -``GET /db/_design/design-doc/_list/list-name/view-name`` -======================================================== - -``POST /db/_design/design-doc/_list/list-name/view-name`` -========================================================= - -``PUT /db/_design/design-doc/_update/updatename/doc`` -===================================================== - -``POST /db/_design/design-doc/_update/updatename`` -================================================== - -``ALL - /db/_design/design-doc/_rewrite/rewrite-name/anything`` -============================================================= - -CouchDB API -=========== - -The CouchDB API is the primary method of interfacing to a CouchDB -instance. Requests are made using HTTP and requests are used to request -information from the database, store new data, and perform views and -formatting of the information stored within the documents. - -Requests to the API can be categorised by the different areas of the -CouchDB system that you are accessing, and the HTTP method used to send -the request. Different methods imply different operations, for example -retrieval of information from the database is typically handled by the -``GET`` operation, while updates are handled by either a ``POST`` or -``PUT`` request. There are some differences between the information that -must be supplied for the different methods. For a guide to the basic -HTTP methods and request structure, see ?. - -For nearly all operations, the submitted data, and the returned data -structure, is defined within a JavaScript Object Notation (JSON) object. -Basic information on the content and data types for JSON are provided in -?. - -Errors when accessing the CouchDB API are reported using standard HTTP -Status Codes. A guide to the generic codes returned by CouchDB are -provided in ?. - -When accessing specific areas of the CouchDB API, specific information -and examples on the HTTP methods and request, JSON structures, and error -codes are provided. For a guide to the different areas of the API, see -?. - -Request Format and Responses -============================ - -CouchDB supports the following HTTP request methods: - -- ``GET`` - - Request the specified item. As with normal HTTP requests, the format - of the URL defines what is returned. With CouchDB this can include - static items, database documents, and configuration and statistical - information. In most cases the information is returned in the form of - a JSON document. - -- ``HEAD`` - - The ``HEAD`` method is used to get the HTTP header of a ``GET`` - request without the body of the response. - -- ``POST`` - - Upload data. Within CouchDB ``POST`` is used to set values, including - uploading documents, setting document values, and starting certain - administration commands. - -- ``PUT`` - - Used to put a specified resource. In CouchDB ``PUT`` is used to - create new objects, including databases, documents, views and design - documents. - -- ``DELETE`` - - Deletes the specified resource, including documents, views, and - design documents. - -- ``COPY`` - - A special method that can be used to copy documents and objects. - -If you use the an unsupported HTTP request type with a URL that does not -support the specified type, a 405 error will be returned, listing the -supported HTTP methods. For example: - -:: - - { - "error":"method_not_allowed", - "reason":"Only GET,HEAD allowed" - } - - -The CouchDB design document API and the functions when returning HTML -(for example as part of a show or list) enables you to include custom -HTTP headers through the ``headers`` block of the return object. For -more information, see ?. - -HTTP Headers -============ - -Because CouchDB uses HTTP for all communication, you need to ensure that -the correct HTTP headers are supplied (and processed on retrieval) so -that you get the right format and encoding. Different environments and -clients will be more or less strict on the effect of these HTTP headers -(especially when not present). Where possible you should be as specific -as possible. - -Request Headers ---------------- - -- ``Content-type`` - - Specifies the content type of the information being supplied within - the request. The specification uses MIME type specifications. For the - majority of requests this will be JSON (``application/json``). For - some settings the MIME type will be plain text. When uploading - attachments it should be the corresponding MIME type for the - attachment or binary (``application/octet-stream``). - - The use of the ``Content-type`` on a request is highly recommended. - -- ``Accept`` - - Specifies the list of accepted data types to be returned by the - server (i.e. that are accepted/understandable by the client). The - format should be a list of one or more MIME types, separated by - colons. - - For the majority of requests the definition should be for JSON data - (``application/json``). For attachments you can either specify the - MIME type explicitly, or use ``*/*`` to specify that all file types - are supported. If the ``Accept`` header is not supplied, then the - ``*/*`` MIME type is assumed (i.e. client accepts all formats). - - The use of ``Accept`` in queries for CouchDB is not required, but is - highly recommended as it helps to ensure that the data returned can - be processed by the client. - - If you specify a data type using the ``Accept`` header, CouchDB will - honor the specified type in the ``Content-type`` header field - returned. For example, if you explicitly request ``application/json`` - in the ``Accept`` of a request, the returned HTTP headers will use - the value in the returned ``Content-type`` field. - - For example, when sending a request without an explicit ``Accept`` - header, or when specifying ``*/*``: - - :: - - GET /recipes HTTP/1.1 - Host: couchdb:5984 - Accept: */* - - The returned headers are: - - :: - - Server: CouchDB/1.0.1 (Erlang OTP/R13B) - Date: Thu, 13 Jan 2011 13:39:34 GMT - Content-Type: text/plain;charset=utf-8 - Content-Length: 227 - Cache-Control: must-revalidate - - Note that the returned content type is ``text/plain`` even though the - information returned by the request is in JSON format. - - Explicitly specifying the ``Accept`` header: - - :: - - GET /recipes HTTP/1.1 - Host: couchdb:5984 - Accept: application/json - - The headers returned include the ``application/json`` content type: - - :: - - Server: CouchDB/1.0.1 (Erlang OTP/R13B) - Date: Thu, 13 Jan 2011 13:40:11 GMT - Content-Type: application/json - Content-Length: 227 - Cache-Control: must-revalidate - -Response Headers ----------------- - -Response headers are returned by the server when sending back content -and include a number of different header fields, many of which are -standard HTTP response header and have no significance to CouchDB -operation. The list of response headers important to CouchDB are listed -below. - -- ``Content-type`` - - Specifies the MIME type of the returned data. For most request, the - returned MIME type is ``text/plain``. All text is encoded in Unicode - (UTF-8), and this is explicitly stated in the returned - ``Content-type``, as ``text/plain;charset=utf-8``. - -- ``Cache-control`` - - The cache control HTTP response header provides a suggestion for - client caching mechanisms on how to treat the returned information. - CouchDB typically returns the ``must-revalidate``, which indicates - that the information should be revalidated if possible. This is used - to ensure that the dynamic nature of the content is correctly - updated. - -- ``Content-length`` - - The length (in bytes) of the returned content. - -- ``Etag`` - - The ``Etag`` HTTP header field is used to show the revision for a - document. - -JSON Basics -=========== - -The majority of requests and responses to CouchDB use the JavaScript -Object Notation (JSON) for formatting the content and structure of the -data and responses. - -JSON is used because it is the simplest and easiest to use solution for -working with data within a web browser, as JSON structures can be -evaluated and used as JavaScript objects within the web browser -environment. JSON also integrates with the server-side JavaScript used -within CouchDB. - -JSON supports the same basic types as supported by JavaScript, these -are: - -- Number (either integer or floating-point). - -- String; this should be enclosed by double-quotes and supports Unicode - characters and backslash escaping. For example: - - :: - - "A String" - -- Boolean - a ``true`` or ``false`` value. You can use these strings - directly. For example: - - :: - - { "value": true} - -- Array - a list of values enclosed in square brackets. For example: - - :: - - ["one", "two", "three"] - -- Object - a set of key/value pairs (i.e. an associative array, or - hash). The key must be a string, but the value can be any of the - supp