diff options
author | Dave Cottlehuber <dch@apache.org> | 2012-12-03 09:30:25 +0100 |
---|---|---|
committer | Dave Cottlehuber <dch@apache.org> | 2012-12-11 14:10:52 +0100 |
commit | 84226656ab3fad6f95029aad993be9f5ec4f1794 (patch) | |
tree | af7c10dd3d30802bdd8bbdd53716e66567e06712 | |
parent | ffca957478b13ac9a68cdb78a255b2ea8d8f471d (diff) | |
download | couchdb-84226656ab3fad6f95029aad993be9f5ec4f1794.tar.gz |
Transmogrify Couchbase XML to .rst and support Sphinx
Authors:
Alexander Shorin <kxepal@gmail.com>
Dave Cottlehuber <dch@apache.org>
Dirkjan Ochtman <dirkjan@ochtman.nl>
Robert Newson <rnewson@apache.org>
Tady Walsh for the spiffy logo
Robert Newson:
- hear no eval, see no eval, speak no eval
- fix minor niggles
Dave Cottlehuber:
- Remove vestiges of svn URLs in comments
- Add browser EventSource protocol support for changes feed
- Add all UUID algorithms including new utc+suffix-based UUID scheme
- refactor 1.1.x features and other into 1.2.0 docs
- remove manual.rst & release.rst files, only used during migration
- prepare conf.py to be run from share/Makefile similar to:
sphinx-build -a -E -W -n \
-D version='$ver' \
-D release='$ver-git-sha' \
-D project='Apache CouchDB' \
-D copyright='$year, Apache Software Foundation' \
-c `pwd` \
-d /tmp/ \
rst/ \
<output_dir>
- set sphinx config:
- update copyright & project
- set default syntax highlighting to JSON
- output docs to share/docs/manual
- move into share/docs/rst
- move old 1.1 .rst updates into main area
- add release.rst for future release notes
- swap specific versions and releases for sphinx variables
Transmogrify XML to rst using pandoc 1.9.4.2:
pandoc --smart --preserve-tabs --normalize --reference-links --chapters \
--number-sections --standalone --from docbook --to rst --output
rst/manual.rst couchdb-manual-1.1/*.xml
pandoc --smart --preserve-tabs --normalize --reference-links --chapters \
--number-sections --standalone --from docbook --to rst --output
rst/release.rst couchdb-release-1.1/*.xml
rm -rf share/docs
Alexander Shorin:
- Convert CHANGES file to rst, update information about 1.3.0 release.
- Actual till #fb670f5712 commit at 2012-12-02.
- Enable extlink extension. Setup extlink to CouchDB JIRA and Apache Git commits.
- Enable sections enumeration. Looks nicer for further referencing.
- Fix copy-paste typo, remove changes history for request object
- Add article about queryservers: JavaScript and Erlang one
- Complete article about how to write design documents
- Shift filter functions from changes and point to ddocs
- Add response object and view head info structure
- Add query server and CommonJS
- Fix markup of errors section
- Fix caution blocks
- Add back JSON structure reference
- Clarify what kind of contents should go in views
- Add back configuration option reference
- Add TODO.txt for future reference
- Add tables to start of API reference sections (except for design docs)
- Fix indentation
- Add syntax highlighting
- Add to-do statements
- Fix weird `_` escaping
- Wrap statements
- Add method descriptions
- Clean up tables
- Add missed `PUT /db/_revs_limit` description
Dirkjan Ochtman:
- Move .rst files into Sphinx Layout
- Move rst files and copy images into a Sphinx project
- Split manual & release docs into smaller pieces
- Update version numbers
- Move API docs into separate directory
68 files changed, 10635 insertions, 28614 deletions
diff --git a/share/doc/images/epub-icon.png b/share/doc/images/epub-icon.png Binary files differnew file mode 100644 index 000000000..3fda935d5 --- /dev/null +++ b/share/doc/images/epub-icon.png diff --git a/share/doc/images/favicon.ico b/share/doc/images/favicon.ico Binary files differnew file mode 100644 index 000000000..34bfaa86f --- /dev/null +++ b/share/doc/images/favicon.ico diff --git a/share/doc/images/futon-createdb.png b/share/doc/images/futon-createdb.png Binary files differnew file mode 100644 index 000000000..c8c1b9d1f --- /dev/null +++ b/share/doc/images/futon-createdb.png diff --git a/share/doc/images/futon-editdoc.png b/share/doc/images/futon-editdoc.png Binary files differnew file mode 100644 index 000000000..6802c2c6b --- /dev/null +++ b/share/doc/images/futon-editdoc.png diff --git a/share/doc/images/futon-editeddoc.png b/share/doc/images/futon-editeddoc.png Binary files differnew file mode 100644 index 000000000..5c8b549e2 --- /dev/null +++ b/share/doc/images/futon-editeddoc.png diff --git a/share/doc/images/futon-overview.png b/share/doc/images/futon-overview.png Binary files differnew file mode 100644 index 000000000..d1eac6e21 --- /dev/null +++ b/share/doc/images/futon-overview.png diff --git a/share/doc/images/futon-replform.png b/share/doc/images/futon-replform.png Binary files differnew file mode 100644 index 000000000..d904f0d56 --- /dev/null +++ b/share/doc/images/futon-replform.png diff --git a/share/doc/images/logo.png b/share/doc/images/logo.png Binary files differnew file mode 100644 index 000000000..9eac89e8d --- /dev/null +++ b/share/doc/images/logo.png diff --git a/share/doc/src/api-basics.rst b/share/doc/src/api-basics.rst new file mode 100644 index 000000000..97ea70c7e --- /dev/null +++ b/share/doc/src/api-basics.rst @@ -0,0 +1,459 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _api-basics: + +=========== +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 :ref:`api-format`. + +For nearly all operations, the submitted data, and the returned data +structure, is defined within a JavaScript Object Notation (JSON) object. +Basic information on the content and data types for JSON are provided in +:ref:`json`. + +Errors when accessing the CouchDB API are reported using standard HTTP +Status Codes. A guide to the generic codes returned by CouchDB are +provided in :ref:`errors`. + +When accessing specific areas of the CouchDB API, specific information +and examples on the HTTP methods and request, JSON structures, and error +codes are provided. For a guide to the different areas of the API, see +:ref:`api-overview`. + +.. _api-format: + +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: + +.. code-block:: javascript + + { + "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. + +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 ``*/*``: + + .. code-block:: http + + GET /recipes HTTP/1.1 + Host: couchdb:5984 + Accept: */* + + The returned headers are: + + .. code-block:: http + + 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: + + .. code-block:: http + + GET /recipes HTTP/1.1 + Host: couchdb:5984 + Accept: application/json + + The headers returned include the ``application/json`` content type: + + .. code-block:: http + + Server: CouchDB/|version| (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, or a view. + + ETags have been assigned to a map/reduce group (the collection of + views in a single design document). Any change to any of the indexes + for those views would generate a new ETag for all view URL's in a + single design doc, even if that specific view's results had not + changed. + + Each ``_view`` URL has its own ETag which only gets updated when + changes are made to the database that effect that index. If the + index for that specific view does not change, that view keeps the + original ETag head (therefore sending back 304 Not Modified more + often). + +.. _json: + +JSON Basics +=========== + +The majority of requests and responses to CouchDB use the JavaScript +Object Notation (JSON) for formatting the content and structure of the +data and responses. + +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: + + .. code-block:: javascript + + "A String" + +- Boolean - a ``true`` or ``false`` value. You can use these strings + directly. For example: + + .. code-block:: javascript + + { "value": true} + +- Array - a list of values enclosed in square brackets. For example: + + .. code-block:: javascript + + ["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 + supported JSON values. For example: + + .. code-block:: javascript + + { + "servings" : 4, + "subtitle" : "Easy to make in advance, and then cook when ready", + "cooktime" : 60, + "title" : "Chicken Coriander" + } + + + In CouchDB, the JSON object is used to represent a variety of + structures, including the main CouchDB document. + +Parsing JSON into a JavaScript object is supported through the +``JSON.parse()`` function in JavaScript, or through various libraries that +will perform the parsing of the content into a JavaScript object for +you. Libraries for parsing and generating JSON are available in many +languages, including Perl, Python, Ruby, Erlang and others. + +.. warning:: + Care should be taken to ensure that your JSON structures are + valid, invalid structures will cause CouchDB to return an HTTP status code + of 500 (server error). + +.. _errors: + +HTTP Status Codes +================= + +With the interface to CouchDB working through HTTP, error codes and +statuses are reported using a combination of the HTTP status code +number, and corresponding data in the body of the response data. + +A list of the error codes returned by CouchDB, and generic descriptions +of the related errors are provided below. The meaning of different +status codes for specific request types are provided in the +corresponding API call reference. + +- ``200 - OK`` + + Request completed successfully. + +- ``201 - Created`` + + Document created successfully. + +- ``202 - Accepted`` + + Request has been accepted, but the corresponding operation may not + have completed. This is used for background operations, such as + database compaction. + +- ``304 - Not Modified`` + + The additional content requested has not been modified. This is used + with the ETag system to identify the version of information returned. + +- ``400 - Bad Request`` + + Bad request structure. The error can indicate an error with the + request URL, path or headers. Differences in the supplied MD5 hash + and content also trigger this error, as this may indicate message + corruption. + +- ``401 - Unauthorized`` + + The item requested was not available using the supplied + authorization, or authorization was not supplied. + +- ``403 - Forbidden`` + + The requested item or operation is forbidden. + +- ``404 - Not Found`` + + The requested content could not be found. The content will include + further information, as a JSON object, if available. The structure + will contain two keys, ``error`` and ``reason``. For example: + + .. code-block:: javascript + + {"error":"not_found","reason":"no_db_file"} + +- ``405 - Resource Not Allowed`` + + A request was made using an invalid HTTP request type for the URL + requested. For example, you have requested a ``PUT`` when a ``POST`` + is required. Errors of this type can also triggered by invalid URL + strings. + +- ``406 - Not Acceptable`` + + The requested content type is not supported by the server. + +- ``409 - Conflict`` + + Request resulted in an update conflict. + +- ``412 - Precondition Failed`` + + The request headers from the client and the capabilities of the + server do not match. + +- ``415 - Bad Content Type`` + + The content types supported, and the content type of the information + being requested or submitted indicate that the content type is not + supported. + +- ``416 - Requested Range Not Satisfiable`` + + The range specified in the request header cannot be satisfied by the + server. + +- ``417 - Expectation Failed`` + + When sending documents in bulk, the bulk load operation failed. + +- ``500 - Internal Server Error`` + + The request was invalid, either because the supplied JSON was + invalid, or invalid information was supplied as part of the request. + +.. _api-overview: + +CouchDB API Overview +==================== + +The components of the API URL path help determine the part of the +CouchDB server that is being accessed. The result is the structure of +the URL request both identifies and effectively describes the area of +the database you are accessing. + +As with all URLs, the individual components are separated by a forward +slash. + +As a general rule, URL components and JSON fields starting with the +``_`` (underscore) character represent a special component or entity +within the server or returned object. For example, the URL fragment +``/_all_dbs`` gets a list of all of the databases in a CouchDB instance. + +The remainder of the URL API structure can be divided up according to +the URL structure. The different sections are divided as follows: + +- ``/db`` + + Database methods, related to adding, updating or deleting databases, + and setting database parameters and operations. For more detailed + information, see :ref:`api-db`. + +- ``/db/doc`` + + Document methods, those that create, store, update or delete CouchDB + documents and their attachments. For more information, see :ref:`api-doc`. + +- ``/db/_local/local-doc`` + + Document methods, those that create, store, update or delete CouchDB + documents only within the local database. Local documents are not + synchronized with other databases. For more information, see + :ref:`api-local`. + +- ``/db/_design/design-doc`` + + Design documents provide the methods and structure for recovering + information from a CouchDB database in the form of views, shows and + lists. For more information, see :ref:`api-design`. + +- ``/_special`` + + Special methods that obtain or set information about the CouchDB + instance, including methods for configuring replication, accessing + the logs, and generate Universally Unique IDs (UUIDs). For more + information, see :ref:`api-misc`. + +- ``/_config`` + + Methods for getting, and settings, CouchDB configuration parameters. + For more information, see :ref:`api-config`. diff --git a/share/doc/src/api/authn.rst b/share/doc/src/api/authn.rst new file mode 100644 index 000000000..bac198b19 --- /dev/null +++ b/share/doc/src/api/authn.rst @@ -0,0 +1,41 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +====================== +Authentication Methods +====================== + +.. todo:: 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: + ++--------+-------------------------+-------------------------------------------+ +| Method | Path | Description | ++========+=========================+===========================================+ +| GET | /_oauth/access_token | TBC | ++--------+-------------------------+-------------------------------------------+ +| GET | /_oauth/authorize | TBC | ++--------+-------------------------+-------------------------------------------+ +| POST | /_oauth/authorize | TBC | ++--------+-------------------------+-------------------------------------------+ +| GET | /_oauth/request_token | TBC | ++--------+-------------------------+-------------------------------------------+ +| GET | /_session | Returns cookie based login user | +| | | information | ++--------+-------------------------+-------------------------------------------+ +| POST | /_session | Do cookie based user login | ++--------+-------------------------+-------------------------------------------+ +| DELETE | /_session | Logout cookie based user | ++--------+-------------------------+-------------------------------------------+ diff --git a/share/doc/src/api/configuration.rst b/share/doc/src/api/configuration.rst new file mode 100644 index 000000000..6c2c58841 --- /dev/null +++ b/share/doc/src/api/configuration.rst @@ -0,0 +1,297 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _api-config: + +===================== +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: + ++--------+-------------------------+-------------------------------------------+ +| Method | Path | Description | ++========+=========================+===========================================+ +| GET | /_config | Obtain a list of the entire server | +| | | configuration | ++--------+-------------------------+-------------------------------------------+ +| GET | /_config/section | Get all the configuration values for the | +| | | specified section | ++--------+-------------------------+-------------------------------------------+ +| GET | /_config/section/key | Get a specific section/configuration value| ++--------+-------------------------+-------------------------------------------+ +| PUT | /_config/section/key | Set the specified configuration value | ++--------+-------------------------+-------------------------------------------+ +| DELETE | /_config/section/key | Delete the current setting | ++--------+-------------------------+-------------------------------------------+ + +``GET /_config`` +================ + +* **Method**: ``GET /_config`` +* **Request**: None +* **Response**: Returns a structure configuration name and value pairs, + organized by section +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **200**: + Request completed successfully. + +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: + +.. code-block:: http + + GET http://couchdb:5984/_config + Accept: application/json + +The response is the JSON structure: + +.. code-block:: javascript + + { + "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`` +======================== + +* **Method**: ``GET /_config/section`` +* **Request**: None +* **Response**: All the configuration values within a specified section +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **200**: + Request completed successfully. + +Gets the configuration structure for a single section. For example, to +retrieve the CouchDB configuration section values: + +.. code-block:: http + + GET http://couchdb:5984/_config/couchdb + Accept: application/json + +The returned JSON contains just the configuration values for this +section: + +.. code-block:: javascript + + { + "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`` +============================ + +* **Method**: ``GET /_config/section/key`` +* **Request**: None +* **Response**: Value of the specified key/section +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **200**: + Request completed successfully. + +Gets a single configuration value from within a specific configuration +section. For example, to obtain the current log level: + +.. code-block:: http + + GET http://couchdb:5984/_config/log/level + Accept: application/json + +Returns the string of the log level: + +.. code-block:: javascript + + "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. + +.. _api-put-config: + +``PUT /_config/section/key`` +============================ + +* **Method**: ``PUT /_config/section/key`` +* **Request**: Value structure +* **Response**: Previous value +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **200**: + Configuration option updated successfully + + * **500**: + Error setting configuration + +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: + +.. code-block:: http + + 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`` +=============================== + +* **Method**: ``DELETE /_config/section/key`` +* **Request**: None +* **Response**: Previous value +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **409**: + Supplied revision is incorrect or missing + +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: + +.. code-block:: http + + DELETE http://couchdb:5984/_config/uuids/algorithm + Content-Type: application/json + +The returned value is the last configured UUID function: + +.. code-block:: javascript + + "random" diff --git a/share/doc/src/api/database.rst b/share/doc/src/api/database.rst new file mode 100644 index 000000000..826adaad7 --- /dev/null +++ b/share/doc/src/api/database.rst @@ -0,0 +1,1463 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _api-db: + +================ +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: + ++--------+-------------------------+-------------------------------------------+ +| Method | Path | Description | ++========+=========================+===========================================+ +| GET | /db | Returns database information | ++--------+-------------------------+-------------------------------------------+ +| PUT | /db | Create a new database | ++--------+-------------------------+-------------------------------------------+ +| DELETE | /db | Delete an existing database | ++--------+-------------------------+-------------------------------------------+ +| GET | /db/_all_docs | Returns a built-in view of all documents | +| | | in this database | ++--------+-------------------------+-------------------------------------------+ +| POST | /db/_all_docs | Returns certain rows from the built-in | +| | | view of all documents | ++--------+-------------------------+-------------------------------------------+ +| POST | /db/_bulk_docs | Insert multiple documents in to the | +| | | database in a single request | ++--------+-------------------------+-------------------------------------------+ +| GET | /db/_changes | Returns changes for the given database | ++--------+-------------------------+-------------------------------------------+ +| POST | /db/_compact | Starts a compaction for the database | ++--------+-------------------------+-------------------------------------------+ +| POST | /db/_compact/design-doc | Starts a compaction for all the views in | +| | | the selected design document | ++--------+-------------------------+-------------------------------------------+ +| POST | /db/_ensure_full_commit | Makes sure all uncommitted changes are | +| | | written and synchronized to the disk | ++--------+-------------------------+-------------------------------------------+ +| POST | /db/_missing_revs | Given a list of document revisions, | +| | | returns the document revisions that do not| +| | | exist in the database | ++--------+-------------------------+-------------------------------------------+ +| POST | /db/_purge | Purge some historical documents entirely | +| | | from database history | ++--------+-------------------------+-------------------------------------------+ +| POST | /db/_revs_diff | Given a list of document revisions, | +| | | returns differences between the given | +| | | revisions and ones that are in the | +| | | database | ++--------+-------------------------+-------------------------------------------+ +| GET | /db/_revs_limit | Gets the limit of historical revisions to | +| | | store for a single document in the | +| | | database | ++--------+-------------------------+-------------------------------------------+ +| PUT | /db/_revs_limit | Sets the limit of historical revisions to | +| | | store for a single document in the | +| | | database | ++--------+-------------------------+-------------------------------------------+ +| GET | /db/_security | Returns the special security object for | +| | | the database | ++--------+-------------------------+-------------------------------------------+ +| PUT | /db/_security | Sets the special security object for the | +| | | database | ++--------+-------------------------+-------------------------------------------+ +| POST | /db/_temp_view | Execute a given view function for all | +| | | documents and return the result | ++--------+-------------------------+-------------------------------------------+ +| POST | /db/_view_cleanup | Removes view files that are not used by | +| | | any design document | ++--------+-------------------------+-------------------------------------------+ + +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: + +.. code-block:: http + + GET /recipes + +For clarity, the form below is used in the URL paths: + +.. code-block:: http + + GET /db + +Where ``db`` is the name of any database. + +.. _api-get-db: + +``GET /db`` +=========== + +* **Method**: ``GET /db`` +* **Request**: None +* **Response**: Information about the database in JSON format +* **Admin Privileges Required**: no +* **Return Codes**: + + * **404**: + The requested content could not be found. The returned content will include + further information, as a JSON object, if available. + +Gets information about the specified database. For example, to retrieve +the information for the database ``recipe``: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + { + "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: + ++----------------------------------+-------------------------------------------+ +| Field | Description | ++==================================+===========================================+ +| committed_update_seq | The number of committed update. | ++----------------------------------+-------------------------------------------+ +| compact_running | Set to true if the database compaction | +| | routine is operating on this database. | ++----------------------------------+-------------------------------------------+ +| db_name | The name of the database. | ++----------------------------------+-------------------------------------------+ +| disk_format_version | The version of the physical format used | +| | for the data when it is stored on disk. | ++----------------------------------+-------------------------------------------+ +| disk_size | Size in bytes of the data as stored on the| +| | disk. Views indexes are not included in | +| | the calculation. | ++----------------------------------+-------------------------------------------+ +| doc_count | A count of the documents in the specified | +| | database. | ++----------------------------------+-------------------------------------------+ +| doc_del_count | Number of deleted documents | ++----------------------------------+-------------------------------------------+ +| instance_start_time | Timestamp of when the database was | +| | created, expressed in milliseconds since | +| | the epoch. | ++----------------------------------+-------------------------------------------+ +| purge_seq | The number of purge operations on the | +| | database. | ++----------------------------------+-------------------------------------------+ +| update_seq | The current number of updates to the | +| | database. | ++----------------------------------+-------------------------------------------+ + +``PUT /db`` +=========== + +* **Method**: ``PUT /db`` +* **Request**: None +* **Response**: JSON success statement +* **Admin Privileges Required**: no +* **Return Codes**: + + * **400**: + Invalid database name + + * **412**: + Database already exists + +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``: + +.. code-block:: http + + PUT http://couchdb:5984/recipes + Content-Type: application/json + +The returned content contains the JSON status: + +.. code-block:: javascript + + { + "ok" : true + } + +Anything should be treated as an error, and the problem should be taken +form the HTTP response code. + +``DELETE /db`` +============== + +* **Method**: ``DELETE /db`` +* **Request**: None +* **Response**: JSON success statement +* **Admin Privileges Required**: no +* **Return Codes**: + + * **200**: + Database has been deleted + + * **404**: + The requested content could not be found. The returned content will include + further information, as a JSON object, if available. + +Deletes the specified database, and all the documents and attachments +contained within it. + +To delete the database ``recipes`` you would send the request: + +.. code-block:: http + + DELETE http://couchdb:5984/recipes + Content-Type: application/json + +If successful, the returned JSON will indicate success + +.. code-block:: javascript + + { + "ok" : true + } + +.. _api-changes: + +``GET /db/_changes`` +==================== + +* **Method**: ``GET /db/_changes`` +* **Request**: None +* **Response**: JSON success statement +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: doc_ids + + * **Description**: Specify the list of documents IDs to be filtered + * **Optional**: yes + * **Type**: json + * **Default**: none + + * **Argument**: feed + + * **Description**: Type of feed + * **Optional**: yes + * **Type**: string + * **Default**: normal + * **Supported Values**: + + * **continuous**: Continuous (non-polling) mode + * **longpoll**: Long polling mode + * **normal**: Normal mode + + * **Argument**: filter + + * **Description**: Filter function from a design document to get updates + * **Optional**: yes + * **Type**: string + * **Default**: none + * **Supported Values**: + + * **Argument**: heartbeat + + * **Description**: Period after which an empty line is sent during longpoll + or continuous + * **Optional**: yes + * **Type**: numeric + * **Default**: 60000 + * **Quantity**: milliseconds + + * **Argument**: include_docs + + * **Description**: Include the document with the result + * **Optional**: yes + * **Type**: boolean + * **Default**: false + + * **Argument**: limit + + * **Description**: Maximum number of rows rows to return + * **Optional**: yes + * **Type**: numeric + * **Default**: none + + * **Argument**: since + + * **Description**: Start the results from changes immediately after the + specified sequence number + * **Optional**: yes + * **Type**: numeric + * **Default**: 0 + +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 + + .. code-block:: http + + 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 changes and 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. + ++----------------------------------+-------------------------------------------+ +| Field | Description | ++==================================+===========================================+ +| last_seq | Last change sequence number. | ++----------------------------------+-------------------------------------------+ +| results [array] | Changes made to a database | ++----------------------------------+-------------------------------------------+ +| changes [array] | List of changes, field-by-field, for this | +| | document | ++----------------------------------+-------------------------------------------+ +| id | Document ID | ++----------------------------------+-------------------------------------------+ +| seq | Update sequence number | ++----------------------------------+-------------------------------------------+ + +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: + +.. code-block:: http + + 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 :ref:`changes`. + +.. _api-compact: + +``POST /db/_compact`` +===================== + +* **Method**: ``POST /db/_compact`` +* **Request**: None +* **Response**: JSON success statement +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **202**: + Compaction request has been accepted + + * **404**: + The requested content could not be found. The returned content will include + further information, as a JSON object, if available. + +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 :ref:`api-get-db`. + +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 +:ref:`api-get-db`. + +You can also obtain a list of running processes to determine whether +compaction is currently running. See :ref:`active-tasks`. + +.. _api-compact-ddoc: + +``POST /db/_compact/design-doc`` +================================ + +* **Method**: ``POST /db/_compact/design-doc`` +* **Request**: None +* **Response**: JSON success statement +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **202**: + Compaction request has been accepted + + * **404**: + The requested content could not be found. The returned content will include + further information, as a JSON object, if available. + +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: + +.. code-block:: http + + 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): + +.. code-block:: javascript + + { + "ok" : true + } + + +``POST /db/_view_cleanup`` +========================== + +* **Method**: ``POST /db/_view_cleanup`` +* **Request**: None +* **Response**: JSON success statement +* **Admin Privileges Required**: yes + +Cleans up the cached view output on disk for a given view. For example: + +.. code-block:: http + + POST http://couchdb:5984/recipes/_view_cleanup + Content-Type: application/json + +If the request is successful, a basic status message us returned: + +.. code-block:: javascript + + { + "ok" : true + } + + +``POST /db/_ensure_full_commit`` +================================ + +* **Method**: ``POST /db/_ensure_full_commit`` +* **Request**: None +* **Response**: JSON success statement +* **Admin Privileges Required**: no +* **Return Codes**: + + * **202**: + Commit completed successfully + + * **404**: + The requested content could not be found. The returned content will include + further information, as a JSON object, if available. + + +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: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + { + "ok" : true, + "instance_start_time" : "1288186189373361" + } + +``POST /db/_bulk_docs`` +======================= + +* **Method**: ``POST /db/_bulk_docs`` +* **Request**: JSON of the docs and updates to be applied +* **Response**: JSON success statement +* **Admin Privileges Required**: no +* **Return Codes**: + + * **201**: + Document(s) have been created or updated + +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: + ++----------------------------------+-------------------------------------------+ +| Field | Description | ++==================================+===========================================+ +| all_or_nothing (optional) | Sets the database commit mode to use | +| | all-or-nothing semantics | ++----------------------------------+-------------------------------------------+ +| docs [array] | Bulk Documents Document | ++----------------------------------+-------------------------------------------+ +| _id (optional) | List of changes, field-by-field, for this | +| | document | ++----------------------------------+-------------------------------------------+ +| _rev (optional) | Document ID | ++----------------------------------+-------------------------------------------+ +| _deleted (optional) | Update sequence number | ++----------------------------------+-------------------------------------------+ + +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: + +.. code-block:: javascript + + { + "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: + +.. code-block:: http + + 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 :ref:`bulk-semantics` for more +information. Conflicts and validation errors when updating documents in +bulk must be handled separately; see :ref:`bulk-validation`. + +Updating Documents in Bulk +-------------------------- + +The bulk document update procedure is similar to the insertion +procedure, except that you must specify the document ID and current +revision for every document in the bulk update JSON string. + +For example, you could send the following request: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + [ + { + "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 document 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 :ref:`bulk-semantics` for more +information. Conflicts and validation errors when updating documents in +bulk must be handled separately; see :ref:`bulk-validation`. + +.. _bulk-semantics: + +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: + + .. code-block:: javascript + + [ + { + "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: + + .. code-block:: javascript + + [ + { + "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 below: + +* **Transaction Mode**: ``Non-atomic`` + + * **Transaction**: ``Insert`` + + * **Cause**: Requested document ID already exists + * **Resolution**: Resubmit with different document ID, or update the + existing document + + * **Transaction**: ``Update`` + + * **Cause**: Revision missing or incorrect + * **Resolution**: Resubmit with correct revision + +* **Transaction Mode**: ``All-or-nothing`` + + * **Transaction**: ``Insert`` / ``Update`` + + * **Cause**: Additional revision inserted + * **Resolution**: Resolve conflicted revisions + +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-validation: + +Bulk Document Validation and Conflict Errors +-------------------------------------------- + +The JSON returned by the ``_bulk_docs`` operation consists of an array +of JSON structures, one for each document in the original submission. +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: + ++----------------------------------+-------------------------------------------+ +| Field | Description | ++==================================+===========================================+ +| docs [array] | Bulk Documents Document | ++----------------------------------+-------------------------------------------+ +| id | Document ID | ++----------------------------------+-------------------------------------------+ +| error | Error type | ++----------------------------------+-------------------------------------------+ +| reason | Error string with extended reason | ++----------------------------------+-------------------------------------------+ + +When a document (or document revision) is not correctly committed 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: + + .. code-block:: javascript + + throw({forbidden: 'invalid recipe ingredient'}); + + The error returned will be: + + .. code-block:: javascript + + { + "id" : "7f7638c86173eb440b8890839ff35433", + "error" : "forbidden", + "reason" : "invalid recipe ingredient" + } + + +``POST /db/_temp_view`` +======================= + +* **Method**: ``POST /db/_temp_view`` +* **Request**: JSON with the temporary view definition +* **Response**: Temporary view result set +* **Admin Privileges Required**: yes + +Creates (and executes) a temporary view based on the view function +supplied in the JSON request. For example: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + { + "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. + +``POST /db/_purge`` +=================== + +* **Method**: ``POST /db/_purge`` +* **Request**: JSON of the document IDs/revisions to be purged +* **Response**: JSON structure with purged documents and purge sequence +* **Admin Privileges Required**: no + +A database purge permanently removes the references to deleted documents +from the database. Deleting a document within CouchDB does not actually +remove the document 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 references 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 + :ref:`api-compact`), and compact views (see :ref:`api-compact-ddoc`). + +To perform a purge operation you must send a request including the JSON +of the document IDs that you want to purge. For example: + +.. code-block:: http + + 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. + +.. code-block:: javascript + + { + "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`` +===================== + +* **Method**: ``GET /db/_all_docs`` +* **Request**: None +* **Response**: JSON object containing document information, ordered by the + document ID +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: descending + + * **Description**: Return the documents in descending by key order + * **Optional**: yes + * **Type**: boolean + * **Default**: false + + * **Argument**: endkey + + * **Description**: Stop returning records when the specified key is reached + * **Optional**: yes + * **Type**: string + + * **Argument**: endkey_docid + + * **Description**: Stop returning records when the specified document ID is + reached + * **Optional**: yes + * **Type**: string + + * **Argument**: group + + * **Description**: Group the results using the reduce function to a group + or single row + * **Optional**: yes + * **Type**: boolean + * **Default**: false + + * **Argument**: group_level + + * **Description**: Specify the group level to be used + * **Optional**: yes + * **Type**: numeric + + * **Argument**: include_docs + + * **Description**: Include the full content of the documents in the return + * **Optional**: yes + * **Type**: boolean + * **Default**: false + + * **Argument**: inclusive_end + + * **Description**: Specifies whether the specified end key should be + included in the result + * **Optional**: yes + * **Type**: boolean + * **Default**: true + + * **Argument**: key + + * **Description**: Return only documents that match the specified key + * **Optional**: yes + * **Type**: string + + * **Argument**: limit + + * **Description**: Limit the number of the returned documents to the + specified number + * **Optional**: yes + * **Type**: numeric + + * **Argument**: reduce + + * **Description**: Use the reduction function + * **Optional**: yes + * **Type**: boolean + * **Default**: true + + * **Argument**: skip + + * **Description**: Skip this number of records before starting to return + the results + * **Optional**: yes + * **Type**: numeric + * **Default**: 0 + + * **Argument**: stale + + * **Description**: Allow the results from a stale view to be used + * **Optional**: yes + * **Type**: string + * **Default**: + * **Supported Values**: + + * **ok**: Allow stale views + + * **Argument**: startkey + + * **Description**: Return records starting with the specified key + * **Optional**: yes + * **Type**: string + + * **Argument**: startkey_docid + + * **Description**: Return records starting with the specified document ID + * **Optional**: yes + * **Type**: string + +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. + ++----------------------------------+-------------------------------------------+ +| Field | Description | ++==================================+===========================================+ +| offset | Offset where the document list started | ++----------------------------------+-------------------------------------------+ +| rows [array] | Array of document object | ++----------------------------------+-------------------------------------------+ +| total_rows | Number of documents in the database/view | ++----------------------------------+-------------------------------------------+ +| update_seq | Current update sequence for the database | ++----------------------------------+-------------------------------------------+ + +By default the information returned contains only the document ID and +revision. For example, the request: + +.. code-block:: http + + GET http://couchdb:5984/recipes/_all_docs + Accept: application/json + +Returns the following structure: + +.. code-block:: javascript + + { + "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`` +====================== + +* **Method**: ``POST /db/_all_docs`` +* **Request**: JSON of the document IDs you want included +* **Response**: JSON of the returned view +* **Admin Privileges Required**: no + +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 +:ref:`api-get-doc` requests. + +The request body should contain a list of the keys to be returned as an +array to a ``keys`` object. For example: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + { + "total_rows" : 2666, + "rows" : [ + { + "value" : { + "rev" : "1-a3544d296de19e6f5b932ea77d886942" + }, + "id" : "Zingylemontart", + "key" : "Zingylemontart" + }, + { + "value" : { + "rev" : "1-91635098bfe7d40197a1b98d7ee085fc" + }, + "id" : "Yogurtraita", + "key" : "Yogurtraita" + } + ], + "offset" : 0 + } + +``POST /db/_missing_revs`` +========================== + +* **Method**: ``POST /db/_missing_revs`` +* **Request**: JSON list of document revisions +* **Response**: JSON of missing revisions +* **Admin Privileges Required**: no + +``POST /db/_revs_diff`` +======================= + +* **Method**: ``POST /db/_revs_diff`` +* **Request**: JSON list of document revisions +* **Response**: JSON list of differences from supplied document/revision list +* **Admin Privileges Required**: no + +``GET /db/_security`` +===================== + +* **Method**: ``GET /db/_security`` +* **Request**: None +* **Response**: JSON of the security object +* **Admin Privileges Required**: no + +Gets the current security 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: + +.. code-block:: javascript + + { + "admins" : { + "roles" : [], + "names" : [ + "mc", + "slp" + ] + }, + "readers" : { + "roles" : [], + "names" : [ + "tim", + "brian" + ] + } + } + +Security object structure is: + +* **admins**: Roles/Users with admin privileges + + * **roles** [array]: List of roles with parent privilege + * **users** [array]: List of users with parent privilege + +* **readers**: Roles/Users with reader privileges + + * **roles** [array]: List of roles with parent privilege + * **users** [array]: List of users with parent privilege + +.. note:: + If the security object for a database has never been set, then the + value returned will be empty. + +``PUT /db/_security`` +===================== + +* **Method**: ``PUT /db/_security`` +* **Request**: JSON specifying the admin and user security for the database +* **Response**: JSON status message +* **Admin Privileges Required**: no + +Sets the security object for the given database.For example, to set the +security object for the ``recipes`` database: + +.. code-block:: javascript + + 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: + +.. code-block:: javascript + + { + "ok" : true + } + +``GET /db/_revs_limit`` +======================= + +* **Method**: ``GET /db/_revs_limit`` +* **Request**: None +* **Response**: The current revision limit setting +* **Admin Privileges Required**: no + + +Gets the current ``revs_limit`` (revision limit) setting. + +For example to get the current limit: + +.. code-block:: http + + GET http://couchdb:5984/recipes/_revs_limit + Content-Type: application/json + +The returned information is the current setting as a numerical scalar: + +.. code-block:: javascript + + 1000 + +``PUT /db/_revs_limit`` +======================= + +* **Method**: ``PUT /db/_revs_limit`` +* **Request**: A scalar integer of the revision limit setting +* **Response**: Confirmation of setting of the revision limit +* **Admin Privileges Required**: no + +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: + +.. code-block:: http + + PUT http://couchdb:5984/recipes/_revs_limit + Content-Type: application/json + + 100 + +If the setting was successful, a JSON status object will be returned: + +.. code-block:: javascript + + { + "ok" : true + } + +.. _JSON object: #table-couchdb-api-db_db-json-changes diff --git a/share/doc/src/api/dbmaint.rst b/share/doc/src/api/dbmaint.rst new file mode 100644 index 000000000..9b2019d75 --- /dev/null +++ b/share/doc/src/api/dbmaint.rst @@ -0,0 +1,15 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +==================== +Database Maintenance +==================== diff --git a/share/doc/src/api/design.rst b/share/doc/src/api/design.rst new file mode 100644 index 000000000..38bdd0bd4 --- /dev/null +++ b/share/doc/src/api/design.rst @@ -0,0 +1,1264 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _api-design: + +======================= +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`` +============================== + +* **Method**: ``GET /db/_design/design-doc`` +* **Request**: None +* **Response**: JSON of the existing design document +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Specify the revision to return + * **Optional**: yes + * **Type**: string + + * **Argument**: revs + + * **Description**: Return a list of the revisions for the document + * **Optional**: yes + * **Type**: boolean + * **Supported Values**: + + * **true**: Includes the revisions + + * **Argument**: revs_info + + * **Description**: Return a list of detailed revision information for the + document + * **Optional**: yes + * **Type**: boolean + * **Supported Values**: + + * **true**: Includes the revisions + +Returns the specified design document, ``design-doc`` from the specified +``db``. For example, to retrieve the design document ``recipes`` you +would send the following request: + +.. code-block:: http + + GET http://couchdb:5984/recipes/_design/recipes + Content-Type: application/json + +The returned string will be the JSON of the design document: + +.. code-block:: javascript + + { + "_id" : "_design/recipes", + "_rev" : "5-39f56a392b86bbee57e2138921346406" + "language" : "javascript", + "views" : { + "by_recipe" : { + "map" : "function(doc) { if (doc.title != null) emit(doc.title, doc) }" + }, + }, + } + +A list of the revisions can be obtained by using the ``revs`` query +argument, or an extended list of revisions using the ``revs_info`` query +argument. This operates in the same way as for other documents. Fur +further examples, see :ref:`api-get-doc`. + +``PUT /db/_design/design-doc`` +============================== + +* **Method**: ``PUT /db/_design/design-doc`` +* **Request**: JSON of the design document +* **Response**: JSON status +* **Admin Privileges Required**: no + +Upload the specified design document, ``design-doc``, to the specified +database. The design document should follow the definition of a design +document, as summarised in the following table. + +* **_id**: Design Document ID +* **_rev**: Design Document Revision +* **views**: View + + * **viewname**: View Definition + + * **map**: Map Function for View + * **reduce (optional)**: Reduce Function for View + +For more information on writing views, see :ref:`views`. + +``DELETE /db/_design/design-doc`` +================================= + +* **Method**: ``DELETE /db/_design/design-doc`` +* **Request**: None +* **Response**: JSON of deleted design document +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Current revision of the document for validation + * **Optional**: yes + * **Type**: string + +* **HTTP Headers** + + * **Header**: ``If-Match`` + + * **Description**: Current revision of the document for validation + * **Optional**: yes + +* **Return Codes**: + + * **409**: + Supplied revision is incorrect or missing + +Delete an existing design document. Deleting a design document also +deletes all of the associated view indexes, and recovers the +corresponding space on disk for the indexes in question. + +To delete, you must specify the current revision of the design document +using the ``rev`` query argument. + +For example: + +.. code-block:: http + + DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8 + Content-Type: application/json + +The response contains the delete document ID and revision: + +.. code-block:: javascript + + { + "id" : "recipe/_design/recipes" + "ok" : true, + "rev" : "3-7a05370bff53186cb5d403f861aca154", + } + +``COPY /db/_design/design-doc`` +=============================== + +* **Method**: ``COPY /db/_design/design-doc`` +* **Request**: None +* **Response**: JSON of the new document and revision +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Revision to copy from + * **Optional**: yes + * **Type**: string + +* **HTTP Headers** + + * **Header**: ``Destination`` + + * **Description**: Destination document (and optional revision) + * **Optional**: no + +The ``COPY`` command (non-standard HTTP) copies an existing design +document to a new or existing document. + +The source design document is specified on the request line, with the +``Destination`` HTTP Header of the request specifying the target +document. + +Copying a Design Document +------------------------- + +To copy the latest version of a design document to a new document you +specify the base document and target document: + +.. code-block:: http + + COPY http://couchdb:5984/recipes/_design/recipes + Content-Type: application/json + Destination: /recipes/_design/recipelist + +The above request copies the design document ``recipes`` to the new +design document ``recipelist``. The response is the ID and revision of +the new document. + +.. code-block:: javascript + + { + "id" : "recipes/_design/recipelist" + "rev" : "1-9c65296036141e575d32ba9c034dd3ee", + } + +.. note:: + Copying a design document does automatically reconstruct the view + indexes. These will be recreated, as with other views, the first + time the new view is accessed. + +Copying from a Specific Revision +-------------------------------- + +To copy *from* a specific version, use the ``rev`` argument to the query +string: + +.. code-block:: http + + COPY http://couchdb:5984/recipes/_design/recipes?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5 + Content-Type: application/json + Destination: recipes/_design/recipelist + +The new design document will be created using the specified revision of +the source document. + +Copying to an Existing Design Document +-------------------------------------- + +To copy to an existing document, you must specify the current revision +string for the target document, using the ``rev`` parameter to the +``Destination`` HTTP Header string. For example: + +.. code-block:: http + + COPY http://couchdb:5984/recipes/_design/recipes + Content-Type: application/json + Destination: recipes/_design/recipelist?rev=1-9c65296036141e575d32ba9c034dd3ee + +The return value will be the new revision of the copied document: + +.. code-block:: javascript + + { + "id" : "recipes/_design/recipes" + "rev" : "2-55b6a1b251902a2c249b667dab1c6692", + } + +``GET /db/_design/design-doc/attachment`` +========================================= + +* **Method**: ``GET /db/_design/design-doc/attachment`` +* **Request**: None +* **Response**: Returns the attachment data +* **Admin Privileges Required**: no + +Returns the file attachment ``attachment`` associated with the design +document ``/_design_/design-doc``. The raw data of the associated +attachment is returned (just as if you were accessing a static file. The +returned HTTP ``Content-type`` will be the same as the content type set +when the document attachment was submitted into the database. + +``PUT /db/_design/design-doc/attachment`` +========================================= + +* **Method**: ``PUT /db/_design/design-doc/attachment`` +* **Request**: Raw document data +* **Response**: JSON document status +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Current document revision + * **Optional**: no + * **Type**: string + +* **HTTP Headers** + + * **Header**: ``Content-Length`` + + * **Description**: Length (bytes) of the attachment being uploaded + * **Optional**: no + + * **Header**: ``Content-Type`` + + * **Description**: MIME type for the uploaded attachment + * **Optional**: no + + * **Header**: ``If-Match`` + + * **Description**: Current revision of the document for validation + * **Optional**: yes + +Upload the supplied content as an attachment to the specified design +document (``/_design/design-doc``). The ``attachment`` name provided +must be a URL encoded string. You must also supply either the ``rev`` +query argument or the ``If-Match`` HTTP header for validation, and the +HTTP headers (to set the 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: + +.. code-block:: http + + PUT http://couchdb:5984/recipes/_design/recipes/view.css?rev=7-f7114d4d81124b223283f3e89eee043e + Content-Length: 39 + Content-Type: text/plain + + div.recipetitle { + font-weight: bold; + } + +Or by using the ``If-Match`` HTTP header: + +.. code-block:: http + + PUT http://couchdb:5984/recipes/FishStew/basic + If-Match: 7-f7114d4d81124b223283f3e89eee043e + Content-Length: 39 + Content-Type: text/plain + + div.recipetitle { + font-weight: bold; + } + +The returned JSON contains the new document information: + +.. code-block:: javascript + + { + "id" : "_design/recipes" + "ok" : true, + "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5", + } + +.. note:: + Uploading an attachment updates the corresponding document revision. + Revisions are tracked for the parent document, not individual attachments. + +``DELETE /db/_design/design-doc/attachment`` +============================================ + +* **Method**: ``DELETE /db/_design/design-doc/attachment`` +* **Request**: None +* **Response**: JSON status +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Current document revision + * **Optional**: no + * **Type**: string + +* **HTTP Headers** + + * **Header**: ``If-Match`` + + * **Description**: Current revision of the document for validation + * **Optional**: yes + +* **Return Codes**: + + * **200**: + Attachment deleted successfully + * **409**: + Supplied revision is incorrect or missing + +Deletes the attachment ``attachment`` to the specified +``_design/design-doc``. You must supply the ``rev`` argument with the +current revision to delete the attachment. + +For example to delete the attachment ``view.css`` from the design +document ``recipes``: + +.. code-block:: http + + DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a + +The returned JSON contains the updated revision information for the +parent document: + +.. code-block:: javascript + + { + "id" : "_design/recipes" + "ok" : true, + "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c", + } + +``GET /db/_design/design-doc/_info`` +==================================== + +* **Method**: ``GET /db/_design/design-doc/_info`` +* **Request**: None +* **Response**: JSON of the design document information +* **Admin Privileges Required**: no + +Obtains information about a given design document, including the index, +index size and current status of the design document and associated +index information. + +For example, to get the information for the ``recipes`` design document: + +.. code-block:: http + + GET http://couchdb:5984/recipes/_design/recipes/_info + Content-Type: application/json + +This returns the following JSON structure: + +.. code-block:: javascript + + { + "name" : "recipes" + "view_index" : { + "compact_running" : false, + "updater_running" : false, + "language" : "javascript", + "purge_seq" : 10, + "waiting_commit" : false, + "waiting_clients" : 0, + "signature" : "fc65594ee76087a3b8c726caf5b40687", + "update_seq" : 375031, + "disk_size" : 16491 + }, + } + +The individual fields in the returned JSON structure are detailed below: + +* **name**: Name/ID of Design Document +* **view_index**: View Index + + * **compact_running**: Indicates whether a compaction routine is currently + running on the view + * **disk_size**: Size in bytes of the view as stored on disk + * **language**: Language for the defined views + * **purge_seq**: The purge sequence that has been processed + * **signature**: MD5 signature of the views for the design document + * **update_seq**: The update sequence of the corresponding database that + has been indexed + * **updater_running**: Indicates if the view is currently being updated + * **waiting_clients**: Number of clients waiting on views from this design + document + * **waiting_commit**: Indicates if there are outstanding commits to the + underlying database that need to processed + +.. _api-get-view: + +.. _views: + +``GET /db/_design/design-doc/_view/view-name`` +============================================== + +* **Method**: ``GET /db/_design/design-doc/_view/view-name`` +* **Request**: None +* **Response**: JSON of the documents returned by the view +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: descending + + * **Description**: Return the documents in descending by key order + * **Optional**: yes + * **Type**: boolean + * **Default**: false + + * **Argument**: endkey + + * **Description**: Stop returning records when the specified key is reached + * **Optional**: yes + * **Type**: string + + * **Argument**: endkey_docid + + * **Description**: Stop returning records when the specified document + ID is reached + * **Optional**: yes + * **Type**: string + + * **Argument**: group + + * **Description**: Group the results using the reduce function to a + group or single row + * **Optional**: yes + * **Type**: boolean + * **Default**: false + + * **Argument**: group_level + + * **Description**: Specify the group level to be used + * **Optional**: yes + * **Type**: numeric + + * **Argument**: include_docs + + * **Description**: Include the full content of the documents in the return + * **Optional**: yes + * **Type**: boolean + * **Default**: false + + * **Argument**: inclusive_end + + * **Description**: Specifies whether the specified end key should be + included in the result + * **Optional**: yes + * **Type**: boolean + * **Default**: true + + * **Argument**: key + + * **Description**: Return only documents that match the specified key + * **Optional**: yes + * **Type**: string + + * **Argument**: limit + + * **Description**: Limit the number of the returned documents to the + specified number + * **Optional**: yes + * **Type**: numeric + + * **Argument**: reduce + + * **Description**: Use the reduction function + * **Optional**: yes + * **Type**: boolean + * **Default**: true + + * **Argument**: skip + + * **Description**: Skip this number of records before starting to return + the results + * **Optional**: yes + * **Type**: numeric + * **Default**: 0 + + * **Argument**: stale + + * **Description**: Allow the results from a stale view to be used + * **Optional**: yes + * **Type**: string + * **Default**: + * **Supported Values** + + * **ok**: Allow stale views + + * **Argument**: startkey + + * **Description**: Return records starting with the specified key + * **Optional**: yes + * **Type**: string + + * **Argument**: startkey_docid + + * **Description**: Return records starting with the specified document ID + * **Optional**: yes + * **Type**: string + + * **Argument**: update_seq + + * **Description**: Include the update sequence in the generated results + * **Optional**: yes + * **Type**: boolean + * **Default**: false + +Executes the specified ``view-name`` from the specified ``design-doc`` +design document. + +Querying Views and Indexes +-------------------------- + +The definition of a view within a design document also creates an index +based on the key information defined within each view. The production +and use of the index significantly increases the speed of access and +searching or selecting documents from the view. + +However, the index is not updated when new documents are added or +modified in the database. Instead, the index is generated or updated, +either when the view is first accessed, or when the view is accessed +after a document has been updated. In each case, the index is updated +before the view query is executed against the database. + +View indexes are updated incrementally in the following situations: + +- A new document has been added to the database. + +- A document has been deleted from the database. + +- A document in the database has been updated. + +View indexes are rebuilt entirely when the view definition changes. To +achieve this, a 'fingerprint' of the view definition is created when the +design document is updated. If the fingerprint changes, then the view +indexes are entirely rebuilt. This ensures that changes to the view +definitions are reflected in the view indexes. + +.. note:: + View index rebuilds occur when one view from the same the view group + (i.e. all the views defined within a single a design document) has + been determined as needing a rebuild. For example, if if you have a + design document with different views, and you update the database, + all three view indexes within the design document will be updated. + +Because the view is updated when it has been queried, it can result in a +delay in returned information when the view is accessed, especially if +there are a large number of documents in the database and the view index +does not exist. There are a number of ways to mitigate, but not +completely eliminate, these issues. These include: + +- Create the view definition (and associated design documents) on your + database before allowing insertion or updates to the documents. If + this is allowed while the view is being accessed, the index can be + updated incrementally. + +- Manually force a view request from the database. You can do this + either before users are allowed to use the view, or you can access + the view manually after documents are added or updated. + +- Use the ``/db/_changes`` method to monitor for changes to the + database and then access the view to force the corresponding view + index to be updated. See :ref:`api-changes` for more information. + +- Use a monitor with the ``update_notification`` section of the CouchDB + configuration file to monitor for changes to your database, and + trigger a view query to force the view to be updated. For more + information, see :ref:`update-notifications`. + +None of these can completely eliminate the need for the indexes to be +rebuilt or updated when the view is accessed, but they may lessen the +effects on end-users of the index update affecting the user experience. + +Another alternative is to allow users to access a 'stale' version of the +view index, rather than forcing the index to be updated and displaying +the updated results. Using a stale view may not return the latest +information, but will return the results of the view query using an +existing version of the index. + +For example, to access the existing stale view ``by_recipe`` in the +``recipes`` design document: + +.. code-block:: text + + http://couchdb:5984/recipes/_design/recipes/_view/by_recipe?stale=ok + +Accessing a stale view: + +- Does not trigger a rebuild of the view indexes, even if there have + been changes since the last access. + +- Returns the current version of the view index, if a current version + exists. + +- Returns an empty result set if the given view index does exist. + +As an alternative, you use the ``update_after`` value to the ``stale`` +parameter. This causes the view to be returned as a stale view, but for +the update process to be triggered after the view information has been +returned to the client. + +In addition to using stale views, you can also make use of the +``update_seq`` query argument. Using this query argument generates the +view information including the update sequence of the database from +which the view was generated. The returned value can be compared this to +the current update sequence exposed in the database information +(returned by :ref:`api-get-db`). + +Sorting Returned Rows +--------------------- + +Each element within the returned array is sorted using native UTF-8 +sorting according to the contents of the key portion of the emitted +content. The basic order of output is as follows: + +- ``null`` + +- ``false`` + +- ``true`` + +- Numbers + +- Text (case sensitive, lowercase first) + +- Arrays (according to the values of each element, in order) + +- Objects (according to the values of keys, in key order) + +You can reverse the order of the returned view information by using the +``descending`` query value set to true. For example, Retrieving the list +of recipes using the ``by_title`` (limited to 5 records) view: + +.. code-block:: javascript + + { + "offset" : 0, + "rows" : [ + { + "id" : "3-tiersalmonspinachandavocadoterrine", + "key" : "3-tier salmon, spinach and avocado terrine", + "value" : [ + null, + "3-tier salmon, spinach and avocado terrine" + ] + }, + { + "id" : "Aberffrawcake", + "key" : "Aberffraw cake", + "value" : [ + null, + "Aberffraw cake" + ] + }, + { + "id" : "Adukiandorangecasserole-microwave", + "key" : "Aduki and orange casserole - microwave", + "value" : [ + null, + "Aduki and orange casserole - microwave" + ] + }, + { + "id" : "Aioli-garlicmayonnaise", + "key" : "Aioli - garlic mayonnaise", + "value" : [ + null, + "Aioli - garlic mayonnaise" + ] + }, + { + "id" : "Alabamapeanutchicken", + "key" : "Alabama peanut chicken", + "value" : [ + null, + "Alabama peanut chicken" + ] + } + ], + "total_rows" : 2667 + } + +Requesting the same in descending order will reverse the entire view +content. For example the request + +.. code-block:: http + + GET http://couchdb:5984/recipes/_design/recipes/_view/by_title?limit=5&descending=true + Accept: application/json + Content-Type: application/json + +Returns the last 5 records from the view: + +.. code-block:: javascript + + { + "offset" : 0, + "rows" : [ + { + "id" : "Zucchiniinagrodolcesweet-sourcourgettes", + "key" : "Zucchini in agrodolce (sweet-sour courgettes)", + "value" : [ + null, + "Zucchini in agrodolce (sweet-sour courgettes)" + ] + }, + { + "id" : "Zingylemontart", + "key" : "Zingy lemon tart", + "value" : [ + null, + "Zingy lemon tart" + ] + }, + { + "id" : "Zestyseafoodavocado", + "key" : "Zesty seafood avocado", + "value" : [ + null, + "Zesty seafood avocado" + ] + }, + { + "id" : "Zabaglione", + "key" : "Zabaglione", + "value" : [ + null, + "Zabaglione" + ] + }, + { + "id" : "Yogurtraita", + "key" : "Yogurt raita", + "value" : [ + null, + "Yogurt raita" + ] + } + ], + "total_rows" : 2667 + } + +The sorting direction is applied before the filtering applied using the +``startkey`` and ``endkey`` query arguments. For example the following +query: + +.. code-block:: http + + GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?startkey=%22carrots%22&endkey=%22egg%22 + Accept: application/json + Content-Type: application/json + +Will operate correctly when listing all the matching entries between +“carrots” and ``egg``. If the order of output is reversed with the +``descending`` query argument, the view request will return no entries: + +.. code-block:: http + + GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22carrots%22&endkey=%22egg%22 + Accept: application/json + Content-Type: application/json + +The returned result is empty: + +.. code-block:: javascript + + { + "total_rows" : 26453, + "rows" : [], + "offset" : 21882 + } + +The results will be empty because the entries in the view are reversed +before the key filter is applied, and therefore the ``endkey`` of “egg” +will be seen before the ``startkey`` of “carrots”, resulting in an empty +list. + +Instead, you should reverse the values supplied to the ``startkey`` and +``endkey`` parameters to match the descending sorting applied to the +keys. Changing the previous example to: + +.. code-block:: http + + GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22egg%22&endkey=%22carrots%22 + Accept: application/json + Content-Type: application/json + +Specifying Start and End Values +------------------------------- + +.. todo:: Specifying Start and End Values + +The ``startkey`` and ``endkey`` query arguments can be used to specify +the range of values to be displayed when querying the view. + +Using Limits and Skipping Rows +------------------------------ + +.. todo:: Using Limits and Skipping Rows + +TBC + +View Reduction and Grouping +--------------------------- + +.. todo:: View Reduction and Grouping + +TBC + +``POST /db/_design/design-doc/_view/view-name`` +=============================================== + +* **Method**: ``POST /db/_design/design-doc/_view/view-name`` +* **Request**: List of keys to be returned from specified view +* **Response**: JSON of the documents returned by the view +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: descending + + * **Description**: Return the documents in descending by key order + * **Optional**: yes + * **Type**: boolean + * **Default**: false + + * **Argument**: endkey + + * **Description**: Stop returning records when the specified key is reached + * **Optional**: yes + * **Type**: string + + * **Argument**: endkey_docid + + * **Description**: Stop returning records when the specified document ID + is reached + * **Optional**: yes + * **Type**: string + + * **Argument**: group + + * **Description**: Group the results using the reduce function to a group + or single row + * **Optional**: yes + * **Type**: boolean + * **Default**: false + + * **Argument**: group_level + + * **Description**: Specify the group level to be used + * **Optional**: yes + * **Type**: numeric + + * **Argument**: include_docs + + * **Description**: Include the full content of the documents in the return + * **Optional**: yes + * **Type**: boolean + * **Default**: false + + * **Argument**: inclusive_end + + * **Description**: Specifies whether the specified end key should be + included in the result + * **Optional**: yes + * **Type**: boolean + * **Default**: true + + * **Argument**: key + + * **Description**: Return only documents that match the specified key + * **Optional**: yes + * **Type**: string + + * **Argument**: limit + + * **Description**: Limit the number of the returned documents to the + specified number + * **Optional**: yes + * **Type**: numeric + + * **Argument**: reduce + + * **Description**: Use the reduction function + * **Optional**: yes + * **Type**: boolean + * **Default**: true + + * **Argument**: skip + + * **Description**: Skip this number of records before starting to return + the results + * **Optional**: yes + * **Type**: numeric + * **Default**: 0 + + * **Argument**: stale + + * **Description**: Allow the results from a stale view to be used + * **Optional**: yes + * **Type**: string + * **Default**: + * **Supported Values**: + + * **ok**: Allow stale views + + * **Argument**: startkey + + * **Description**: Return records starting with the specified key + * **Optional**: yes + * **Type**: string + + * **Argument**: startkey_docid + + * **Description**: Return records starting with the specified document ID + * **Optional**: yes + * **Type**: string + + * **Argument**: update_seq + + * **Description**: Include the update sequence in the generated results + * **Optional**: yes + * **Type**: boolean + * **Default**: false + +Executes the specified ``view-name`` from the specified ``design-doc`` +design document. Unlike the ``GET`` method for accessing views, the +``POST`` method supports the specification of explicit keys to be +retrieved from the view results. The remainder of the ``POST`` view +functionality is identical to the :ref:`api-get-view` API. + +For example, the request below will return all the recipes where the key +for the view matches either “claret” or “clear apple cider” : + +.. code-block:: http + + POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient + Content-Type: application/json + + { + "keys" : [ + "claret", + "clear apple juice" + ] + } + + +The returned view data contains the standard view information, but only +where the keys match. + +.. code-block:: javascript + + { + "total_rows" : 26484, + "rows" : [ + { + "value" : [ + "Scotch collops" + ], + "id" : "Scotchcollops", + "key" : "claret" + }, + { + "value" : [ + "Stand pie" + ], + "id" : "Standpie", + "key" : "clear apple juice" + } + ], + "offset" : 6324 + } + +Multi-document Fetching +----------------------- + +By combining the ``POST`` method to a given view with the +``include_docs=true`` query argument you can obtain multiple documents +from a database. The result is more efficient than using multiple +:ref:`api-get-doc` requests. + +For example, sending the following request for ingredients matching +“claret” and “clear apple juice”: + +.. code-block:: http + + POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?include_docs=true + Content-Type: application/json + + { + "keys" : [ + "claret", + "clear apple juice" + ] + } + +Returns the full document for each recipe: + +.. code-block:: javascript + + { + "offset" : 6324, + "rows" : [ + { + "doc" : { + "_id" : "Scotchcollops", + "_rev" : "1-bcbdf724f8544c89697a1cbc4b9f0178", + "cooktime" : "8", + "ingredients" : [ + { + "ingredient" : "onion", + "ingredtext" : "onion, peeled and chopped", + "meastext" : "1" + }, + ... + ], + "keywords" : [ + "cook method.hob, oven, grill@hob", + "diet@wheat-free", + "diet@peanut-free", + "special collections@classic recipe", + "cuisine@british traditional", + "diet@corn-free", + "diet@citrus-free", + "special collections@very easy", + "diet@shellfish-free", + "main ingredient@meat", + "occasion@christmas", + "meal type@main", + "diet@egg-free", + "diet@gluten-free" + ], + "preptime" : "10", + "servings" : "4", + "subtitle" : "This recipe comes from an old recipe book of 1683 called 'The Gentlewoman's Kitchen'. This is an excellent way of making a rich and full-flavoured meat dish in a very short time.", + "title" : "Scotch collops", + "totaltime" : "18" + }, + "id" : "Scotchcollops", + "key" : "claret", + "value" : [ + "Scotch collops" + ] + }, + { + "doc" : { + "_id" : "Standpie", + "_rev" : "1-bff6edf3ca2474a243023f2dad432a5a", + "cooktime" : "92", + "ingredients" : [ + ... ], + "keywords" : [ + "diet@dairy-free", + "diet@peanut-free", + "special collections@classic recipe", + "cuisine@british traditional", + "diet@corn-free", + "diet@citrus-free", + "occasion@buffet party", + "diet@shellfish-free", + "occasion@picnic", + "special collections@lunchbox", + "main ingredient@meat", + "convenience@serve with salad for complete meal", + "meal type@main", + "cook method.hob, oven, grill@hob / oven", + "diet@cow dairy-free" + ], + "preptime" : "30", + "servings" : "6", + "subtitle" : "Serve this pie with pickled vegetables and potato salad.", + "title" : "Stand pie", + "totaltime" : "437" + }, + "id" : "Standpie", + "key" : "clear apple juice", + "value" : [ + "Stand pie" + ] + } + ], + "total_rows" : 26484 + } + +``GET /db/_design/design-doc/_show/show-name`` +=============================================== + +.. todo:: GET /db/_design/design-doc/_show/show-name + +* **Method**: ``GET /db/_design/design-doc/_show/show-name`` +* **Request**: None +* **Response**: Returns the result of the show +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: details + + * **Description**: Indicates whether details should be included + * **Optional**: yes + * **Type**: string + + * **Argument**: format + + * **Description**: Format of the returned information + * **Optional**: yes + * **Type**: string + +``POST /db/_design/design-doc/_show/show-name/doc`` +=================================================== + +.. todo:: POST /db/_design/design-doc/_show/show-name/doc + +* **Method**: ``POST /db/_design/design-doc/_show/show-name`` +* **Request**: Custom data +* **Response**: Returns the result of the show +* **Admin Privileges Required**: no + +``GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name`` +========================================================================= + +.. todo:: GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name + +* **Method**: ``GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name`` +* **Request**: TBC +* **Response**: TBC +* **Admin Privileges Required**: no + +``POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name`` +========================================================================== + +.. todo:: POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name + +* **Method**: ``POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name`` +* **Request**: TBC +* **Response**: TBC +* **Admin Privileges Required**: no + +``GET /db/_design/design-doc/_list/list-name/view-name`` +======================================================== + +.. todo:: GET /db/_design/design-doc/_list/list-name/view-name + +* **Method**: ``GET /db/_design/design-doc/_list/list-name/view-name`` +* **Request**: TBC +* **Response**: TBC +* **Admin Privileges Required**: no + +``POST /db/_design/design-doc/_list/list-name/view-name`` +========================================================= + +.. todo:: POST /db/_design/design-doc/_list/list-name/view-name + +* **Method**: ``POST /db/_design/design-doc/_list/list-name/view-name`` +* **Request**: TBC +* **Response**: TBC +* **Admin Privileges Required**: no + +``PUT /db/_design/design-doc/_update/updatename/doc`` +===================================================== + +.. todo:: POST /db/_design/design-doc/_update/updatename/doc + +* **Method**: ``POST /db/_design/design-doc/_update/updatename/doc`` +* **Request**: TBC +* **Response**: TBC +* **Admin Privileges Required**: no + +``POST /db/_design/design-doc/_update/updatename`` +================================================== + +.. todo:: PUT /db/_design/design-doc/_update/updatename/doc + +* **Method**: ``PUT /db/_design/design-doc/_update/updatename/doc`` +* **Request**: TBC +* **Response**: TBC +* **Admin Privileges Required**: no + +``ALL /db/_design/design-doc/_rewrite/rewrite-name/anything`` +============================================================= + +.. todo:: ALL /db/_design/design-doc/_rewrite/rewrite-name/anything + +* **Method**: ``ALL /db/_design/design-doc/_rewrite/rewrite-name/anything`` +* **Request**: TBC +* **Response**: TBC +* **Admin Privileges Required**: no diff --git a/share/doc/src/api/documents.rst b/share/doc/src/api/documents.rst new file mode 100644 index 000000000..c58d00427 --- /dev/null +++ b/share/doc/src/api/documents.rst @@ -0,0 +1,973 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _api-doc: + +================ +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: + ++--------+-------------------------+-------------------------------------------+ +| Method | Path | Description | ++========+=========================+===========================================+ +| POST | /db | Create a new document | ++--------+-------------------------+-------------------------------------------+ +| GET | /db/doc | Returns the latest revision of the | +| | | document | ++--------+-------------------------+-------------------------------------------+ +| HEAD | /db/doc | Returns bare information in the HTTP | +| | | Headers for the document | ++--------+-------------------------+-------------------------------------------+ +| PUT | /db/doc | Inserts a new document, or new version | +| | | of an existing document | ++--------+-------------------------+-------------------------------------------+ +| DELETE | /db/doc | Deletes the document | ++--------+-------------------------+-------------------------------------------+ +| COPY | /db/doc | Copies the document | ++--------+-------------------------+-------------------------------------------+ +| GET | /db/doc/attachment | Gets the attachment of a document | ++--------+-------------------------+-------------------------------------------+ +| PUT | /db/doc/attachment | Adds an attachment of a document | ++--------+-------------------------+-------------------------------------------+ +| DELETE | /db/doc/attachment | Deletes an attachment of a document | ++--------+-------------------------+-------------------------------------------+ + +``POST /db`` +============ + +* **Method**: ``POST /db`` +* **Request**: JSON of the new document +* **Response**: JSON with the committed document information +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: batch + + * **Description**: Allow document store request to be batched with others + * **Optional**: yes + * **Type**: string + * **Supported Values**: asd + * **ok**: Enable + +* **Return Codes**: + + * **201**: + Document has been created successfully + * **409**: + Conflict - a document with the specified document ID already exists + +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: + +.. code-block:: http + + 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 generated ID and revision +information: + +.. code-block:: javascript + + { + "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``: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + { + "id" : "FishStew", + "ok" : true, + "rev" : "1-9c65296036141e575d32ba9c034dd3ee" + } + + +.. _api-batch-writes: + +UUID generation algorithms +-------------------------- + +CouchDB supports a number of different UUID generation algorithms for use +in situations where a user-specified UUID does not make sense. These +can be set simply by `PUT http://couchdb:5984/_config/uuids/algorithm`. + + ++---------------+---------------------+------------------------------------+ +| Algorithm | Description | Sample UUID | ++===============+=====================+====================================+ +| random | 128 bits of pure | - 43febce5675468a5467fb5467ce9e6c0 | +| | random awesomeness | | ++---------------+---------------------+------------------------------------+ +| sequential | monotonically | - f755c413badf66b22941313f9f001e28 | +| | increasing ids with | - f755c413badf66b22941313f9f0024ca | +| | random increments | - f755c413badf66b22941313f9f00332c | ++---------------+---------------------+------------------------------------+ +| utc_random | time since start of | - 04cfa405381205204f75100d0241ccc3 | +| | epoch, as 14 hex | - 04cfa4059c48e76e7c054bbe033dd8db | +| | digits, followed by | - 04cfa405fce10b0df4c08f95e667cd2f | +| | 18 random digits. | | ++---------------+---------------------+------------------------------------+ +| utc_id | time since start of | - 04cfa718b00848_i_am_in_yer_couch | +| & additional | epoch, as 14 hex | - 04cfa71d377aef_i_am_in_yer_couch | +| parameter | digits, followed by | - 04cfa71e0deabd_i_am_in_yer_couch | +| | utc_id_suffix. | | ++---------------+---------------------+------------------------------------+ + +.. Impact of UUID choices:: + The choice of UUID has a signficant impact on the layout of the B-tree, + prior to compaction. For example, a sequential UUID algorithm during + uploading thousands of documents, will avoid the need to rewrite many + intermediate B-tree nodes. A random UUID algorithm may require rewriting + intermediate nodes on a regular basis, with a corresponding decrease of + throughput, and significant wasted space due to the append-only B-tree + design. It is generally recommended to set your own UUIDs, or use the + sequential algorithm unless you have a specific need and take into account + the likely need for compaction to re-balance the B-tree and reclaim wasted + space. + + +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 :ref:`api-put-attachment`). + +* **_id** (optional): Document ID +* **_rev** (optional): Revision ID (when updating an existing document) +* **_attachments** (optional): Document Attachment + + * **filename**: Attachment information + + * **content_type**: MIME Content type string + * **data**: File attachment content, Base64 encoded + +The ``filename`` will be the attachment name. For example, when sending +the JSON structure below: + +.. code-block:: javascript + + { + "_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 :ref:`api-get-attachment`. + +The document data embedded in to the structure must be encoded using +base64. + +.. _api-get-doc: + +``GET /db/doc`` +=============== + +* **Method**: ``GET /db/doc`` +* **Request**: None +* **Response**: Returns the JSON for the document +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: conflicts + + * **Description**: Returns the conflict tree for the document. + * **Optional**: yes + * **Type**: boolean + * **Default**: false + * **Supported Values**: + + * **true**: Includes the revisions + + * **Argument**: rev + + * **Description**: Specify the revision to return + * **Optional**: yes + * **Type**: string + * **Supported Values**: + + * **true**: Includes the revisions + + * **Argument**: revs + + * **Description**: Return a list of the revisions for the document + * **Optional**: yes + * **Type**: boolean + + * **Argument**: revs_info + + * **Description**: Return a list of detailed revision information for the + document + * **Optional**: yes + * **Type**: boolean + * **Supported Values**: + + * **true**: Includes the revisions + +* **Return Codes**: + + * **200**: + Document retrieved + * **400**: + The format of the request or revision was invalid + * **404**: + The specified document or revision cannot be found, or has been deleted + * **409**: + Conflict - a document with the specified document ID already exists + +Returns the specified ``doc`` from the specified ``db``. For example, to +retrieve the document with the id ``FishStew`` you would send the +following request: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + { + "_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 associated 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: + +.. code-block:: javascript + + { + "_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: + +* **_id** (optional): Document ID +* **_rev** (optional): Revision ID (when updating an existing document) +* **_attachments** (optional): Document Attachment + + * **filename**: Attachment information + + * **content_type**: MIME Content type string + * **length**: Length (bytes) of the attachment data + * **revpos**: Revision where this attachment exists + * **stub**: Indicates whether the attachment is a stub + +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: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + { + "servings" : 4, + "subtitle" : "Delicious with a green salad", + "_id" : "FishStew", + "title" : "Irish Fish Stew", + "_revisions" : { + "ids" : [ + "a1a9b39ee3cc39181b796a69cb48521c", + "7c4740b4dcf26683e941d6641c00c39d", + "9c65296036141e575d32ba9c034dd3ee" + ], + "start" : 3 + }, + "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" + } + +* **_id** (optional): Document ID +* **_rev** (optional): Revision ID (when updating an existing document) +* **_revisions**: CouchDB Document Revisions + + * **ids** [array]: Array of valid revision IDs, in reverse order + (latest first) + * **start**: Prefix number for the latest revision + +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: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + { + "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" + } + +* **_id** (optional): Document ID +* **_rev** (optional): Revision ID (when updating an existing document) +* **_revs_info** [array]: CouchDB Document Extended Revision Info + + * **rev**: Full revision string + * **status**: Status of the revision + +Obtaining a Specific Revision +----------------------------- + +To get a specific revision, use the ``rev`` argument to the request, and +specify the full revision number: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + { + "_id" : "FishStew", + "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d", + "servings" : 4, + "subtitle" : "Delicious with a green salad", + "title" : "Fish Stew" + } + +``HEAD /db/doc`` +================ + +* **Method**: ``HEAD /db/doc`` +* **Request**: None +* **Response**: None +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Specify the revision to return + * **Optional**: yes + * **Type**: string + + * **Argument**: revs + + * **Description**: Return a list of the revisions for the document + * **Optional**: yes + * **Type**: boolean + + * **Argument**: revs_info + + * **Description**: Return a list of detailed revision information for the + document + * **Optional**: yes + * **Type**: boolean + +* **Return Codes**: + + * **404**: + The specified document or revision cannot be found, or has been deleted + +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: + +.. code-block:: http + + HEAD http://couchdb:5984/recipes/FishStew + Content-Type: application/json + + +Returns the following HTTP Headers: + +.. code-block:: javascript + + 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: + +.. code-block:: http + + 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 + +.. _api-put-doc: + +``PUT /db/doc`` +=============== + +* **Method**: ``PUT /db/doc`` +* **Request**: JSON of the new document, or updated version of the existed + document +* **Response**: JSON of the document ID and revision +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: batch + + * **Description**: Allow document store request to be batched with others + * **Optional**: yes + * **Type**: string + * **Supported Values**: + + * **ok**: Enable + +* **HTTP Headers** + + * **Header**: ``If-Match`` + + * **Description**: Current revision of the document for validation + * **Optional**: yes + +* **Return Codes**: + + * **201**: + Document has been created successfully + * **202**: + Document accepted for writing (batch mode) + + +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 document ``FishStew``, you would send the +following request: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + { + "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: + +.. code-block:: http + + 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: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + { + "id" : "FishStew99", + "ok" : true, + "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea" + } + +For information on batched writes, which can provide improved +performance, see :ref:`api-batch-writes`. + +.. _api-del-doc: + +``DELETE /db/doc`` +================== + +* **Method**: ``DELETE /db/doc`` +* **Request**: None +* **Response**: JSON of the deleted revision +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Current revision of the document for validation + * **Optional**: yes + * **Type**: string + +* **HTTP Headers** + + * **Header**: ``If-Match`` + + * **Description**: Current revision of the document for validation + * **Optional**: yes + +* **Return Codes**: + + * **409**: + Revision is missing, invalid or not the latest + +Deletes the specified document from the database. You must supply the +current (latest) revision, either by using the ``rev`` parameter to +specify the revision: + +.. code-block:: http + + DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c + Content-Type: application/json + +Alternatively, you can use ETags with the ``If-Match`` field: + +.. code-block:: http + + DELETE http://couchdb:5984/recipes/FishStew + If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c + Content-Type: application/json + + +The returned JSON contains the document ID, revision and status: + +.. code-block:: javascript + + { + "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. + +.. _api-copy-doc: + +``COPY /db/doc`` +================ + +* **Method**: ``COPY /db/doc`` +* **Request**: None +* **Response**: JSON of the new document and revision +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Revision to copy from + * **Optional**: yes + * **Type**: string + +* **HTTP Headers** + + * **Header**: ``Destination`` + + * **Description**: Destination document (and optional revision) + * **Optional**: no + +* **Return Codes**: + + * **201**: + Document has been copied and created successfully + * **409**: + Revision is missing, invalid or not the latest + +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: + +.. code-block:: http + + 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. + +.. code-block:: javascript + + { + "id" : "IrishFishStew", + "rev" : "1-9c65296036141e575d32ba9c034dd3ee" + } + +Copying from a Specific Revision +-------------------------------- + +To copy *from* a specific version, use the ``rev`` argument to the query +string: + +.. code-block:: http + + COPY http://couchdb:5984/recipes/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: + +.. code-block:: http + + 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: + +.. code-block:: javascript + + { + "id" : "IrishFishStew", + "rev" : "2-55b6a1b251902a2c249b667dab1c6692" + } + +.. _api-get-attachment: + +``GET /db/doc/attachment`` +========================== + +* **Method**: ``GET /db/doc/attachment`` +* **Request**: None +* **Response**: Returns the attachment data +* **Admin Privileges Required**: no + +Returns the file attachment ``attachment`` associated with the document +``doc``. The raw data of the associated attachment is returned (just as +if you were accessing a static file. The returned HTTP ``Content-type`` +will be the same as the content type set when the document attachment +was submitted into the database. + +.. _api-put-attachment: + +``PUT /db/doc/attachment`` +========================== + +* **Method**: ``PUT /db/doc/attachment`` +* **Request**: Raw document data +* **Response**: JSON document status +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Current document revision + * **Optional**: no + * **Type**: string + +* **HTTP Headers** + + * **Header**: ``Content-Length`` + + * **Description**: Length (bytes) of the attachment being uploaded + * **Optional**: no + + * **Header**: ``Content-Type`` + + * **Description**: MIME type for the uploaded attachment + * **Optional**: no + + * **Header**: ``If-Match`` + + * **Description**: Current revision of the document for validation + * **Optional**: yes + +* **Return Codes**: + + * **201**: + Attachment has been accepted + +Upload the supplied content as an attachment to the specified document +(``doc``). The ``attachment`` name provided must be a URL encoded +string. You must also supply either the ``rev`` query argument or the +``If-Match`` HTTP header for validation, and the HTTP headers (to set +the attachment content type). The content type is used when the +attachment is requested as the corresponding content-type in the +returned document header. + +For example, you could upload a simple text document using the following +request: + +.. code-block:: http + + PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca + Content-Length: 10 + Content-Type: text/plain + + Roast it + +Or by using the ``If-Match`` HTTP header: + +.. code-block:: http + + PUT http://couchdb:5984/recipes/FishStew/basic + If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca + Content-Length: 10 + Content-Type: text/plain + + Roast it + +The returned JSON contains the new document information: + +.. code-block:: javascript + + { + "id" : "FishStew", + "ok" : true, + "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74" + } + +.. note:: Uploading an attachment updates the corresponding document revision. + Revisions are tracked for the parent document, not individual + attachments. + +Updating an Existing Attachment +------------------------------- + +Uploading an attachment using an existing attachment name will update +the corresponding stored content of the database. Since you must supply +the revision information to add an attachment to a document, this serves +as validation to update the existing attachment. + +``DELETE /db/doc/attachment`` +============================= + +* **Method**: ``DELETE /db/doc/attachment`` +* **Request**: None +* **Response**: JSON status +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Current document revision + * **Optional**: no + * **Type**: string + +* **HTTP Headers** + + * **Header**: ``If-Match`` + + * **Description**: Current revision of the document for validation + * **Optional**: yes + +* **Return Codes**: + + * **200**: + Attachment deleted successfully + * **409**: + Supplied revision is incorrect or missing + +Deletes the attachment ``attachment`` to the specified ``doc``. You must +supply the ``rev`` argument with the current revision to delete the +attachment. + +For example to delete the attachment ``basic`` from the recipe +``FishStew``: + +.. code-block:: http + + DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74 + Content-Type: application/json + + + +The returned JSON contains the updated revision information: + +.. code-block:: javascript + + { + "id" : "FishStew", + "ok" : true, + "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e" + } + +.. _JSON object: #table-couchdb-api-db_db-json-changes +.. _POST: #couchdb-api-dbdoc_db_post diff --git a/share/doc/src/api/local.rst b/share/doc/src/api/local.rst new file mode 100644 index 000000000..780c0306a --- /dev/null +++ b/share/doc/src/api/local.rst @@ -0,0 +1,169 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _api-local: + +======================================== +Local (non-replicating) Document Methods +======================================== + +The Local (non-replicating) document interface allows you to create +local documents that are not replicated to other databases. These +documents can be used to hold configuration or other information that is +required specifically on the local CouchDB instance. + +Local documents have the following limitations: + +- Local documents are not replicated to other databases. + +- The ID of the local document must be known for the document to + accessed. You cannot obtain a list of local documents from the + database. + +- Local documents are not output by views, or the ``_all_docs`` view. + +Local documents can be used when you want to store configuration or +other information for the current (local) instance of a given database. + +A list of the available methods and URL paths are provided below: + ++--------+-------------------------+-------------------------------------------+ +| Method | Path | Description | ++========+=========================+===========================================+ +| GET | /db/_local/local-doc | Returns the latest revision of the | +| | | non-replicated document | ++--------+-------------------------+-------------------------------------------+ +| PUT | /db/_local/local-doc | Inserts a new version of the | +| | | non-replicated document | ++--------+-------------------------+-------------------------------------------+ +| DELETE | /db/_local/local-doc | Deletes the non-replicated document | ++--------+-------------------------+-------------------------------------------+ +| COPY | /db/_local/local-doc | Copies the non-replicated document | ++--------+-------------------------+-------------------------------------------+ + +``GET /db/_local/local-doc`` +============================ + +* **Method**: ``GET /db/_local/local-doc`` +* **Request**: None +* **Response**: JSON of the returned document +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Specify the revision to return + * **Optional**: yes + * **Type**: string + * **Supported Values**: + + * **true**: Includes the revisions + + * **Argument**: revs + + * **Description**: Return a list of the revisions for the document + * **Optional**: yes + * **Type**: boolean + + * **Argument**: revs_info + + * **Description**: Return a list of detailed revision information for + the document + * **Optional**: yes + * **Type**: boolean + * **Supported Values** + + * **true**: Includes the revisions + +* **Return Codes**: + + * **400**: + The format of the request or revision was invalid + * **404**: + The specified document or revision cannot be found, or has been deleted + +Gets the specified local document. The semantics are identical to +accessing a standard document in the specified database, except that the +document is not replicated. See :ref:`api-get-doc`. + +``PUT /db/_local/local-doc`` +============================ + +* **Method**: ``PUT /db/_local/local-doc`` +* **Request**: JSON of the document +* **Response**: JSON with the committed document information +* **Admin Privileges Required**: no +* **Return Codes**: + + * **201**: + Document has been created successfully + +Stores the specified local document. The semantics are identical to +storing a standard document in the specified database, except that the +document is not replicated. See :ref:`api-put-doc`. + +``DELETE /db/_local/local-doc`` +=============================== + +* **Method**: ``DELETE /db/_local/local-doc`` +* **Request**: None +* **Response**: JSON with the deleted document information +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Current revision of the document for validation + * **Optional**: yes + * **Type**: string + +* **HTTP Headers** + + * **Header**: ``If-Match`` + + * **Description**: Current revision of the document for validation + * **Optional**: yes + +* **Return Codes**: + + * **409**: + Supplied revision is incorrect or missing + +Deletes the specified local document. The semantics are identical to +deleting a standard document in the specified database, except that the +document is not replicated. See :ref:`api-del-doc`. + +``COPY /db/_local/local-doc`` +============================= + +* **Method**: ``COPY /db/_local/local-doc`` +* **Request**: None +* **Response**: JSON of the copied document +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: rev + + * **Description**: Revision to copy from + * **Optional**: yes + * **Type**: string + +* **HTTP Headers** + + * **Header**: ``Destination`` + + * **Description**: Destination document (and optional revision) + * **Optional**: no + +Copies the specified local document. The semantics are identical to +copying a standard document in the specified database, except that the +document is not replicated. See :ref:`api-copy-doc`. diff --git a/share/doc/src/api/misc.rst b/share/doc/src/api/misc.rst new file mode 100644 index 000000000..f9562ae90 --- /dev/null +++ b/share/doc/src/api/misc.rst @@ -0,0 +1,805 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _api-misc: + +===================== +Miscellaneous Methods +===================== + +The CouchDB Miscellaneous interface provides the basic interface to a +CouchDB server for obtaining CouchDB information and getting and setting +configuration information. + +A list of the available methods and URL paths are provided below: + ++--------+-------------------------+-------------------------------------------+ +| Method | Path | Description | ++========+=========================+===========================================+ +| GET | / | Get the welcome message and version | +| | | information | ++--------+-------------------------+-------------------------------------------+ +| GET | /_active_tasks | Obtain a list of the tasks running in the| +| | | server | ++--------+-------------------------+-------------------------------------------+ +| GET | /_all_dbs | Get a list of all the DBs | ++--------+-------------------------+-------------------------------------------+ +| GET | /_log | Return the server log file | ++--------+-------------------------+-------------------------------------------+ +| POST | /_replicate | Set or cancel replication | ++--------+-------------------------+-------------------------------------------+ +| POST | /_restart | Restart the server | ++--------+-------------------------+-------------------------------------------+ +| GET | /_stats | Return server statistics | ++--------+-------------------------+-------------------------------------------+ +| GET | /_utils | CouchDB administration interface (Futon) | ++--------+-------------------------+-------------------------------------------+ +| GET | /_uuids | Get generated UUIDs from the server | ++--------+-------------------------+-------------------------------------------+ +| GET | /favicon.ico | Get the site icon | ++--------+-------------------------+-------------------------------------------+ + +``GET /`` +========= + +* **Method**: ``GET /`` +* **Request**: None +* **Response**: Welcome message and version +* **Admin Privileges Required**: no +* **Return Codes**: + + * **200**: + Request completed successfully. + +Accessing the root of a CouchDB instance returns meta information about +the instance. The response is a JSON structure containing information +about the server, including a welcome message and the version of the +server. + +.. code-block:: javascript + + { + "couchdb" : "Welcome", + "version" : "1.0.1" + } + +.. _active-tasks: + +``GET /_active_tasks`` +====================== + +* **Method**: ``GET /_active_tasks`` +* **Request**: None +* **Response**: List of running tasks, including the task type, name, status + and process ID +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **200**: + Request completed successfully. + +You can obtain a list of active tasks by using the ``/_active_tasks`` +URL. The result is a JSON array of the currently running tasks, with +each task being described with a single object. For example: + +.. code-block:: javascript + + [ + { + "pid" : "<0.11599.0>", + "status" : "Copied 0 of 18369 changes (0%)", + "task" : "recipes", + "type" : "Database Compaction" + } + ] + +The returned structure includes the following fields for each task: + +* **tasks** [array]: Active Task + + * **pid**:Process ID + * **status**: Task status message + * **task**: Task name + * **type**: Operation Type + +For operation type, valid values include: + +- ``Database Compaction`` + +- ``Replication`` + +- ``View Group Compaction`` + +- ``View Group Indexer`` + +``GET /_all_dbs`` +================= + +* **Method**: ``GET /_all_dbs`` +* **Request**: None +* **Response**: JSON list of DBs +* **Admin Privileges Required**: no +* **Return Codes**: + + * **200**: + Request completed successfully. + +Returns a list of all the databases in the CouchDB instance. For +example: + +.. code-block:: http + + GET http://couchdb:5984/_all_dbs + Accept: application/json + +The return is a JSON array: + +.. code-block:: javascript + + [ + "_users", + "contacts", + "docs", + "invoices", + "locations" + ] + +``GET /_log`` +============= + +* **Method**: ``GET /_log`` +* **Request**: None +* **Response**: Log content +* **Admin Privileges Required**: yes +* **Query Arguments**: + + * **Argument**: bytes + + * **Description**: Bytes to be returned + * **Optional**: yes + * **Type**: numeric + * **Default**: 1000 + + * **Argument**: offset + + * **Description**: Offset in bytes where the log tail should be started + * **Optional**: yes + * **Type**: numeric + * **Default**: 0 + +* **Return Codes**: + + * **200**: + Request completed successfully. + +Gets the CouchDB log, equivalent to accessing the local log file of the +corresponding CouchDB instance. + +When you request the log, the response is returned as plain (UTF-8) +text, with an HTTP ``Content-type`` header as ``text/plain``. + +For example, the request: + +.. code-block:: http + + GET http://couchdb:5984/_log + Accept: */* + +The raw text is returned: + +.. code-block:: text + + [Wed, 27 Oct 2010 10:49:42 GMT] [info] [<0.23338.2>] 192.168.0.2 - - 'PUT' /authdb 401 + [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /recipes/FishStew 200 + [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /_session 200 + [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.24199.2>] 192.168.0.116 - - 'GET' / 200 + [Wed, 27 Oct 2010 13:03:38 GMT] [info] [<0.24207.2>] 192.168.0.116 - - 'GET' /_log?offset=5 200 + +If you want to pick out specific parts of the log information you can +use the ``bytes`` argument, which specifies the number of bytes to be +returned, and ``offset``, which specifies where the reading of the log +should start, counted back from the end. For example, if you use the +following request: + +.. code-block:: http + + GET /_log?bytes=500&offset=2000 + +Reading of the log will start at 2000 bytes from the end of the log, and +500 bytes will be shown. + +.. _replicate: + +``POST /_replicate`` +==================== + +.. todo:: POST /_replicate :: what response is? + +* **Method**: ``POST /_replicate`` +* **Request**: Replication specification +* **Response**: TBD +* **Admin Privileges Required**: yes +* **Query Arguments**: + + * **Argument**: bytes + + * **Description**: Bytes to be returned + * **Optional**: yes + * **Type**: numeric + * **Default**: 1000 + + * **Argument**: offset + + * **Description**: Offset in bytes where the log tail should be started + * **Optional**: yes + * **Type**: numeric + * **Default**: 0 + +* **Return Codes**: + + * **200**: + Replication request successfully completed + * **202**: + Continuous replication request has been accepted + * **404**: + Either the source or target DB is not found + * **500**: + JSON specification was invalid + +Request, configure, or stop, a replication operation. + +The specification of the replication request is controlled through the +JSON content of the request. The JSON should be an object with the +fields defining the source, target and other options. The fields of the +JSON request are shown in the table below: + +* **cancel (optional)**: Cancels the replication +* **continuous (optional)**: Configure the replication to be continuous +* **create_target (optional)**: Creates the target database +* **doc_ids (optional)**: Array of document IDs to be synchronized +* **proxy (optional)**: Address of a proxy server through which replication + should occur +* **source**: Source database name or URL +* **target**: Target database name or URL + +Replication Operation +--------------------- + +The aim of the replication is that at the end of the process, all active +documents on the source database are also in the destination database +and all documents that were deleted in the source databases are also +deleted (if they exist) on the destination database. + +Replication can be described as either push or pull replication: + +- *Pull replication* is where the ``source`` is the remote CouchDB + instance, and the ``destination`` is the local database. + + Pull replication is the most useful solution to use if your source + database has a permanent IP address, and your destination (local) + database may have a dynamically assigned IP address (for example, + through DHCP). This is particularly important if you are replicating + to a mobile or other device from a central server. + +- *Push replication* is where the ``source`` is a local database, and + ``destination`` is a remote database. + +Specifying the Source and Target Database +----------------------------------------- + +You must use the URL specification of the CouchDB database if you want +to perform replication in either of the following two situations: + +- Replication with a remote database (i.e. another instance of CouchDB + on the same host, or a different host) + +- Replication with a database that requires authentication + +For example, to request replication between a database local to the +CouchDB instance to which you send the request, and a remote database +you might use the following request: + +.. code-block:: http + + POST http://couchdb:5984/_replicate + Content-Type: application/json + Accept: application/json + + { + "source" : "recipes", + "target" : "http://coucdb-remote:5984/recipes", + } + + +In all cases, the requested databases in the ``source`` and ``target`` +specification must exist. If they do not, an error will be returned +within the JSON object: + +.. code-block:: javascript + + { + "error" : "db_not_found" + "reason" : "could not open http://couchdb-remote:5984/ol1ka/", + } + +You can create the target database (providing your user credentials +allow it) by adding the ``create_target`` field to the request object: + +.. code-block:: http + + POST http://couchdb:5984/_replicate + Content-Type: application/json + Accept: application/json + + { + "create_target" : true + "source" : "recipes", + "target" : "http://couchdb-remote:5984/recipes", + } + +The ``create_target`` field is not destructive. If the database already +exists, the replication proceeds as normal. + +Single Replication +------------------ + +You can request replication of a database so that the two databases can +be synchronized. By default, the replication process occurs one time and +synchronizes the two databases together. For example, you can request a +single synchronization between two databases by supplying the ``source`` +and ``target`` fields within the request JSON content. + +.. code-block:: http + + POST http://couchdb:5984/_replicate + Content-Type: application/json + Accept: application/json + + { + "source" : "recipes", + "target" : "recipes-snapshot", + } + +In the above example, the databases ``recipes`` and ``recipes-snapshot`` +will be synchronized. These databases are local to the CouchDB instance +where the request was made. The response will be a JSON structure +containing the success (or failure) of the synchronization process, and +statistics about the process: + +.. code-block:: javascript + + { + "ok" : true, + "history" : [ + { + "docs_read" : 1000, + "session_id" : "52c2370f5027043d286daca4de247db0", + "recorded_seq" : 1000, + "end_last_seq" : 1000, + "doc_write_failures" : 0, + "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT", + "start_last_seq" : 0, + "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT", + "missing_checked" : 0, + "docs_written" : 1000, + "missing_found" : 1000 + } + ], + "session_id" : "52c2370f5027043d286daca4de247db0", + "source_last_seq" : 1000 + } + +The structure defines the replication status, as described in the table +below: + +* **history [array]**: Replication History + + * **doc_write_failures**: Number of document write failures + * **docs_read**: Number of documents read + * **docs_written**: Number of documents written to target + * **end_last_seq**: Last sequence number in changes stream + * **end_time**: Date/Time replication operation completed + * **missing_checked**: Number of missing documents checked + * **missing_found**: Number of missing documents found + * **recorded_seq**: Last recorded sequence number + * **session_id**: Session ID for this replication operation + * **start_last_seq**: First sequence number in changes stream + * **start_time**: Date/Time replication operation started + +* **ok**: Replication status +* **session_id**: Unique session ID +* **source_last_seq**: Last sequence number read from source database + +Continuous Replication +---------------------- + +Synchronization of a database with the previously noted methods happens +only once, at the time the replicate request is made. To have the target +database permanently replicated from the source, you must set the +``continuous`` field of the JSON object within the request to true. + +With continuous replication changes in the source database are +replicated to the target database in perpetuity until you specifically +request that replication ceases. + +.. code-block:: http + + POST http://couchdb:5984/_replicate + Content-Type: application/json + Accept: application/json + + { + "continuous" : true + "source" : "recipes", + "target" : "http://couchdb-remote:5984/recipes", + } + +Changes will be replicated between the two databases as long as a +network connection is available between the two instances. + +.. note:: + Two keep two databases synchronized with each other, you need to set + replication in both directions; that is, you must replicate from + ``databasea`` to ``databaseb``, and separately from ``databaseb`` to + ``databasea``. + +Canceling Continuous Replication +-------------------------------- + +You can cancel continuous replication by adding the ``cancel`` field to +the JSON request object and setting the value to true. Note that the +structure of the request must be identical to the original for the +cancellation request to be honoured. For example, if you requested +continuous replication, the cancellation request must also contain the +``continuous`` field. + +For example, the replication request: + +.. code-block:: http + + POST http://couchdb:5984/_replicate + Content-Type: application/json + Accept: application/json + + { + "source" : "recipes", + "target" : "http://couchdb-remote:5984/recipes", + "create_target" : true, + "continuous" : true + } + +Must be canceled using the request: + +.. code-block:: http + + POST http://couchdb:5984/_replicate + Content-Type: application/json + Accept: application/json + + { + "cancel" : true, + "continuous" : true + "create_target" : true, + "source" : "recipes", + "target" : "http://couchdb-remote:5984/recipes", + } + +Requesting cancellation of a replication that does not exist results in +a 404 error. + +``POST /_restart`` +================== + +* **Method**: ``POST /_restart`` +* **Request**: None +* **Response**: JSON status message +* **Admin Privileges Required**: yes +* **HTTP Headers**: + + * **Header**: ``Content-Type`` + + * **Description**: Request content type + * **Optional**: no + * **Value**: :mimetype:`application/json` + +* **Return Codes**: + + * **200**: + Replication request successfully completed + +Restarts the CouchDB instance. You must be authenticated as a user with +administration privileges for this to work. + +For example: + +.. code-block:: http + + POST http://admin:password@couchdb:5984/_restart + +The return value (if the server has not already restarted) is a JSON +status object indicating that the request has been received: + +.. code-block:: javascript + + { + "ok" : true, + } + +If the server has already restarted, the header may be returned, but no +actual data is contained in the response. + +``GET /_stats`` +=============== + +* **Method**: ``GET /_stats`` +* **Request**: None +* **Response**: Server statistics +* **Admin Privileges Required**: no +* **Return Codes**: + + * **200**: + Request completed successfully. + +The ``_stats`` method returns a JSON object containing the statistics +for the running server. The object is structured with top-level sections +collating the statistics for a range of entries, with each individual +statistic being easily identified, and the content of each statistic is +self-describing. For example, the request time statistics, within the +``couchdb`` section are structured as follows: + +.. code-block:: javascript + + { + "couchdb" : { + ... + "request_time" : { + "stddev" : "27.509", + "min" : "0.333333333333333", + "max" : "152", + "current" : "400.976", + "mean" : "10.837", + "sum" : "400.976", + "description" : "length of a request inside CouchDB without MochiWeb" + }, + ... + } + } + + +The fields provide the current, minimum and maximum, and a collection of +statistical means and quantities. The quantity in each case is not +defined, but the descriptions below provide + +The statistics are divided into the following top-level sections: + +- ``couchdb``: Describes statistics specific to the internals of CouchDB. + + +-------------------------+-------------------------------------------------------+----------------+ + | Statistic ID | Description | Unit | + +=========================+=======================================================+================+ + | ``auth_cache_hits`` | Number of authentication cache hits | number | + +-------------------------+-------------------------------------------------------+----------------+ + | ``auth_cache_misses`` | Number of authentication cache misses | number | + +-------------------------+-------------------------------------------------------+----------------+ + | ``database_reads`` | Number of times a document was read from a database | number | + +-------------------------+-------------------------------------------------------+----------------+ + | ``database_writes`` | Number of times a database was changed | number | + +-------------------------+-------------------------------------------------------+----------------+ + | ``open_databases`` | Number of open databases | number | + +-------------------------+-------------------------------------------------------+----------------+ + | ``open_os_files`` | Number of file descriptors CouchDB has open | number | + +-------------------------+-------------------------------------------------------+----------------+ + | ``request_time`` | Length of a request inside CouchDB without MochiWeb | milliseconds | + +-------------------------+-------------------------------------------------------+----------------+ + +- ``httpd_request_methods`` + + +----------------+----------------------------------+----------+ + | Statistic ID | Description | Unit | + +================+==================================+==========+ + | ``COPY`` | Number of HTTP COPY requests | number | + +----------------+----------------------------------+----------+ + | ``DELETE`` | Number of HTTP DELETE requests | number | + +----------------+----------------------------------+----------+ + | ``GET`` | Number of HTTP GET requests | number | + +----------------+----------------------------------+----------+ + | ``HEAD`` | Number of HTTP HEAD requests | number | + +----------------+----------------------------------+----------+ + | ``POST`` | Number of HTTP POST requests | number | + +----------------+----------------------------------+----------+ + | ``PUT`` | Number of HTTP PUT requests | number | + +----------------+----------------------------------+----------+ + +- ``httpd_status_codes`` + + +----------------+------------------------------------------------------+----------+ + | Statistic ID | Description | Unit | + +================+======================================================+==========+ + | ``200`` | Number of HTTP 200 OK responses | number | + +----------------+------------------------------------------------------+----------+ + | ``201`` | Number of HTTP 201 Created responses | number | + +----------------+------------------------------------------------------+----------+ + | ``202`` | Number of HTTP 202 Accepted responses | number | + +----------------+------------------------------------------------------+----------+ + | ``301`` | Number of HTTP 301 Moved Permanently responses | number | + +----------------+------------------------------------------------------+----------+ + | ``304`` | Number of HTTP 304 Not Modified responses | number | + +----------------+------------------------------------------------------+----------+ + | ``400`` | Number of HTTP 400 Bad Request responses | number | + +----------------+------------------------------------------------------+----------+ + | ``401`` | Number of HTTP 401 Unauthorized responses | number | + +----------------+------------------------------------------------------+----------+ + | ``403`` | Number of HTTP 403 Forbidden responses | number | + +----------------+------------------------------------------------------+----------+ + | ``404`` | Number of HTTP 404 Not Found responses | number | + +----------------+------------------------------------------------------+----------+ + | ``405`` | Number of HTTP 405 Method Not Allowed responses | number | + +----------------+------------------------------------------------------+----------+ + | ``409`` | Number of HTTP 409 Conflict responses | number | + +----------------+------------------------------------------------------+----------+ + | ``412`` | Number of HTTP 412 Precondition Failed responses | number | + +----------------+------------------------------------------------------+----------+ + | ``500`` | Number of HTTP 500 Internal Server Error responses | number | + +----------------+------------------------------------------------------+----------+ + +- ``httpd`` + + +----------------------------------+----------------------------------------------+----------+ + | Statistic ID | Description | Unit | + +==================================+==============================================+==========+ + | ``bulk_requests`` | Number of bulk requests | number | + +----------------------------------+----------------------------------------------+----------+ + | ``clients_requesting_changes`` | Number of clients for continuous _changes | number | + +----------------------------------+----------------------------------------------+----------+ + | ``requests`` | Number of HTTP requests | number | + +----------------------------------+----------------------------------------------+----------+ + | ``temporary_view_reads`` | Number of temporary view reads | number | + +----------------------------------+----------------------------------------------+----------+ + | ``view_reads`` | Number of view reads | number | + +----------------------------------+----------------------------------------------+----------+ + +You can also access individual statistics by quoting the statistics +sections and statistic ID as part of the URL path. For example, to get +the ``request_time`` statistics, you can use: + +.. code-block:: http + + GET /_stats/couchdb/request_time + +This returns an entire statistics object, as with the full request, but +containing only the request individual statistic. Hence, the returned +structure is as follows: + +.. code-block:: javascript + + { + "couchdb" : { + "request_time" : { + "stddev" : 7454.305, + "min" : 1, + "max" : 34185, + "current" : 34697.803, + "mean" : 1652.276, + "sum" : 34697.803, + "description" : "length of a request inside CouchDB without MochiWeb" + } + } + } + + +``GET /_utils`` +=============== + +* **Method**: ``GET /_utils`` +* **Request**: None +* **Response**: Administration interface +* **Admin Privileges Required**: no + +Accesses the built-in Futon administration interface for CouchDB. + +``GET /_uuids`` +=============== + +* **Method**: ``GET /_uuids`` +* **Request**: None +* **Response**: List of UUIDs +* **Admin Privileges Required**: no +* **Query Arguments**: + + * **Argument**: count + + * **Description**: Number of UUIDs to return + * **Optional**: yes + * **Type**: numeric + +* **Return Codes**: + + * **200**: + Request completed successfully. + +Requests one or more Universally Unique Identifiers (UUIDs) from the +CouchDB instance. The response is a JSON object providing a list of +UUIDs. For example: + +.. code-block:: javascript + + { + "uuids" : [ + "7e4b5a14b22ec1cf8e58b9cdd0000da3" + ] + } + +You can use the ``count`` argument to specify the number of UUIDs to be +returned. For example: + +.. code-block:: http + + GET http://couchdb:5984/_uuids?count=5 + +Returns: + +.. code-block:: javascript + + { + "uuids" : [ + "c9df0cdf4442f993fc5570225b405a80", + "c9df0cdf4442f993fc5570225b405bd2", + "c9df0cdf4442f993fc5570225b405e42", + "c9df0cdf4442f993fc5570225b4061a0", + "c9df0cdf4442f993fc5570225b406a20" + ] + } + +The UUID type is determined by the UUID type setting in the CouchDB +configuration. See :ref:`api-put-config`. + +For example, changing the UUID type to ``random``: + +.. code-block:: http + + PUT http://couchdb:5984/_config/uuids/algorithm + Content-Type: application/json + Accept: */* + + "random" + +When obtaining a list of UUIDs: + +.. code-block:: javascript + + { + "uuids" : [ + "031aad7b469956cf2826fcb2a9260492", + "6ec875e15e6b385120938df18ee8e496", + "cff9e881516483911aa2f0e98949092d", + "b89d37509d39dd712546f9510d4a9271", + "2e0dbf7f6c4ad716f21938a016e4e59f" + ] + } + +``GET /favicon.ico`` +==================== + +* **Method**: ``GET /favicon.ico`` +* **Request**: None +* **Response**: Binary content for the `favicon.ico` site icon +* **Admin Privileges Required**: no +* **Return Codes**: + + * **200**: + Request completed successfully. + * **404**: + The requested content could not be found. The returned content will include + further information, as a JSON object, if available. + +Returns the site icon. The return ``Content-Type`` header is +:mimetype:`image/x-icon`, and the content stream is the image data. diff --git a/share/doc/src/api/reference.rst b/share/doc/src/api/reference.rst new file mode 100644 index 000000000..fce650a27 --- /dev/null +++ b/share/doc/src/api/reference.rst @@ -0,0 +1,28 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +API Reference +============= + +Contents: + +.. toctree:: + :maxdepth: 2 + + configuration + authn + database + documents + design + misc + local + dbmaint diff --git a/share/doc/src/changelog.rst b/share/doc/src/changelog.rst new file mode 100644 index 000000000..18c19d40c --- /dev/null +++ b/share/doc/src/changelog.rst @@ -0,0 +1,1175 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +Apache CouchDB CHANGES +====================== + +Version 1.3.0 +------------- + +.. note:: This version has not been released yet. + +Database core +^^^^^^^^^^^^^ + +* :issue:`1512`: Validate bind address before assignment. :commit:`09ead8a0` +* Restore ``max_document_size`` protection. :commit:`bf1eb135` + +Documentation +^^^^^^^^^^^^^ + +* :issue:`1523`: Import CouchBase documentation and convert them into + `Sphinx docs <http://sphinx.pocoo.org/>`_ + +Futon +^^^^^ + +* :issue:`1470`: Futon raises popup on attempt to navigate to missed/deleted + document. :commit:`5da40eef` +* :issue:`1383`: Futon view editor won't allow you to save original view after + saving a revision. :commit:`ce48342` +* :issue:`627`: Support all timezones. :commit:`b1a049bb` +* :issue:`509`: Added view request duration to Futon. :commit:`2d2c7d1e` +* :issue:`1473`, :issue:`1472`: Disable buttons for actions that the user + doesn't have permissions to. :commit:`7156254d` + +HTTP Interface +^^^^^^^^^^^^^^^^^ + +* :issue:`1537`: Include user name in show/list `ETags`. :commit:`ac320479` +* :issue:`1511`: CouchDB checks `roles` field for `_users` database documents + with more care. :commit:`41205000` +* :issue:`1502`: Allow users to delete own _users doc. :commit:`f0d6f19bc8` +* :issue:`1501`: :ref:`Changes feed <changes>` now can take special parameter + ``since=now`` to emit changes since current point of time. :commit:`3bbb2612` +* :issue:`1442`: No longer rewrites the `X-CouchDB-Requested-Path` during + recursive calls to the rewriter. :commit:`56744f2f` +* :issue:`1441`: Limit recursion depth in the URL rewriter. + Defaults to a maximum of 100 invocations but is configurable. + :commit:`d076976c` +* :issue:`1381`: Add jquery.couch support for Windows 8 Metro apps. + :commit:`dfc5d37c` +* :issue:`1337`: Use MD5 for attachment ETag header value. :commit:`6d912c9f` +* :issue:`1321`: Variables in rewrite rules breaks OAuth authentication. + :commit:`c307ba95` +* :issue:`1285`: Allow configuration of vendor and modules version in CouchDB + welcome message. :commit:`3c24a94d` +* :issue:`1277`: Better query parameter support and code clarity: + :commit:`7e3c69ba` + + * Responses to documents created/modified via form data `POST` to /db/doc or + copied with `COPY` should now include `Location` header. + * Form data POST to /db/doc now includes an `ETag` response header. + * ``?batch=ok`` is now supported for `COPY` and `POST` /db/doc updates. + * ``?new_edits=false`` is now supported for more operations. + +* :issue:`1210`: Files starting with underscore can be attached and updated now. + :commit:`05858792` +* :issue:`1097`: Allow `OPTIONS` request to shows and lists functions. + :commit:`9f53704a` +* :issue:`1026`: Database names are encoded with respect of special characters + in the rewriter now. :commit:`272d6415` +* :issue:`986`: Added Server-Sent Events protocol to db changes API. + See http://www.w3.org/TR/eventsource/ for details. :commit:`093d2aa6` +* :issue:`887`: Fix ``bytes`` and ``offset`` parameters semantic for `_log` + resource (`explanation <https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blobdiff;f=src/couchdb/couch_log.erl;h=1b05f4db2;hp=0befe7aab;hb=ad700014;hpb=7809f3ca>`_) + :commit:`ad700014` +* :issue:`764`, :issue:`514`, :issue:`430`: Fix sending HTTP headers from + ``_list`` function, :commit:`2a74f88375` +* Send a 202 response for `_restart`. :commit:`b213e16f` +* Make password hashing synchronous when using the /_config/admins API. + :commit:`08071a80` +* Fix `_session` for IE7. +* Return ``X-Couch-Id`` header if doc is created, :commit:`98515bf0b9` +* Allow any 2xx code to indicate success, :commit:`0d50103cfd` +* Restore 400 error for empty PUT, :commit:`2057b895` +* Add support to serve single file with CouchDB, :commit:`2774531ff2` +* Support auth cookies with ``:`` characters, :commit:`d9566c831d` + +Log System +^^^^^^^^^^ + +* :issue:`1380`: Minor fixes for logrotate support. +* Improve file I/O error logging and handling, :commit:`4b6475da` +* Module Level Logging, :commit:`b58f069167` +* Log 5xx responses at error level, :commit:`e896b0b7` +* Log problems opening database at ERROR level except for auto-created + system dbs, :commit:`41667642f7` + +Replicator +^^^^^^^^^^ + +* :issue:`1557`: Upgrade some code to use BIFs bring good improvements for + replication. +* :issue:`1363`: Fix rarely occurred, but still race condition in changes feed + if a quick burst of changes happens while replication is starting the + replication can go stale. :commit:`573a7bb9` +* :issue:`1323`: Replicator now acts as standalone application. + :commit:`f913ca6e` +* :issue:`1259`: Stabilize replication id, :commit:`c6252d6d7f` +* :issue:`1248`: `HTTP 500` error now doesn't occurs when replicating with + ``?doc_ids=null``. :commit:`bea76dbf` + +Security +^^^^^^^^ + +* :issue:`1060`: Passwords are now hashed using the PBKDF2 algorithm with a + configurable work factor. :commit:`7d418134` + +Source Repository +^^^^^^^^^^^^^^^^^ + +* The source repository was migrated from `SVN`_ to `Git`_. + +.. _SVN: https://svn.apache.org/repos/asf/couchdb +.. _Git: https://git-wip-us.apache.org/repos/asf/couchdb.git + +Storage System +^^^^^^^^^^^^^^ + +* Fixed unnecessary conflict when deleting and creating a + document in the same batch. + +Test Suite +^^^^^^^^^^ + +* :issue:`1563`: Ensures urlPrefix is set in all ajax requests. + :commit:`07a6af222` +* :issue:`1389`: Improved tracebacks printed by the JS CLI tests. +* :issue:`1339`: Use shell trap to catch dying beam processes during test runs. + :commit:`2921c78` +* :issue:`1338`: Start CouchDB with ``port=0``. While CouchDB might be already + running on the default port 5984, port number 0 let the TCP stack figure out a + free port to run. :commit:`127cbe3` +* :issue:`1321`: Moved the JS test suite to the CLI. +* Improved the reliability of a number of tests. +* Fix race condition for test running on faster hardware. + +URL Rewriter & Vhosts +^^^^^^^^^^^^^^^^^^^^^ + +* :issue:`1026`: Database name is encoded during rewriting + (allowing embedded /'s, etc). :commit:`272d6415` + +UUID Algorithms +^^^^^^^^^^^^^^^ + +* :issue:`1373`: Added the utc_id algorithm :commit:`5ab712a2` + +Query and View Server +^^^^^^^^^^^^^^^^^^^^^ + +* :issue:`1491`: Clenaup view tables. :commit:`c37204b7` +* :issue:`1483`: Update handlers requires valid doc ids. :commit:`72ea7e38` +* :issue:`1445`: CouchDB tries no more to delete view file if it couldn't open + it, even if the error is `emfile`. +* :issue:`1444`: Fix missed_named_view error that occurs on existed design + documents and views. :commit:`b59ac98b` +* :issue:`1372`: `_stats` builtin reduce function no longer produces error for + empty view result. +* :issue:`1334`: Speedup in the communication with external view servers. + :commit:`a851c6e5` +* :issue:`410`: More graceful error handling for JavaScript validate_doc_update + functions. +* :issue:`111`: Improve the errors reported by the javascript view server + to provide a more friendly error report when something goes wrong. + :commit:`0c619ed` +* Deprecate E4X support, :commit:`cdfdda2314` + +Windows +^^^^^^^ + +* :issue:`1482`: Use correct linker flang to build `snappy_nif.dll` on Windows. + :commit:`a6eaf9f1` +* Allows building cleanly on Windows without cURL, :commit:`fb670f5712` + + +Version 1.2.0 +------------- + +Authentication +^^^^^^^^^^^^^^ + +* Fix use of OAuth with VHosts and URL rewriting. +* OAuth secrets can now be stored in the users system database + as an alternative to key value pairs in the .ini configuration. + By default this is disabled (secrets are stored in the .ini) + but can be enabled via the .ini configuration key `use_users_db` + in the `couch_httpd_oauth` section. +* Documents in the _users database are no longer publicly + readable. +* Confidential information in the _replication database is no + longer publicly readable. +* Password hashes are now calculated by CouchDB. Clients are no + longer required to do this manually. +* Cookies used for authentication can be made persistent by enabling + the .ini configuration key `allow_persistent_cookies` in the + `couch_httpd_auth` section. + +Build System +^^^^^^^^^^^^ + +* cURL is no longer required to build CouchDB as it is only + used by the command line JS test runner. If cURL is available + when building CouchJS you can enable the HTTP bindings by + passing -H on the command line. +* Temporarily made `make check` pass with R15B. A more thorough + fix is in the works (:issue:`1424`). +* Fixed --with-js-include and --with-js-lib options. +* Added --with-js-lib-name option. + +Futon +^^^^^ + +* The `Status` screen (active tasks) now displays two new task status + fields: `Started on` and `Updated on`. +* Futon remembers view code every time it is saved, allowing to save an + edit that amounts to a revert. + +HTTP Interface +^^^^^^^^^^^^^^ + +* Added a native JSON parser. +* The _active_tasks API now offers more granular fields. Each + task type is now able to expose different properties. +* Added built-in changes feed filter `_view`. +* Fixes to the `_changes` feed heartbeat option which caused + heartbeats to be missed when used with a filter. This caused + timeouts of continuous pull replications with a filter. +* Properly restart the SSL socket on configuration changes. + +Replicator +^^^^^^^^^^ + +* A new replicator implementation. It offers more performance and + configuration options. +* Passing non-string values to query_params is now a 400 bad + request. This is to reduce the surprise that all parameters + are converted to strings internally. +* Added optional field `since_seq` to replication objects/documents. + It allows to bootstrap a replication from a specific source sequence + number. +* Simpler replication cancellation. In addition to the current method, + replications can now be canceled by specifying the replication ID + instead of the original replication object/document. + +Storage System +^^^^^^^^^^^^^^ + +* Added optional database and view index file compression (using Google's + snappy or zlib's deflate). This feature is enabled by default, but it + can be disabled by adapting local.ini accordingly. The on-disk format + is upgraded on compaction and new DB/view creation to support this. +* Several performance improvements, most notably regarding database writes + and view indexing. +* Computation of the size of the latest MVCC snapshot data and all its + supporting metadata, both for database and view index files. This + information is exposed as the `data_size` attribute in the database and + view group information URIs. +* The size of the buffers used for database and view compaction is now + configurable. +* Added support for automatic database and view compaction. This feature + is disabled by default, but it can be enabled via the .ini configuration. +* Performance improvements for the built-in changes feed filters `_doc_ids` + and `_design'. + +View Server +^^^^^^^^^^^ + +* Add CoffeeScript (http://coffeescript.org/) as a first class view server + language. +* Fixed old index file descriptor leaks after a view cleanup. +* The requested_path property keeps the pre-rewrite path even when no VHost + configuration is matched. +* Fixed incorrect reduce query results when using pagination parameters. +* Made icu_driver work with Erlang R15B and later. + +OAuth +^^^^^ + +* Updated bundled erlang_oauth library to the latest version. + + +Version 1.1.1 +------------- + +* Support SpiderMonkey 1.8.5 +* Add configurable maximum to the number of bytes returned by _log. +* Allow CommonJS modules to be an empty string. +* Bump minimum Erlang version to R13B02. +* Do not run deleted validate_doc_update functions. +* ETags for views include current sequence if include_docs=true. +* Fix bug where duplicates can appear in _changes feed. +* Fix bug where update handlers break after conflict resolution. +* Fix bug with _replicator where include "filter" could crash couch. +* Fix crashes when compacting large views. +* Fix file descriptor leak in _log +* Fix missing revisions in _changes?style=all_docs. +* Improve handling of compaction at max_dbs_open limit. +* JSONP responses now send "text/javascript" for Content-Type. +* Link to ICU 4.2 on Windows. +* Permit forward slashes in path to update functions. +* Reap couchjs processes that hit reduce_overflow error. +* Status code can be specified in update handlers. +* Support provides() in show functions. +* _view_cleanup when ddoc has no views now removes all index files. +* max_replication_retry_count now supports "infinity". +* Fix replication crash when source database has a document with empty ID. +* Fix deadlock when assigning couchjs processes to serve requests. +* Fixes to the document multipart PUT API. +* Fixes regarding file descriptor leaks for databases with views. + + +Version 1.1.0 +------------- + +.. note:: All CHANGES for 1.0.2 and 1.0.3 also apply to 1.1.0. + +Externals +^^^^^^^^^ + +* Added OS Process module to manage daemons outside of CouchDB. +* Added HTTP Proxy handler for more scalable externals. + +Futon +^^^^^ + +* Added a "change password"-feature to Futon. + +HTTP Interface +^^^^^^^^^^^^^^ + +* Native SSL support. +* Added support for HTTP range requests for attachments. +* Added built-in filters for `_changes`: `_doc_ids` and `_design`. +* Added configuration option for TCP_NODELAY aka "Nagle". +* Allow POSTing arguments to `_changes`. +* Allow `keys` parameter for GET requests to views. +* Allow wildcards in vhosts definitions. +* More granular ETag support for views. +* More flexible URL rewriter. +* Added support for recognizing "Q values" and media parameters in + HTTP Accept headers. +* Validate doc ids that come from a PUT to a URL. + +Replicator +^^^^^^^^^^ + +* Added `_replicator` database to manage replications. +* Fixed issues when an endpoint is a remote database accessible via SSL. +* Added support for continuous by-doc-IDs replication. +* Fix issue where revision info was omitted when replicating attachments. +* Integrity of attachment replication is now verified by MD5. + +Storage System +^^^^^^^^^^^^^^ + +* Multiple micro-optimizations when reading data. + +URL Rewriter & Vhosts +^^^^^^^^^^^^^^^^^^^^^ + +* Fix for variable substituion + +View Server +^^^^^^^^^^^ + +* Added CommonJS support to map functions. +* Added `stale=update_after` query option that triggers a view update after + returning a `stale=ok` response. +* Warn about empty result caused by `startkey` and `endkey` limiting. +* Built-in reduce function `_sum` now accepts lists of integers as input. +* Added view query aliases start_key, end_key, start_key_doc_id and + end_key_doc_id. + + +Version 1.0.3 +------------- + +General +^^^^^^^ + +* Fixed compatibility issues with Erlang R14B02. + +Etap Test Suite +^^^^^^^^^^^^^^^ + +* Etap tests no longer require use of port 5984. They now use a randomly + selected port so they won't clash with a running CouchDB. + +Futon +^^^^^ + +* Made compatible with jQuery 1.5.x. + +HTTP Interface +^^^^^^^^^^^^^^ + +* Fix bug that allows invalid UTF-8 after valid escapes. +* The query parameter `include_docs` now honors the parameter `conflicts`. + This applies to queries against map views, _all_docs and _changes. +* Added support for inclusive_end with reduce views. + +Replicator +^^^^^^^^^^ + +* Enabled replication over IPv6. +* Fixed for crashes in continuous and filtered changes feeds. +* Fixed error when restarting replications in OTP R14B02. +* Upgrade ibrowse to version 2.2.0. +* Fixed bug when using a filter and a limit of 1. + +Security +^^^^^^^^ + +* Fixed OAuth signature computation in OTP R14B02. +* Handle passwords with : in them. + +Storage System +^^^^^^^^^^^^^^ + +* More performant queries against _changes and _all_docs when using the + `include_docs` parameter. + +Windows +^^^^^^^ + +* Windows builds now require ICU >= 4.4.0 and Erlang >= R14B03. See + :issue:`1152`, and :issue:`963` + OTP-9139 for more information. + + +Version 1.0.2 +------------- + +Futon +^^^^^ + +* Make test suite work with Safari and Chrome. +* Fixed animated progress spinner. +* Fix raw view document link due to overzealous URI encoding. +* Spell javascript correctly in loadScript(uri). + +HTTP Interface +^^^^^^^^^^^^^^ + +* Allow reduce=false parameter in map-only views. +* Fix parsing of Accept headers. +* Fix for multipart GET APIs when an attachment was created during a + local-local replication. See :issue:`1022` for details. + +Log System +^^^^^^^^^^ + +* Reduce lengthy stack traces. +* Allow logging of native <xml> types. + +Replicator +^^^^^^^^^^ + +* Updated ibrowse library to 2.1.2 fixing numerous replication issues. +* Make sure that the replicator respects HTTP settings defined in the config. +* Fix error when the ibrowse connection closes unexpectedly. +* Fix authenticated replication (with HTTP basic auth) of design documents + with attachments. +* Various fixes to make replication more resilient for edge-cases. + +Storage System +^^^^^^^^^^^^^^ + +* Fix leaking file handles after compacting databases and views. +* Fix databases forgetting their validation function after compaction. +* Fix occasional timeout errors after successfully compacting large databases. +* Fix ocassional error when writing to a database that has just been compacted. +* Fix occasional timeout errors on systems with slow or heavily loaded IO. +* Fix for OOME when compactions include documents with many conflicts. +* Fix for missing attachment compression when MIME types included parameters. +* Preserve purge metadata during compaction to avoid spurious view rebuilds. +* Fix spurious conflicts introduced when uploading an attachment after + a doc has been in a conflict. See :issue:`902` for details. +* Fix for frequently edited documents in multi-master deployments being + duplicated in _changes and _all_docs. See :issue:`968` for details on how + to repair. +* Significantly higher read and write throughput against database and + view index files. + +View Server +^^^^^^^^^^^ + +* Don't trigger view updates when requesting `_design/doc/_info`. +* Fix for circular references in CommonJS requires. +* Made isArray() function available to functions executed in the query server. +* Documents are now sealed before being passed to map functions. +* Force view compaction failure when duplicated document data exists. When + this error is seen in the logs users should rebuild their views from + scratch to fix the issue. See :issue:`999` for details. + + +Version 1.0.1 +------------- + +Authentication +^^^^^^^^^^^^^^ + +* Enable basic-auth popup when required to access the server, to prevent + people from getting locked out. + +Build and System Integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Included additional source files for distribution. + +Futon +^^^^^ + +* User interface element for querying stale (cached) views. + +HTTP Interface +^^^^^^^^^^^^^^ + +* Expose `committed_update_seq` for monitoring purposes. +* Show fields saved along with _deleted=true. Allows for auditing of deletes. +* More robust Accept-header detection. + +Replicator +^^^^^^^^^^ + +* Added support for replication via an HTTP/HTTPS proxy. +* Fix pull replication of attachments from 0.11 to 1.0.x. +* Make the _changes feed work with non-integer seqnums. + +Storage System +^^^^^^^^^^^^^^ + +* Fix data corruption bug :issue:`844`. Please see + http://couchdb.apache.org/notice/1.0.1.html for details. + + +Version 1.0.0 +------------- + +Security +^^^^^^^^ + +* Added authentication caching, to avoid repeated opening and closing of the + users database for each request requiring authentication. + +Storage System +^^^^^^^^^^^^^^ + +* Small optimization for reordering result lists. +* More efficient header commits. +* Use O_APPEND to save lseeks. +* Faster implementation of pread_iolist(). Further improves performance on + concurrent reads. + +View Server +^^^^^^^^^^^ + +* Faster default view collation. +* Added option to include update_seq in view responses. + + +Version 0.11.2 +-------------- + +Authentication +^^^^^^^^^^^^^^ + +* User documents can now be deleted by admins or the user. + +Futon +^^^^^ + +* Add some Futon files that were missing from the Makefile. + +HTTP Interface +^^^^^^^^^^^^^^ + +* Better error messages on invalid URL requests. + +Replicator +^^^^^^^^^^ + +* Fix bug when pushing design docs by non-admins, which was hanging the + replicator for no good reason. +* Fix bug when pulling design documents from a source that requires + basic-auth. + +Security +^^^^^^^^ + +* Avoid potential DOS attack by guarding all creation of atoms. + + +Version 0.11.1 +-------------- + +Build and System Integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Output of `couchdb --help` has been improved. +* Fixed compatibility with the Erlang R14 series. +* Fixed warnings on Linux builds. +* Fixed build error when aclocal needs to be called during the build. +* Require ICU 4.3.1. +* Fixed compatibility with Solaris. + +Configuration System +^^^^^^^^^^^^^^^^^^^^ + +* Fixed timeout with large .ini files. + +Futon +^^^^^ + +* Use "expando links" for over-long document values in Futon. +* Added continuous replication option. +* Added option to replicating test results anonymously to a community + CouchDB instance. +* Allow creation and deletion of config entries. +* Fixed display issues with doc ids that have escaped characters. +* Fixed various UI issues. + +HTTP Interface +^^^^^^^^^^^^^^ + +* Mask passwords in active tasks and logging. +* Update mochijson2 to allow output of BigNums not in float form. +* Added support for X-HTTP-METHOD-OVERRIDE. +* Better error message for database names. +* Disable jsonp by default. +* Accept gzip encoded standalone attachments. +* Made max_concurrent_connections configurable. +* Made changes API more robust. +* Send newly generated document rev to callers of an update function. + +JavaScript Clients +^^^^^^^^^^^^^^^^^^ + +* Added tests for couch.js and jquery.couch.js +* Added changes handler to jquery.couch.js. +* Added cache busting to jquery.couch.js if the user agent is msie. +* Added support for multi-document-fetch (via _all_docs) to jquery.couch.js. +* Added attachment versioning to jquery.couch.js. +* Added option to control ensure_full_commit to jquery.couch.js. +* Added list functionality to jquery.couch.js. +* Fixed issues where bulkSave() wasn't sending a POST body. + +Log System +^^^^^^^^^^ + +* Log HEAD requests as HEAD, not GET. +* Keep massive JSON blobs out of the error log. +* Fixed a timeout issue. + +Replication System +^^^^^^^^^^^^^^^^^^ + +* Refactored various internal APIs related to attachment streaming. +* Fixed hanging replication. +* Fixed keepalive issue. + +Security +^^^^^^^^ + +* Added authentication redirect URL to log in clients. +* Fixed query parameter encoding issue in oauth.js. +* Made authentication timeout configurable. +* Temporary views are now admin-only resources. + +Storage System +^^^^^^^^^^^^^^ + +* Don't require a revpos for attachment stubs. +* Added checking to ensure when a revpos is sent with an attachment stub, + it's correct. +* Make file deletions async to avoid pauses during compaction and db + deletion. +* Fixed for wrong offset when writing headers and converting them to blocks, + only triggered when header is larger than 4k. +* Preserve _revs_limit and instance_start_time after compaction. + +Test Suite +^^^^^^^^^^ + +* Made the test suite overall more reliable. + +View Server +^^^^^^^^^^^ + +* Provide a UUID to update functions (and all other functions) that they can + use to create new docs. +* Upgrade CommonJS modules support to 1.1.1. +* Fixed erlang filter funs and normalize filter fun API. +* Fixed hang in view shutdown. + +URL Rewriter & Vhosts +^^^^^^^^^^^^^^^^^^^^^ + +* Allow more complex keys in rewriter. +* Allow global rewrites so system defaults are available in vhosts. +* Allow isolation of databases with vhosts. +* Fix issue with passing variables to query parameters. + + +Version 0.11.0 +-------------- + +Build and System Integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Updated and improved source documentation. +* Fixed distribution preparation for building on Mac OS X. +* Added support for building a Windows installer as part of 'make dist'. +* Bug fix for building couch.app's module list. +* ETap tests are now run during make distcheck. This included a number of + updates to the build system to properly support VPATH builds. +* Gavin McDonald setup a build-bot instance. More info can be found at + http://ci.apache.org/buildbot.html + +Futon +^^^^^ + +* Added a button for view compaction. +* JSON strings are now displayed as-is in the document view, without the + escaping of new-lines and quotes. That dramatically improves readability of + multi-line strings. +* Same goes for editing of JSON string values. When a change to a field value is + submitted, and the value is not valid JSON it is assumed to be a string. This + improves editing of multi-line strings a lot. +* Hitting tab in textareas no longer moves focus to the next form field, but + simply inserts a tab character at the current caret position. +* Fixed some font declarations. + +HTTP Interface +^^^^^^^^^^^^^^ + +* Provide Content-MD5 header support for attachments. +* Added URL Rewriter handler. +* Added virtual host handling. + +Replication +^^^^^^^^^^^ + +* Added option to implicitly create replication target databases. +* Avoid leaking file descriptors on automatic replication restarts. +* Added option to replicate a list of documents by id. +* Allow continuous replication to be cancelled. + +Runtime Statistics +^^^^^^^^^^^^^^^^^^ + +* Statistics are now calculated for a moving window instead of non-overlapping + timeframes. +* Fixed a problem with statistics timers and system sleep. +* Moved statistic names to a term file in the priv directory. + +Security +^^^^^^^^ + +* Fixed CVE-2010-0009: Apache CouchDB Timing Attack Vulnerability. +* Added default cookie-authentication and users database. +* Added Futon user interface for user signup and login. +* Added per-database reader access control lists. +* Added per-database security object for configuration data in validation + functions. +* Added proxy authentication handler + +Storage System +^^^^^^^^^^^^^^ + +* Adds batching of multiple updating requests, to improve throughput with many + writers. Removed the now redundant couch_batch_save module. +* Adds configurable compression of attachments. + +View Server +^^^^^^^^^^^ + +* Added optional 'raw' binary collation for faster view builds where Unicode + collation is not important. +* Improved view index build time by reducing ICU collation callouts. +* Improved view information objects. +* Bug fix for partial updates during view builds. +* Move query server to a design-doc based protocol. +* Use json2.js for JSON serialization for compatiblity with native JSON. +* Major refactoring of couchjs to lay the groundwork for disabling cURL + support. The new HTTP interaction acts like a synchronous XHR. Example usage + of the new system is in the JavaScript CLI test runner. + + + + +Version 0.10.1 +-------------- + +Build and System Integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Test suite now works with the distcheck target. + +Replicator +^^^^^^^^^^ + +* Stability enhancements regarding redirects, timeouts, OAuth. + +Query Server +^^^^^^^^^^^^ + +* Avoid process leaks +* Allow list and view to span languages + +Stats +^^^^^ + +* Eliminate new process flood on system wake + + +Version 0.10.0 +-------------- + +Build and System Integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Changed `couchdb` script configuration options. +* Added default.d and local.d configuration directories to load sequence. + +HTTP Interface +^^^^^^^^^^^^^^ + +* Added optional cookie-based authentication handler. +* Added optional two-legged OAuth authentication handler. + +Storage Format +^^^^^^^^^^^^^^ + +* Add move headers with checksums to the end of database files for extra robust + storage and faster storage. + +View Server +^^^^^^^^^^^ + +* Added native Erlang views for high-performance applications. + + +Version 0.9.2 +------------- + +Build and System Integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Remove branch callbacks to allow building couchjs against newer versions of + Spidermonkey. + +Replication +^^^^^^^^^^^ + +* Fix replication with 0.10 servers initiated by an 0.9 server (:issue:`559`). + + +Version 0.9.1 +------------- + +Build and System Integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* PID file directory is now created by the SysV/BSD daemon scripts. +* Fixed the environment variables shown by the configure script. +* Fixed the build instructions shown by the configure script. +* Updated ownership and permission advice in `README` for better security. + +Configuration and stats system +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Corrected missing configuration file error message. +* Fixed incorrect recording of request time. + +Database Core +^^^^^^^^^^^^^ + +* Document validation for underscore prefixed variables. +* Made attachment storage less sparse. +* Fixed problems when a database with delayed commits pending is considered + idle, and subject to losing changes when shutdown. (:issue:`334`) + +External Handlers +^^^^^^^^^^^^^^^^^ + +* Fix POST requests. + +Futon +^^^^^ + +* Redirect when loading a deleted view URI from the cookie. + +HTTP Interface +^^^^^^^^^^^^^^ + +* Attachment requests respect the "rev" query-string parameter. + +JavaScript View Server +^^^^^^^^^^^^^^^^^^^^^^ + +* Useful JavaScript Error messages. + +Replication +^^^^^^^^^^^ + +* Added support for Unicode characters transmitted as UTF-16 surrogate pairs. +* URL-encode attachment names when necessary. +* Pull specific revisions of an attachment, instead of just the latest one. +* Work around a rare chunk-merging problem in ibrowse. +* Work with documents containing Unicode characters outside the Basic + Multilingual Plane. + + +Version 0.9.0 +------------- + +Build and System Integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* The `couchdb` script now supports system chainable configuration files. +* The Mac OS X daemon script now redirects STDOUT and STDERR like SysV/BSD. +* The build and system integration have been improved for portability. +* Added COUCHDB_OPTIONS to etc/default/couchdb file. +* Remove COUCHDB_INI_FILE and COUCHDB_PID_FILE from etc/default/couchdb file. +* Updated `configure.ac` to manually link `libm` for portability. +* Updated `configure.ac` to extended default library paths. +* Removed inets configuration files. +* Added command line test runner. +* Created dev target for make. + +Configuration and stats system +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Separate default and local configuration files. +* HTTP interface for configuration changes. +* Statistics framework with HTTP query API. + +Database Core +^^^^^^^^^^^^^ + +* Faster B-tree implementation. +* Changed internal JSON term format. +* Improvements to Erlang VM interactions under heavy load. +* User context and administrator role. +* Update validations with design document validation functions. +* Document purge functionality. +* Ref-counting for database file handles. + +Design Document Resource Paths +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Added httpd_design_handlers config section. +* Moved _view to httpd_design_handlers. +* Added ability to render documents as non-JSON content-types with _show and + _list functions, which are also httpd_design_handlers. + +Futon Utility Client +^^^^^^^^^^^^^^^^^^^^ + +* Added pagination to the database listing page. +* Implemented attachment uploading from the document page. +* Added page that shows the current configuration, and allows modification of + option values. +* Added a JSON "source view" for document display. +* JSON data in view rows is now syntax highlighted. +* Removed the use of an iframe for better integration with browser history and + bookmarking. +* Full database listing in the sidebar has been replaced by a short list of + recent databases. +* The view editor now allows selection of the view language if there is more + than one configured. +* Added links to go to the raw view or document URI. +* Added status page to display currently running tasks in CouchDB. +* JavaScript test suite split into multiple files. +* Pagination for reduce views. + +HTTP Interface +^^^^^^^^^^^^^^ + +* Added client side UUIDs for idempotent document creation +* HTTP COPY for documents +* Streaming of chunked attachment PUTs to disk +* Remove negative count feature +* Add include_docs option for view queries +* Add multi-key view post for views +* Query parameter validation +* Use stale=ok to request potentially cached view index +* External query handler module for full-text or other indexers. +* Etags for attachments, views, shows and lists +* Show and list functions for rendering documents and views as developer + controlled content-types. +* Attachment names may use slashes to allow uploading of nested directories + (useful for static web hosting). +* Option for a view to run over design documents. +* Added newline to JSON responses. Closes bike-shed. + +Replication +^^^^^^^^^^^ + +* Using ibrowse. +* Checkpoint replications so failures are less expensive. +* Automatically retry of failed replications. +* Stream attachments in pull-replication. + + +Version 0.8.1-incubating +------------------------ + +Build and System Integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* The `couchdb` script no longer uses `awk` for configuration checks as this + was causing portability problems. +* Updated `sudo` example in `README` to use the `-i` option, this fixes + problems when invoking from a directory the `couchdb` user cannot access. + +Database Core +^^^^^^^^^^^^^ + +* Fix for replication problems where the write queues can get backed up if the + writes aren't happening fast enough to keep up with the reads. For a large + replication, this can exhaust memory and crash, or slow down the machine + dramatically. The fix keeps only one document in the write queue at a time. +* Fix for databases sometimes incorrectly reporting that they contain 0 + documents after compaction. +* CouchDB now uses ibrowse instead of inets for its internal HTTP client + implementation. This means better replication stability. + +Futon +^^^^^ + +* The view selector dropdown should now work in Opera and Internet Explorer + even when it includes optgroups for design documents. (:issue:`81`) + +JavaScript View Server +^^^^^^^^^^^^^^^^^^^^^^ + +* Sealing of documents has been disabled due to an incompatibility with + SpiderMonkey 1.9. +* Improve error handling for undefined values emitted by map functions. + (:issue:`83`) + +HTTP Interface +^^^^^^^^^^^^^^ + +* Fix for chunked responses where chunks were always being split into multiple + TCP packets, which caused problems with the test suite under Safari, and in + some other cases. +* Fix for an invalid JSON response body being returned for some kinds of + views. (:issue:`84`) +* Fix for connections not getting closed after rejecting a chunked request. + (:issue:`55`) +* CouchDB can now be bound to IPv6 addresses. +* The HTTP `Server` header now contains the versions of CouchDB and Erlang. + + +Version 0.8.0-incubating +------------------------ + +Build and System Integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* CouchDB can automatically respawn following a server crash. +* Database server no longer refuses to start with a stale PID file. +* System logrotate configuration provided. +* Improved handling of ICU shared libraries. +* The `couchdb` script now automatically enables SMP support in Erlang. +* The `couchdb` and `couchjs` scripts have been improved for portability. +* The build and system integration have been improved for portability. + +Database Core +^^^^^^^^^^^^^ + +* The view engine has been completely decoupled from the storage engine. Index + data is now stored in separate files, and the format of the main database + file has changed. +* Databases can now be compacted to reclaim space used for deleted documents + and old document revisions. +* Support for incremental map/reduce views has been added. +* To support map/reduce, the structure of design documents has changed. View + values are now JSON objects containing at least a `map` member, and + optionally a `reduce` member. +* View servers are now identified by name (for example `javascript`) instead of + by media type. +* Automatically generated document IDs are now based on proper UUID generation + using the crypto module. +* The field `content-type` in the JSON representation of attachments has been + renamed to `content_type` (underscore). + +Futon +^^^^^ + +* When adding a field to a document, Futon now just adds a field with an + autogenerated name instead of prompting for the name with a dialog. The name + is automatically put into edit mode so that it can be changed immediately. +* Fields are now sorted alphabetically by name when a document is displayed. +* Futon can be used to create and update permanent views. +* The maximum number of rows to display per page on the database page can now + be adjusted. +* Futon now uses the XMLHTTPRequest API asynchronously to communicate with the + CouchDB HTTP server, so that most operations no longer block the browser. +* View results sorting can now be switched between ascending and descending by + clicking on the `Key` column header. +* Fixed a bug where documents that contained a `@` character could not be + viewed. (:issue:`12`) +* The database page now provides a `Compact` button to trigger database + compaction. (:issue:`38`) +* Fixed portential double encoding of document IDs and other URI segments in + many instances. (:issue:`39`) +* Improved display of attachments. +* The JavaScript Shell has been removed due to unresolved licensing issues. + +JavaScript View Server +^^^^^^^^^^^^^^^^^^^^^^ + +* SpiderMonkey is no longer included with CouchDB, but rather treated as a + normal external dependency. A simple C program (`_couchjs`) is provided that + links against an existing SpiderMonkey installation and uses the interpreter + embedding API. +* View functions using the default JavaScript view server can now do logging + using the global `log(message)` function. Log messages are directed into the + CouchDB log at `INFO` level. (:issue:`59`) +* The global `map(key, value)` function made available to view code has been + renamed to `emit(key, value)`. +* Fixed handling of exceptions raised by view functions. + +HTTP Interface +^^^^^^^^^^^^^^ + +* CouchDB now uses MochiWeb instead of inets for the HTTP server + implementation. Among other things, this means that the extra configuration + files needed for inets (such as `couch_httpd.conf`) are no longer used. +* The HTTP interface now completely supports the `HEAD` method. (:issue:`3`) +* Improved compliance of `Etag` handling with the HTTP specification. + (:issue:`13`) +* Etags are no longer included in responses to document `GET` requests that + include query string parameters causing the JSON response to change without + the revision or the URI having changed. +* The bulk document update API has changed slightly on both the request and the + response side. In addition, bulk updates are now atomic. +* CouchDB now uses `TCP_NODELAY` to fix performance problems with persistent + connections on some platforms due to nagling. +* Including a `?descending=false` query string parameter in requests to views + no longer raises an error. +* Requests to unknown top-level reserved URLs (anything with a leading + underscore) now return a `unknown_private_path` error instead of the + confusing `illegal_database_name`. +* The Temporary view handling now expects a JSON request body, where the JSON + is an object with at least a `map` member, and optional `reduce` and + `language` members. +* Temporary views no longer determine the view server based on the Content-Type + header of the `POST` request, but rather by looking for a `language` member + in the JSON body of the request. +* The status code of responses to `DELETE` requests is now 200 to reflect that + that the deletion is performed synchronously. diff --git a/share/doc/src/changes.rst b/share/doc/src/changes.rst new file mode 100644 index 000000000..0d98c8610 --- /dev/null +++ b/share/doc/src/changes.rst @@ -0,0 +1,214 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _changes: + +============ +Changes Feed +============ + +Polling +======= + +A list of changes made to documents in the database, in the order they were +made, can be obtained from the database's ``_changes`` resource. You can query +the ``_changes`` resource by issuing a ``GET`` request with the following +(optional) parameters: + ++--------------+----------------------------------------------+---------------+--------------+ +| Parameter | Value | Default Value | Notes | ++==============+==============================================+===============+==============+ +| since | seqnum / now | 0 | \(1) | ++--------------+----------------------------------------------+---------------+--------------+ +| limit | maxsequences | none | \(2) | ++--------------+----------------------------------------------+---------------+--------------+ +| descending | boolean | false | \(3) | ++--------------+----------------------------------------------+---------------+--------------+ +| feed | normal / longpoll / continuous / eventsource | normal | \(4) | ++--------------+----------------------------------------------+---------------+--------------+ +| heartbeat | milliseconds | 60000 | \(5) | ++--------------+----------------------------------------------+---------------+--------------+ +| timeout | milliseconds | 60000 | \(6) | ++--------------+----------------------------------------------+---------------+--------------+ +| filter | designdoc/filtername / _view | none | \(7) | ++--------------+----------------------------------------------+---------------+--------------+ +| include_docs | boolean | false | \(8) | ++--------------+----------------------------------------------+---------------+--------------+ +| style | all_docs / main_only | main_only | \(9) | ++--------------+----------------------------------------------+---------------+--------------+ +| view | designdoc/filtername | none | \(10) | ++--------------+----------------------------------------------+---------------+--------------+ + +Notes: + +(1) Start the results from the change immediately after the given sequence + number. + +(2) Limit number of result rows to the specified value (note that using 0 here + has the same effect as 1). + +(3) Return the change results in descending sequence order (most recent change + first) + +(4) Select the type of feed. + +(5) Period in milliseconds after which an empty line is sent in the results. + Only applicable for `longpoll` or `continuous` feeds. Overrides any timeout + to keep the feed alive indefinitely. + +(6) Maximum period in milliseconds to wait for a change before the response is + sent, even if there are no results. Only applicable for `longpoll` or + `continuous` feeds. Note that 60000 is also the default maximum timeout to + prevent undetected dead connections. + + You can change the default maximum timeout in your ini-configuration: + + .. code-block:: ini + + [httpd] + changes_timeout=#millisecs + +(7) Reference to a :ref:`filter function <filterfun>` from a design document + that will filter whole stream emitting only filtered events. + See the `section in the book`_ for more information. + +(8) Include the associated document with each result. If there are conflicts, + only the winning revision is returned. + +(9) Specifies how many revisions are returned in the changes array. + The default, `main_only`, will only return the current "winning" revision; + `all_docs` will return all leaf revisions (including conflicts and deleted + former conflicts.) + +(10) Allows to use view functions as filters. It requires to set ``filter`` + special value `_view` to enable this feature. Documents counted as "passed" + for view filter in case if map function emits at least one record for them. + +.. versionchanged:: 0.11.0 added ``include_docs`` parameter +.. versionchanged:: 1.2.0 added ``view`` parameter and special value `_view` + for ``filter`` one +.. versionchanged:: 1.3.0 ``since`` parameter could take `now` value to start + listen changes since current seq number. +.. versionchanged:: 1.3.0 ``eventsource`` feed type added. + +By default all changes are immediately returned as a JSON object:: + + GET /somedatabase/_changes HTTP/1.1 + +.. code-block:: javascript + + {"results":[ + {"seq":1,"id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]}, + {"seq":3,"id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]}, + {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true} + ], + "last_seq":5} + +``results`` is the list of changes in sequential order. New and changed +documents only differ in the value of the rev; deleted documents include the +``"deleted": true`` attribute. (In the ``style=all_docs mode``, deleted applies +only to the current/winning revision. The other revisions listed might be +deleted even if there is no deleted property; you have to ``GET`` them +individually to make sure.) + +``last_seq`` is the sequence number of the last update returned. (Currently it +will always be the same as the seq of the last item in results.) + +Sending a ``since`` param in the query string skips all changes up to and +including the given sequence number:: + + GET /somedatabase/_changes?since=3 HTTP/1.1 + +.. code-block:: javascript + + {"results":[ + {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true} + ], + "last_seq":5} + +Long Polling +============ + +The `longpoll` feed (probably most useful used from a browser) is a more +efficient form of polling that waits for a change to occur before the response +is sent. `longpoll` avoids the need to frequently poll CouchDB to discover +nothing has changed! + +The response is basically the same JSON as is sent for the normal feed. + +A timeout limits the maximum length of time the connection is open. If there +are no changes before the timeout expires the response's results will be an +empty list. + +Continuous +========== + +Polling the CouchDB server is not a good thing to do. Setting up new HTTP +connections just to tell the client that nothing happened puts unnecessary +strain on CouchDB. + +A continuous feed stays open and connected to the database until explicitly +closed and changes are sent to the client as they happen, i.e. in near +real-time. + +The continuous feed's response is a little different than the other feed types +to simplify the job of the client - each line of the response is either empty +or a JSON object representing a single change, as found in the normal feed's +results. + +.. code-block:: text + + GET /somedatabase/_changes?feed=continuous HTTP/1.1 + +.. code-block:: javascript + + {"seq":1,"id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]} + {"seq":3,"id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]} + {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true} + ... tum tee tum ... + {"seq":6,"id":"updated","changes":[{"rev":"3-825cb35de44c433bfb2df415563a19de"}]} + +Obviously, `... tum tee tum ...` does not appear in the actual response, but +represents a long pause before the change with seq 6 occurred. + +.. _section in the book: http://books.couchdb.org/relax/reference/change-notifications + +Event Source +============ + +The `eventsource` feed provides push notifications that can be consumed in +the form of DOM events in the browser. Refer to theW3C specification for +`W3 eventsource specification`_ for further details. + +.. code-block:: text + + GET /somedatabase/_changes?feed=eventsource HTTP/1.1 + +.. code-block:: javascript + + // define the event handling function + if (window.EventSource) { + var source = new EventSource( + "/somedatabase/_changes?feed=eventsource"); + var results = []; + var sourceListener = function(e) { + var data = JSON.parse(e.data); + results.push(data); + }; + + // start listening for events + source.addEventListener('message', sourceListener , false); + + // stop listening for events + source.removeEventListener('message', sourceListener , false); + +.. _W3 eventsource specification: http://www.w3.org/TR/eventsource/ diff --git a/share/doc/src/commonjs.rst b/share/doc/src/commonjs.rst new file mode 100644 index 000000000..49ccaa632 --- /dev/null +++ b/share/doc/src/commonjs.rst @@ -0,0 +1,56 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _commonjs: + +CommonJS support for map functions +================================== + +CommonJS support allows you to use `CommonJS notation <http://commonjs.org/specs>`_ +inside map and reduce functions, but only of libraries that are stored +inside the views part of the design doc. + +So you could continue to access CommonJS code in design\_doc.foo, from +your list functions etc, but we'd add the ability to require CommonJS +modules within map and reduce, but only from ``design_doc.views.lib``. + +There's no worry here about namespace collisions, as Couch just plucks +``views.*.map`` and ``views.*.reduce`` out of the design doc. So you +could have a view called ``lib`` if you wanted, and still have CommonJS +stored in ``views.lib.sha1`` and ``views.lib.stemmer`` if you wanted. + +The implementation is simplified by enforcing that CommonJS modules to +be used in map functions be stored in views.lib. + +A sample design doc (taken from the test suite in Futon) is below: + +.. code-block:: javascript + + { + "views" : { + "lib" : { + "baz" : "exports.baz = 'bam';", + "foo" : { + "zoom" : "exports.zoom = 'yeah';", + "boom" : "exports.boom = 'ok';", + "foo" : "exports.foo = 'bar';" + } + }, + "commonjs" : { + "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}" + } + }, + "_id" : "_design/test" + } + +The ``require()`` statement is relative to the design document, but +anything loaded form outside of ``views/lib`` will fail. diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py new file mode 100644 index 000000000..26974fc61 --- /dev/null +++ b/share/doc/src/conf.py @@ -0,0 +1,88 @@ +## Licensed under the Apache License, Version 2.0 (the "License"); you may not +## use this file except in compliance with the License. You may obtain a copy of +## the License at +## +## http://www.apache.org/licenses/LICENSE-2.0 +## +## Unless required by applicable law or agreed to in writing, software +## distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +## WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +## License for the specific language governing permissions and limitations under +## the License. + +import sys, os + +extensions = ["sphinx.ext.todo", "sphinx.ext.extlinks"] + +source_suffix = ".rst" + +master_doc = "index" + +nitpicky = True + +version = "1.3" + +release = "1.3.0" + +project = u"Apache CouchDB" + +copyright = u"2012, The Apache Software Foundation" + +highlight_language = "json" + +pygments_style = "sphinx" + +html_theme = "default" + +templates_path = ["../templates"] + +html_static_path = ["../static"] + +html_title = "Apache CouchDB " + version + " Manual" + +html_style = "rtd.css" + +html_logo = "../images/logo.png" + +html_favicon = "../images/favicon.ico" + +html_sidebars= { + "**": [ + "searchbox.html", + "localtoc.html", + "relations.html", + "utilities.html", + "help.html", + ] +} + +text_newlines = "native" + +latex_documents = [( + "index", + "CouchDB.tex", + project, + "", + "manual", + True +)] + +latex_elements = { + "papersize":"a4paper" +} + +texinfo_documents = [( + "index", + "CouchDB", + project, + "", + "CouchDB", + "The Apache CouchDB database", + "Databases", + True +)] + +extlinks = { + 'issue': ('https://issues.apache.org/jira/browse/COUCHDB-%s', 'COUCHDB-'), + 'commit': ('https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=commit;h=%s', '#') +} diff --git a/share/doc/src/config_reference.rst b/share/doc/src/config_reference.rst new file mode 100644 index 000000000..b2e78cf3b --- /dev/null +++ b/share/doc/src/config_reference.rst @@ -0,0 +1,288 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +Configuration options reference +=============================== + + +Configuration Groups +-------------------- + ++----------------------------------+-------------------------------------------+ +| Section | Description | ++==================================+===========================================+ +| attachments | Attachment options | ++----------------------------------+-------------------------------------------+ +| couchdb | CouchDB specific options | ++----------------------------------+-------------------------------------------+ +| couch_httpd_auth | HTTPD Authentication options | ++----------------------------------+-------------------------------------------+ +| daemons | Daemons and background processes | ++----------------------------------+-------------------------------------------+ +| httpd | HTTPD Server options | ++----------------------------------+-------------------------------------------+ +| httpd_db_handlers | Database Operation handlers | ++----------------------------------+-------------------------------------------+ +| httpd_design_handlers | Handlers for design document operations | ++----------------------------------+-------------------------------------------+ +| httpd_global_handlers | Handlers for global operations | ++----------------------------------+-------------------------------------------+ +| log | Logging options | ++----------------------------------+-------------------------------------------+ +| query_servers | Query Server options | ++----------------------------------+-------------------------------------------+ +| query_server_config | Query server options | ++----------------------------------+-------------------------------------------+ +| replicator | Replicator Options | ++----------------------------------+-------------------------------------------+ +| ssl | SSL (Secure Sockets Layer) Options | ++----------------------------------+-------------------------------------------+ +| stats | Statistics options | ++----------------------------------+-------------------------------------------+ +| uuids | UUID generation options | ++----------------------------------+-------------------------------------------+ + +attachments Configuration Options +--------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| compressible_types | compressible_types | ++--------------------------------------+---------------------------------------+ +| compression_level | compression_level | ++--------------------------------------+---------------------------------------+ + +couchdb Configuration Options +----------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| database_dir | database_dir | ++--------------------------------------+---------------------------------------+ +| delayed_commits | delayed_commits | ++--------------------------------------+---------------------------------------+ +| max_attachment_chunk_size | max_attachment_chunk_size | ++--------------------------------------+---------------------------------------+ +| max_dbs_open | max_dbs_open | ++--------------------------------------+---------------------------------------+ +| max_document_size | max_document_size | ++--------------------------------------+---------------------------------------+ +| os_process_timeout | os_process_timeout | ++--------------------------------------+---------------------------------------+ +| uri_file | uri_file | ++--------------------------------------+---------------------------------------+ +| util_driver_dir | util_driver_dir | ++--------------------------------------+---------------------------------------+ +| view_index_dir | view_index_dir | ++--------------------------------------+---------------------------------------+ + +daemons Configuration Options +----------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| auth_cache | auth_cache | ++--------------------------------------+---------------------------------------+ +| db_update_notifier | db_update_notifier | ++--------------------------------------+---------------------------------------+ +| external_manager | external_manager | ++--------------------------------------+---------------------------------------+ +| httpd | httpd | ++--------------------------------------+---------------------------------------+ +| httpsd | Enabled HTTPS service | ++--------------------------------------+---------------------------------------+ +| query_servers | query_servers | ++--------------------------------------+---------------------------------------+ +| stats_aggregator | stats_aggregator | ++--------------------------------------+---------------------------------------+ +| stats_collector | stats_collector | ++--------------------------------------+---------------------------------------+ +| uuids | uuids | ++--------------------------------------+---------------------------------------+ +| view_manager | view_manager | ++--------------------------------------+---------------------------------------+ + +httpd_db_handlers Configuration Options +--------------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| _changes | _changes | ++--------------------------------------+---------------------------------------+ +| _compact | _compact | ++--------------------------------------+---------------------------------------+ +| _design | _design | ++--------------------------------------+---------------------------------------+ +| _temp_view | _temp_view | ++--------------------------------------+---------------------------------------+ +| _view_cleanup | _view_cleanup | ++--------------------------------------+---------------------------------------+ + +couch_httpd_auth Configuration Options +-------------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| auth_cache_size | auth_cache_size | ++--------------------------------------+---------------------------------------+ +| authentication_db | authentication_db | ++--------------------------------------+---------------------------------------+ +| authentication_redirect | authentication_redirect | ++--------------------------------------+---------------------------------------+ +| require_valid_user | require_valid_user | ++--------------------------------------+---------------------------------------+ +| timeout | timeout | ++--------------------------------------+---------------------------------------+ + +httpd Configuration Options +--------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| allow_jsonp | allow_jsonp | ++--------------------------------------+---------------------------------------+ +| authentication_handlers | authentication_handlers | ++--------------------------------------+---------------------------------------+ +| bind_address | bind_address | ++--------------------------------------+---------------------------------------+ +| default_handler | default_handler | ++--------------------------------------+---------------------------------------+ +| max_connections | max_connections | ++--------------------------------------+---------------------------------------+ +| nodelay | Enable TCP_NODELAY | ++--------------------------------------+---------------------------------------+ +| port | port | ++--------------------------------------+---------------------------------------+ +| secure_rewrites | secure_rewrites | ++--------------------------------------+---------------------------------------+ +| vhost_global_handlers | vhost_global_handlers | ++--------------------------------------+---------------------------------------+ + +httpd_design_handlers Configuration Options +------------------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| _info | _info | ++--------------------------------------+---------------------------------------+ +| _list | _list | ++--------------------------------------+---------------------------------------+ +| _rewrite | _rewrite | ++--------------------------------------+---------------------------------------+ +| _show | _show | ++--------------------------------------+---------------------------------------+ +| _update | _update | ++--------------------------------------+---------------------------------------+ +| _view | _view | ++--------------------------------------+---------------------------------------+ + +httpd_global_handlers Configuration Options +------------------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| / | / | ++--------------------------------------+---------------------------------------+ +| _active_tasks | _active_tasks | ++--------------------------------------+---------------------------------------+ +| _all_dbs | _all_dbs | ++--------------------------------------+---------------------------------------+ +| _config | _config | ++--------------------------------------+---------------------------------------+ +| _log | _log | ++--------------------------------------+---------------------------------------+ +| _oauth | _oauth | ++--------------------------------------+---------------------------------------+ +| _replicate | _replicate | ++--------------------------------------+---------------------------------------+ +| _restart | _restart | ++--------------------------------------+---------------------------------------+ +| _session | _session | ++--------------------------------------+---------------------------------------+ +| _stats | _stats | ++--------------------------------------+---------------------------------------+ +| _utils | _utils | ++--------------------------------------+---------------------------------------+ +| _uuids | _uuids | ++--------------------------------------+---------------------------------------+ +| favicon.ico | favicon.ico | ++--------------------------------------+---------------------------------------+ + +log Configuration Options +------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| file | file | ++--------------------------------------+---------------------------------------+ +| include_sasl | include_sasl | ++--------------------------------------+---------------------------------------+ +| level | level | ++--------------------------------------+---------------------------------------+ + +query_servers Configuration Options +----------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| javascript | javascript | ++--------------------------------------+---------------------------------------+ + +query_server_config Configuration Options +----------------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| reduce_limit | reduce_limit | ++--------------------------------------+---------------------------------------+ + +replicator Configuration Options +-------------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| max_http_pipeline_size | max_http_pipeline_size | ++--------------------------------------+---------------------------------------+ +| max_http_sessions | max_http_sessions | ++--------------------------------------+---------------------------------------+ + +stats Configuration Options +--------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| rate | rate | ++--------------------------------------+---------------------------------------+ +| samples | samples | ++--------------------------------------+---------------------------------------+ + +uuids Configuration Options +--------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| algorithm | algorithm | ++--------------------------------------+---------------------------------------+ diff --git a/share/doc/src/configuring.rst b/share/doc/src/configuring.rst new file mode 100644 index 000000000..58240d7ab --- /dev/null +++ b/share/doc/src/configuring.rst @@ -0,0 +1,148 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _configuring: + +=================== +Configuring CouchDB +=================== + +.. todo:: Configuring CouchDB + +CouchDB Configuration Files +=========================== + +.. todo:: CouchDB Configuration Files + +Configuration File Locations +============================ + +CouchDB reads files from the following locations, in the following +order. + +1. ``PREFIX/default.ini`` + +2. ``PREFIX/default.d/*`` + +3. ``PREFIX/local.ini`` + +4. ``PREFIX/local.d/*`` + +Settings in successive documents override the settings in earlier +entries. For example, setting the ``bind_address`` parameter in +``local.ini`` would override any setting in ``default.ini``. + +.. warning:: + The ``default.ini`` file may be overwritten during an upgrade or + re-installation, so localised changes should be made to the + ``local.ini`` file or files within the ``local.d`` directory. + +.. _update-notifications: + +Update Notifications +==================== + +.. todo:: Update Notifications + + +MochiWeb Server Options +======================= + +Server options for the MochiWeb component of CouchDB can be added to the +configuration files. Settings should be added to the ``server_options`` +option of the ``[httpd]`` section of ``local.ini``. For example: + +.. code-block:: ini + + [httpd] + server_options = [{backlog, 128}, {acceptor_pool_size, 16}] + +Socket Options Configuration Setting +==================================== + +The socket options for the listening socket in CouchDB can now be set +within the CouchDB configuration file. The setting should be added to +the ``[httpd]`` section of the file using the option name +``socket_options``. The specification is as a list of tuples. For +example: + +.. code-block:: ini + + [httpd] + socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}] + +The options supported are a subset of full options supported by the +TCP/IP stack. A list of the supported options are provided in the +`Erlang inet`_ documentation. + +.. _Erlang inet: http://www.erlang.org/doc/man/inet.html#setopts-2 + +``vhosts`` definitions +====================== + +Similar to the rewrites section of a ``_design`` document, the +``vhosts`` system uses variables in the form of ``:varname`` or wildcards in +the form of asterisks. The variable results can be output into the +resulting path as they are in the rewriter. + + +Configuring Server Administrators +================================= + +A default CouchDB install provides admin-level access to all connecting users. +This configuration is known as ``Admin Party``, and is not recommended for +in-production usage. You can crash the party simply by creating the first +admin account. CouchDB server administrators and passwords are not stored +in the ``_users`` database, but in the ``local.ini`` file, which should be +appropriately secured and readable only by system administrators. + +.. code-block:: ini + + [admins] + ;admin = mysecretpassword + admin = -hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90 + architect = -pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000 + +Administrators can be added directly to the ``[admins]`` section, and when +CouchDB is restarted, the passwords will be salted and encrypted. By using +the HTTP, administrator accounts may be created immediately without needing +a restart, nor of storing the plaintext password temporarily. The HTTP +``_config/admins`` endpoint supports querying, deleting or creating new +administrator accounts: + +.. code-block:: bash + + shell> GET /_config/admins HTTP/1.1 + Accept: application/json + Host: localhost:5984 + + HTTP/1.1 200 OK + Cache-Control: must-revalidate + Content-Length: 196 + Content-Type: application/json + Date: Fri, 30 Nov 2012 11:37:18 GMT + Server: CouchDB/1.3.0 (Erlang OTP/R15B02) + +.. code-block:: json + + { + "admin": "-hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90", + "architect": "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000" + } + +Further details are available in ``security_``, including configuring the +work factor for ``PBKDF2``, and the algorithm itself at +`PBKDF2 (RFC-2898) <http://tools.ietf.org/html/rfc2898>`_. + +.. versionadded:: + 1.3.0 ``PBKDF2`` server-side hashed salted password support added, + now as a synchronous call for the ``_config/admins`` API. diff --git a/share/doc/src/ddocs.rst b/share/doc/src/ddocs.rst new file mode 100644 index 000000000..368f49ea3 --- /dev/null +++ b/share/doc/src/ddocs.rst @@ -0,0 +1,724 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. default-domain:: js + +.. _ddocs: + +=========== +Design Docs +=========== + +In this section we'll show how to write design documents, using the built-in +:ref:`JavaScript Query Server <queryserver_js>`. + +But before we start to write our first function, let's take a look at the list +of common objects that will be used during our code journey - we'll be using +them extensively within each function: + +- :ref:`Database information object <dbinfo_object>` +- :ref:`Request object <request_object>` +- :ref:`Response object <response_object>` +- :ref:`UserCtx object <userctx_object>` +- :ref:`Database Security object <security_object>` +- :ref:`Guide to JavaScript Query Server <queryserver_js>` + +.. _viewfun: + +View functions +============== + +Views are the primary tool used for querying and reporting on CouchDB databases. + +.. _mapfun: + +Map functions +------------- + +.. function:: mapfun(doc) + + :param doc: Processed document object. + +Map functions should take a single argument as document object and optionally +emits paired values also known as `key` and `value`. Since JavaScript +doesn't support generators and ``yield`` statement it is emulated via :func:`emit`: + +.. code-block:: javascript + + function(doc){ + if (!doc.tags || !isArray(doc.tags) || !doc.type || doc.type != 'post'){ + return; + } + for (var idx in doc.tags){ + emit(doc.tags[idx].toLower(), 1); + } + } + +In this example the map function produces documents view by tag if they +has `tags` attribute as array and `type` attribute with "post" value. Note that +:func:`emit` function could be called multiple times, so the same document +will be available by several `keys`. + +Also keep in mind that each document is *sealed* to prevent situation when one +map function changes document state and the other one received a modified +version. + +For efficiency reasons, documents are passed to a group of map functions - +each document is processed by group of map functions from all views of +related design document. This means that if you trigger index update for one +view in ddoc, all others will get updated too. + +Since `1.1.0` release `map` function supports +:ref:`CommonJS <commonjs>` modules and access to :func:`require` function. + +.. _reducefun: + +Reduce and rereduce functions +----------------------------- + +.. function:: redfun(keys, values[, rereduce]) + + :param keys: Array of pairs docid-key for related map function result. + Always ``null`` if rereduce is running (has ``true`` value). + :param values: Array of map function result values. + :param rereduce: Boolean sign of rereduce run. + + :return: Reduces `values` + +Reduce functions takes two required arguments of keys and values lists - the +result of the related map function - and optional third one which indicates if +`rereduce` mode is active or not. `Rereduce` is using for additional reduce +values list, so when it is ``true`` there is no information about related `keys` +(first argument is ``null``). + +Note, that if produced result by `reduce` function is longer than initial +values list then a Query Server error will be raised. However, this behavior +could be disabled by setting ``reduce_limit`` config option to ``false``: + +.. code-block:: ini + + [query_server_config] + reduce_limit = false + +While disabling ``reduce_limit`` might be useful for debug proposes, remember, +that main task of reduce functions is to *reduce* mapped result, not to make it +even bigger. Generally, your reduce function should converge rapidly to a single +value - which could be an array or similar object. + +Also CouchDB has three built-in reduce functions. These are implemented in +Erlang and run right inside CouchDB, so they are much faster than the equivalent +JavaScript functions: ``_sum``, ``_count`` and ``_stats``. Their equivalents in +JavaScript below: + +.. code-block:: javascript + + // could be replaced by _sum + function(keys, values){ + sum(values); + } + + // could be replaced by _count + function(keys, values, rereduce){ + if (rereduce){ + return sum(values); + } else { + return values.length; + } + } + + // could be replaced by _stats + function(keys, values, rereduce){ + return { + 'sum': sum(values), + 'min': Math.min.apply(null, values), + 'max': Math.max.apply(null, values), + 'count': values.length, + 'sumsqr': (function(){ + _sumsqr = 0; + for(var idx in values){ + _sumsqr += values[idx] * values[idx]; + } + return _sumsqr; + })(), + } + } + +.. note:: **Why don't reduce functions support CommonJS modules?** + + While `map` functions have limited access to stored modules through + :func:`require` function there is no such feature for `reduce` functions. + The reason lies deep inside in mechanism how `map` and `reduce` functions + are processed by Query Server. Let's take a look on `map` functions first: + + #. CouchDB sends all `map` functions for processed design document to + Query Server. + #. Query Server handles them one by one, compiles and puts them onto an + internal stack. + #. After all `map` functions had been processed, CouchDB will send the + remaining documents to index one by one. + #. The Query Server receives the document object and applies it to every function + from the stack. The emitted results are then joined into a single array and sent + back to CouchDB. + + Now let's see how `reduce` functions are handled: + + #. CouchDB sends *as single command* list of available `reduce` functions + with result list of key-value pairs that was previously received as + result of `map` functions work. + #. Query Server compiles reduce functions and applies them to key-value + lists. Reduced result sends back to CouchDB. + + As you may note, `reduce` functions been applied in single shot while + `map` ones are applied in an iterative way per each document. This means that + it's possible for `map` functions to precompile CommonJS libraries and use them + during the entire view processing, but for `reduce` functions it will be + compiled again and again for each view result reduction, which will lead to + performance degradation (`reduce` function are already does hard work to make + large result smaller). + + +.. _showfun: + +Show functions +============== + +.. function:: showfun(doc, req) + + :param doc: Processed document, may be omitted. + :param req: :ref:`Request object <request_object>`. + + :return: :ref:`Response object <response_object>` + :rtype: object or string + +Show functions are used to represent documents in various formats, commonly as +HTML page with nicer formatting. They can also be used to run server-side functions +without requiring a pre-existing document. + +Basic example of show function could be: + +.. code-block:: javascript + + function(doc, req){ + if (doc){ + return "Hello from " + doc._id + "!"; + } else { + return "Hello, world!"; + } + } + +Also, there is more simple way to return json encoded data: + +.. code-block:: javascript + + function(doc, req){ + return { + 'json': { + 'id': doc['_id'], + 'rev': doc['_rev'] + } + } + } + + +and even files (this one is CouchDB logo): + +.. code-block:: javascript + + function(doc, req){ + return { + 'headers': { + 'Content-Type' : 'image/png', + }, + 'base64': ''.concat( + 'iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAAsV', + 'BMVEUAAAD////////////////////////5ur3rEBn////////////////wDBL/', + 'AADuBAe9EB3IEBz/7+//X1/qBQn2AgP/f3/ilpzsDxfpChDtDhXeCA76AQH/v7', + '/84eLyWV/uc3bJPEf/Dw/uw8bRWmP1h4zxSlD6YGHuQ0f6g4XyQkXvCA36MDH6', + 'wMH/z8/yAwX64ODeh47BHiv/Ly/20dLQLTj98PDXWmP/Pz//39/wGyJ7Iy9JAA', + 'AADHRSTlMAbw8vf08/bz+Pv19jK/W3AAAAg0lEQVR4Xp3LRQ4DQRBD0QqTm4Y5', + 'zMxw/4OleiJlHeUtv2X6RbNO1Uqj9g0RMCuQO0vBIg4vMFeOpCWIWmDOw82fZx', + 'vaND1c8OG4vrdOqD8YwgpDYDxRgkSm5rwu0nQVBJuMg++pLXZyr5jnc1BaH4GT', + 'LvEliY253nA3pVhQqdPt0f/erJkMGMB8xucAAAAASUVORK5CYII=') + } + } + +But what if you need to represent data in different formats via a single function? +Functions :func:`registerType` and :func:`provides` are your the best friends in +that question: + +.. code-block:: javascript + + function(doc, req){ + provides('json', function(){ + return {'json': doc} + }); + provides('html', function(){ + return '<pre>' + toJSON(doc) + '</pre>' + }) + provides('xml', function(){ + return { + 'headers': {'Content-Type': 'application/xml'}, + 'body' : ''.concat( + '<?xml version="1.0" encoding="utf-8"?>\n', + '<doc>', + (function(){ + escape = function(s){ + return s.replace(/"/g, '"') + .replace(/>/g, '>') + .replace(/</g, '<') + .replace(/&/g, '&'); + }; + var content = ''; + for(var key in doc){ + if(!doc.hasOwnProperty(key)) continue; + var value = escape(toJSON(doc[key])); + var key = escape(key); + content += ''.concat( + '<' + key + '>', + value + '</' + key + '>' + ) + } + return content; + })(), + '</doc>' + ) + } + }) + registerType('text-json', 'text/json') + provides('text-json', function(){ + return toJSON(doc); + }) + } + +This function may return `html`, `json` , `xml` or our custom `text json` format +representation of same document object with same processing rules. Probably, +the `xml` provider in our function needs more care to handle nested objects +correctly, and keys with invalid characters, but you've got the idea! + +.. seealso:: + + CouchDB Wiki: + - `Showing Documents <http://wiki.apache.org/couchdb/Formatting_with_Show_and_List#Showing_Documents>`_ + + CouchDB Guide: + - `Show Functions <http://guide.couchdb.org/editions/1/en/show.html>`_ + + +.. _listfun: + +List functions +============== + +.. function:: listfun(head, req) + + :param head: :ref:`view_head_info_object` + :param req: :ref:`Request object <request_object>`. + + :return: Last chunk. + :rtype: string + +While :ref:`showfun` are used to customize document presentation, :ref:`listfun` +are used for same purpose, but against :ref:`viewfun` results. + +The next list function formats view and represents it as a very simple HTML page: + +.. code-block:: javascript + + function(head, req){ + start({ + 'headers': { + 'Content-Type': 'text/html' + } + }); + send('<html><body><table>'); + send('<tr><th>ID</th><th>Key</th><th>Value</th></tr>') + while(row = getRow()){ + send(''.concat( + '<tr>', + '<td>' + toJSON(row.id) + '</td>', + '<td>' + toJSON(row.key) + '</td>', + '<td>' + toJSON(row.value) + '</td>', + '</tr>' + )); + } + send('</table></body></html>'); + } + +Templates and styles could obviously be used to present data in a nicer +fashion, but this is an excellent starting point. Note that you may also +use :func:`registerType` and :func:`provides` functions in the same +way as for :ref:`showfun`! + +.. seealso:: + + CouchDB Wiki: + - `Listing Views with CouchDB 0.10 and later <http://wiki.apache.org/couchdb/Formatting_with_Show_and_List#Listing_Views_with_CouchDB_0.10_and_later>`_ + + CouchDB Guide: + - `Transforming Views with List Functions <http://guide.couchdb.org/draft/transforming.html>`_ + + +.. _updatefun: + +Update functions +================ + +.. function:: updatefun(doc, req) + + :param doc: Update function target document. + :param req: :ref:`request_object` + + :returns: Two-element array: the first element is the (updated or new) + document, which is committed to the database. If the first element + is ``null`` no document will be committed to the database. + If you are updating an existing, it should already have an ``_id`` + set, and if you are creating a new document, make sure to set its + ``_id`` to something, either generated based on the input or the + ``req.uuid`` provided. The second element is the response that will + be sent back to the caller. + +Update handlers are functions that clients can request to invoke server-side +logic that will create or update a document. This feature allows a range of use +cases such as providing a server-side last modified timestamp, updating +individual fields in a document without first getting the latest revision, etc. + +When the request to an update handler includes a document ID in the URL, the +server will provide the function with the most recent version of that document. +You can provide any other values needed by the update handler function via the +``POST``/``PUT`` entity body or query string parameters of the request. + +The basic example that demonstrates all use-cases of update handlers below: + +.. code-block:: javascript + + function(doc, req){ + if (!doc){ + if ('id' in req){ + // create new document + return [{'_id': req['id']}, 'New World'] + } + // change nothing in database + return [null, 'Empty World'] + } + doc['world'] = 'hello'; + doc['edited_by'] = req['userCtx']['name'] + return [doc, 'Edited World!'] + } + +.. seealso:: + + CouchDB Wiki: + - `Document Update Handlers <http://wiki.apache.org/couchdb/Document_Update_Handlers>`_ + + +.. _filterfun: + +Filter functions +================ + +.. function:: filterfun(doc, req) + + :param doc: Processed document object. + :param req: :ref:`request_object` + :return: Boolean value: ``true`` means that `doc` passes the filter rules, + ``false`` that not. + +Filter functions are mostly acts like :ref:`showfun` and :ref:`listfun`: they +formats, but more correctly to say, they *filters* :ref:`changes feed<changes>`. + +Classic filters +--------------- + +By default the changes feed emits all database documents changes. But if you're +waiting for some special changes, processing all documents is inefficient. + +Filters are special design document functions that allows changes feed to emit +only specific documents that pass filter rules. + +Lets assume that our database is a mailbox and we need to to handle only new mails +(documents with status `new`) events. Assuming that, our filter function +will looks like next one: + +.. code-block:: javascript + + function(doc, req){ + // we need only `mail` documents + if (doc.type != 'mail'){ + return false; + } + // we're interested only in `new` ones + if (doc.status != 'new'){ + return false; + } + return true; // passed! + } + +Filter functions must return ``true`` in fact if document passed all defined +rules. Now, if you apply this function to changes feed it will emit only changes +about "new mails":: + + GET /somedatabase/_changes?filter=mailbox/new_mail HTTP/1.1 + +.. code-block:: javascript + + {"results":[ + {"seq":1,"id":"df8eca9da37dade42ee4d7aa3401f1dd","changes":[{"rev":"1-c2e0085a21d34fa1cecb6dc26a4ae657"}]}, + {"seq":7,"id":"df8eca9da37dade42ee4d7aa34024714","changes":[{"rev":"1-29d748a6e87b43db967fe338bcb08d74"}]}, + ], + "last_seq":27} + +Note, that ``last_seq`` number is 27, but we'd received only two records. +Seems like any other changes was about documents that hasn't passed our filter. + +Probably, we also need to filter changes feed of our mailbox not only by single +status value: we're also interested in statuses like "spam" to update +spam-filter heuristic rules, "outgoing" to let mail daemon actually send mails +and so on. Creating a lot of similar functions that actually does similar work +isn't good idea - so we need dynamic filter to go. + +If you have noted, filter functions takes second argument as +:ref:`request <request_object>` object - it allows to create dynamic filters +based on query parameters, :ref:`user context <userctx_object>` and more. + +The dynamic version of our filter now will be next: + +.. code-block:: javascript + + function(doc, req){ + // we need only `mail` documents + if (doc.type != 'mail'){ + return false; + } + // we're interested only in requested status + if (doc.status != req.query.status){ + return false; + } + return true; // passed! + } + +and now we have pass `status` query parameter in request to let filter match +only required documents:: + + GET /somedatabase/_changes?filter=mailbox/by_status&status=new HTTP/1.1 + +.. code-block:: javascript + + {"results":[ + {"seq":1,"id":"df8eca9da37dade42ee4d7aa3401f1dd","changes":[{"rev":"1-c2e0085a21d34fa1cecb6dc26a4ae657"}]}, + {"seq":7,"id":"df8eca9da37dade42ee4d7aa34024714","changes":[{"rev":"1-29d748a6e87b43db967fe338bcb08d74"}]}, + ], + "last_seq":27} + +and we can change filter behavior with easy:: + + GET /somedatabase/_changes?filter=mailbox/by_status&status=spam HTTP/1.1 + +.. code-block:: javascript + + {"results":[ + {"seq":11,"id":"8960e91220798fc9f9d29d24ed612e0d","changes":[{"rev":"3-cc6ff71af716ddc2ba114967025c0ee0"}]}, + ], + "last_seq":27} + + +Combining filters with `continuous` feed allows to create powerful event-driven +systems. + +View filters +------------ + +View filters are the same as above, with one small difference: they use +views `map` function instead to `filter` one to process the changes feed. Each +time when a key-value pair could be emitted, a change is returned. This allows +to avoid creating filter functions that are mostly does same works as views. + +To use them just specify `_view` value for ``filter`` parameter and +`designdoc/viewname` for ``view`` one:: + + GET /somedatabase/_changes?filter=_view&view=dname/viewname HTTP/1.1 + +.. note:: + + Since view filters uses `map` functions as filters, they can't show any + dynamic behavior since :ref:`request object<request_object>` is not + available. + +.. seealso:: + + CouchDB Guide: + - `Guide to filter change notification <http://guide.couchdb.org/draft/notifications.html#filters>`_ + + CouchDB Wiki: + - `Filtered replication <http://wiki.apache.org/couchdb/Replication#Filtered_Replication>`_ + + +.. _vdufun: + +Validate document update functions +================================== + +.. function:: validatefun(newDoc, oldDoc, userCtx, secObj) + + :param newDoc: New version of document that will be stored. + :param oldDoc: Previous version of document that is already stored. + :param userCtx: :ref:`userctx_object` + :param secObj: :ref:`security_object` + + :throws: ``forbidden`` error to gracefully prevent document storing. + +To perform validate operations on document saving there is a special design +function type called `validate_doc_update`. + +Instead of thousands words take a look at the next example of validate +function - this function is used in ``_design/_auth`` ddoc from `_users` +database to control users documents required field set and modification +permissions: + +.. code-block:: javascript + + function(newDoc, oldDoc, userCtx, secObj) { + if (newDoc._deleted === true) { + // allow deletes by admins and matching users + // without checking the other fields + if ((userCtx.roles.indexOf('_admin') !== -1) || + (userCtx.name == oldDoc.name)) { + return; + } else { + throw({forbidden: 'Only admins may delete other user docs.'}); + } + } + + if ((oldDoc && oldDoc.type !== 'user') || newDoc.type !== 'user') { + throw({forbidden : 'doc.type must be user'}); + } // we only allow user docs for now + + if (!newDoc.name) { + throw({forbidden: 'doc.name is required'}); + } + + if (!newDoc.roles) { + throw({forbidden: 'doc.roles must exist'}); + } + + if (!isArray(newDoc.roles)) { + throw({forbidden: 'doc.roles must be an array'}); + } + + if (newDoc._id !== ('org.couchdb.user:' + newDoc.name)) { + throw({ + forbidden: 'Doc ID must be of the form org.couchdb.user:name' + }); + } + + if (oldDoc) { // validate all updates + if (oldDoc.name !== newDoc.name) { + throw({forbidden: 'Usernames can not be changed.'}); + } + } + + if (newDoc.password_sha && !newDoc.salt) { + throw({ + forbidden: 'Users with password_sha must have a salt.' + + 'See /_utils/script/couch.js for example code.' + }); + } + + var is_server_or_database_admin = function(userCtx, secObj) { + // see if the user is a server admin + if(userCtx.roles.indexOf('_admin') !== -1) { + return true; // a server admin + } + + // see if the user a database admin specified by name + if(secObj && secObj.admins && secObj.admins.names) { + if(secObj.admins.names.indexOf(userCtx.name) !== -1) { + return true; // database admin + } + } + + // see if the user a database admin specified by role + if(secObj && secObj.admins && secObj.admins.roles) { + var db_roles = secObj.admins.roles; + for(var idx = 0; idx < userCtx.roles.length; idx++) { + var user_role = userCtx.roles[idx]; + if(db_roles.indexOf(user_role) !== -1) { + return true; // role matches! + } + } + } + + return false; // default to no admin + } + + if (!is_server_or_database_admin(userCtx, secObj)) { + if (oldDoc) { // validate non-admin updates + if (userCtx.name !== newDoc.name) { + throw({ + forbidden: 'You may only update your own user document.' + }); + } + // validate role updates + var oldRoles = oldDoc.roles.sort(); + var newRoles = newDoc.roles.sort(); + + if (oldRoles.length !== newRoles.length) { + throw({forbidden: 'Only _admin may edit roles'}); + } + + for (var i = 0; i < oldRoles.length; i++) { + if (oldRoles[i] !== newRoles[i]) { + throw({forbidden: 'Only _admin may edit roles'}); + } + } + } else if (newDoc.roles.length > 0) { + throw({forbidden: 'Only _admin may set roles'}); + } + } + + // no system roles in users db + for (var i = 0; i < newDoc.roles.length; i++) { + if (newDoc.roles[i][0] === '_') { + throw({ + forbidden: + 'No system roles (starting with underscore) in users db.' + }); + } + } + + // no system names as names + if (newDoc.name[0] === '_') { + throw({forbidden: 'Username may not start with underscore.'}); + } + + var badUserNameChars = [':']; + + for (var i = 0; i < badUserNameChars.length; i++) { + if (newDoc.name.indexOf(badUserNameChars[i]) >= 0) { + throw({forbidden: 'Character `' + badUserNameChars[i] + + '` is not allowed in usernames.'}); + } + } + } + +.. note:: + + The ``return`` statement used only for function, it has no impact on + the validation process. + +.. seealso:: + + CouchDB Guide: + - `Validation Functions <http://guide.couchdb.org/editions/1/en/validation.html>`_ + + CouchDB Wiki: + - `Document Update Validation <http://wiki.apache.org/couchdb/Document_Update_Validation>`_ diff --git a/share/doc/src/errors.rst b/share/doc/src/errors.rst new file mode 100644 index 000000000..431ff9100 --- /dev/null +++ b/share/doc/src/errors.rst @@ -0,0 +1,37 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +Error Messages +============== + +The errors reported when CouchDB is unable to read a required file have +been updated so that explicit information about the files and problem +can now be identified from the error message. The errors report file +permission access either when reading or writing to configuration and +database files. + +The error is raised both through the log file and the error message +returned through the API call as a JSON error message. For example, when +setting configuration values: + +.. code-block:: bash + + shell> curl -X PUT http://couchdb:5984/_config/couchdb/delayed_commits \ + -H 'X-Couch-Persist: true' -d '"false"' + {"error":"file_permission_error","reason":"/etc/couchdb/local.ini"} + +Errors will always be reported using the ``file_permission_error`` error +type. + +During startup permissions errors on key files are also reported in the +log with a descriptive error message and file location so that +permissions can be fixed before restart. diff --git a/share/doc/src/http-proxying.rst b/share/doc/src/http-proxying.rst new file mode 100644 index 000000000..cff2404c5 --- /dev/null +++ b/share/doc/src/http-proxying.rst @@ -0,0 +1,94 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _http-proxying: + +HTTP Proxying +============= + +The HTTP proxy feature makes it easy to map and redirect different +content through your CouchDB URL. The proxy works by mapping a pathname +and passing all content after that prefix through to the configured +proxy address. + +Configuration of the proxy redirect is handled through the +``[httpd_global_handlers]`` section of the CouchDB configuration file +(typically ``local.ini``). The format is: + +.. code-block:: ini + + [httpd_global_handlers] + PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>} + + +Where: + +- ``PREFIX`` + + Is the string that will be matched. The string can be any valid + qualifier, although to ensure that existing database names are not + overridden by a proxy configuration, you can use an underscore + prefix. + +- ``DESTINATION`` + + The fully-qualified URL to which the request should be sent. The + destination must include the ``http`` prefix. The content is used + verbatim in the original request, so you can also forward to servers + on different ports and to specific paths on the target host. + +The proxy process then translates requests of the form: + +.. code-block:: text + + http://couchdb:5984/PREFIX/path + +To: + +.. code-block:: text + + DESTINATION/path + +.. note:: + Everything after ``PREFIX`` including the required forward slash + will be appended to the ``DESTINATION``. + +The response is then communicated back to the original client. + +For example, the following configuration: + +.. code-block:: ini + + _google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>} + +Would forward all requests for ``http://couchdb:5984/_google`` to the +Google website. + +The service can also be used to forward to related CouchDB services, +such as Lucene: + +.. code-block:: ini + + [httpd_global_handlers] + _fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>} + +.. note:: + The proxy service is basic. If the request is not identified by the + ``DESTINATION``, or the remainder of the ``PATH`` specification is + incomplete, the original request URL is interpreted as if the + ``PREFIX`` component of that URL does not exist. + + For example, requesting ``http://couchdb:5984/_intranet/media`` when + ``/media`` on the proxy destination does not exist, will cause the + request URL to be interpreted as ``http://couchdb:5984/media``. Care + should be taken to ensure that both requested URLs and destination + URLs are able to cope. diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst new file mode 100644 index 000000000..ad3a90d17 --- /dev/null +++ b/share/doc/src/index.rst @@ -0,0 +1,52 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +Introduction +============ + +|Apache CouchDB(TM)|_ is a document database built for the web. + +If you would like to help document the project, please send a note to the +`developer mailing list <http://couchdb.apache.org/#mailing-list>`_. + +This is a work in progress. + +Contents +======== + +.. toctree:: + :maxdepth: 2 + :numbered: + + intro + api-basics + range + pretty_urls + configuring + ssl + os-daemons + http-proxying + config_reference + replication + ddocs + query-servers + commonjs + errors + changes + release + api/reference + json-structure + changelog + +.. This is how you get a TM sign into a link. Haha. Seriously. +.. |Apache CouchDB(TM)| unicode:: Apache U+0020 CouchDB U+2122 +.. _Apache CouchDB(TM): http://couchdb.apache.org/ diff --git a/share/doc/src/intro.rst b/share/doc/src/intro.rst new file mode 100644 index 000000000..b5930d340 --- /dev/null +++ b/share/doc/src/intro.rst @@ -0,0 +1,309 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +============ +Introduction +============ + +There are two interfaces to CouchDB, the built-in Futon web-based +interface and the CouchDB API accessed through the HTTP REST interface. +The former is the simplest way to view and monitor your CouchDB +installation and perform a number of basic database and system +operations. More information on using the Futon interface can be found +in :ref:`using-futon`. + +The primary way to interact with the CouchDB API is to use a client +library or other interface that provides access to the underlying +functionality through your chosen language or platform. However, since +the API is supported through HTTP REST, you can interact with your +CouchDB with any solution that supports the HTTP protocol. + +There are a number of different tools that talk the HTTP protocol and +allow you to set and configure the necessary information. One tool for +this that allows for access from the command-line is ``curl``. See +:ref:`using-curl`. + +.. _using-futon: + +Using Futon +=========== + +Futon is a native web-based interface built into CouchDB. It provides a +basic interface to the majority of the functionality, including the +ability to create, update, delete and view documents and views, provides +access to the configuration parameters, and an interface for initiating +replication. + +The default view is the Overview page which provides you with a list of +the databases. The basic structure of the page is consistent regardless +of the section you are in. The main panel on the left provides the main +interface to the databases, configuration or replication systems. The +side panel on the right provides navigation to the main areas of Futon +interface: + +.. figure:: ../images/futon-overview.png + :align: center + :alt: Futon Overview + + Futon Overview + +The main sections are: + +- Overview + + The main overview page, which provides a list of the databases and + provides the interface for querying the database and creating and + updating documents. See :ref:`futon-management`. + +- Configuration + + An interface into the configuration of your CouchDB installation. The + interface allows you to edit the different configurable parameters. + For more details on configuration, see :ref:`configuring`. + +- Replicator + + An interface to the replication system, enabling you to initiate + replication between local and remote databases. See + :ref:`futon-replication`. + +- Status + + Displays a list of the running background tasks on the server. + Background tasks include view index building, compaction and + replication. The Status page is an interface to the + :ref:`Active Tasks <active-tasks>` API call. + +- Verify Installation + + The Verify Installation allows you to check whether all of the + components of your CouchDB installation are correctly installed. + +- Test Suite + + The Test Suite section allows you to run the built-in test suite. + This executes a number of test routines entirely within your browser + to test the API and functionality of your CouchDB installation. If + you select this page, you can run the tests by using the Run All + button. This will execute all the tests, which may take some time. + +.. _futon-management: + +Managing Databases and Documents +-------------------------------- + +You can manage databases and documents within Futon using the main +Overview section of the Futon interface. + +To create a new database, click the Create Database ELLIPSIS button. You +will be prompted for the database name, as shown in the figure below. + +.. figure:: ../images/futon-createdb.png + :align: center + :alt: Creating a Database + + Creating a Database + +Once you have created the database (or selected an existing one), you +will be shown a list of the current documents. If you create a new +document, or select an existing document, you will be presented with the +edit document display. + +Editing documents within Futon requires selecting the document and then +editing (and setting) the fields for the document individually before +saving the document back into the database. + +For example, the figure below shows the editor for a single document, a +newly created document with a single ID, the document ``_id`` field. + +.. figure:: ../images/futon-editdoc.png + :align: center + :alt: Editing a Document + + Editing a Document + +To add a field to the document: + +1. Click Add Field. + +2. In the fieldname box, enter the name of the field you want to create. + For example, “company”. + +3. Click the green tick next to the field name to confirm the field name + change. + +4. Double-click the corresponding Value cell. + +5. Enter a company name, for example “Example”. + +6. Click the green tick next to the field value to confirm the field + value. + +7. The document is still not saved as this point. You must explicitly + save the document by clicking the Save Document button at the top of + the page. This will save the document, and then display the new + document with the saved revision information (the ``_rev`` field). + + .. figure:: ../images/futon-editeddoc.png + :align: center + :alt: Edited Document + + Edited Document + +The same basic interface is used for all editing operations within Futon. +You *must* remember to save the individual element (fieldname, value) +using the green tick button, before then saving the document. + +.. _futon-replication: + +Configuring Replication +----------------------- + +When you click the Replicator option within the Tools menu you are +presented with the Replicator screen. This allows you to start +replication between two databases by filling in or select the +appropriate options within the form provided. + +.. figure:: ../images/futon-replform.png + :align: center + :alt: Replication Form + + Replication Form + +To start a replication process, either the select the local database or +enter a remote database name into the corresponding areas of the form. +Replication occurs from the database on the left to the database on the +right. + +If you are specifying a remote database name, you must specify the full +URL of the remote database (including the host, port number and database +name). If the remote instance requires authentication, you can specify +the username and password as part of the URL, for example +``http://username:pass@remotehost:5984/demo``. + +To enable continuous replication, click the Continuous checkbox. + +To start the replication process, click the Replicate button. The +replication process should start and will continue in the background. If +the replication process will take a long time, you can monitor the +status of the replication using the Status option under the Tools menu. + +Once replication has been completed, the page will show the information +returned when the replication process completes by the API. + +The Replicator tool is an interface to the underlying replication API. +For more information, see :ref:`replicate`. For more information on +replication, see :ref:`replication`. + +.. _using-curl: + +Using ``curl`` +============== + +The ``curl`` utility is a command line tool available on Unix, Linux, +Mac OS X and Windows and many other platforms. ``curl`` provides easy +access to the HTTP protocol (among others) directly from the +command-line and is therefore an ideal way of interacting with CouchDB +over the HTTP REST API. + +For simple ``GET`` requests you can supply the URL of the request. For +example, to get the database information: + +.. code-block:: bash + + shell> curl http://127.0.0.1:5984 + +This returns the database information (formatted in the output below for +clarity): + +.. code-block:: json + + { + "couchdb" : "Welcome", + "version" : "|version|", + } + +.. note:: For some URLs, especially those that include special characters such + as ampersand, exclamation mark, or question mark, you should quote + the URL you are specifying on the command line. For example: + + .. code-block:: bash + + shell> curl 'http://couchdb:5984/_uuids?count=5' + +You can explicitly set the HTTP command using the ``-X`` command line +option. For example, when creating a database, you set the name of the +database in the URL you send using a PUT request: + +.. code-block:: bash + + shell> curl -X PUT http://127.0.0.1:5984/demo + {"ok":true} + +But to obtain the database information you use a ``GET`` request (with +the return information formatted for clarity): + +.. code-block:: bash + + shell> curl -X GET http://127.0.0.1:5984/demo + { + "compact_running" : false, + "doc_count" : 0, + "db_name" : "demo", + "purge_seq" : 0, + "committed_update_seq" : 0, + "doc_del_count" : 0, + "disk_format_version" : 5, + "update_seq" : 0, + "instance_start_time" : "1306421773496000", + "disk_size" : 79 + } + +For certain operations, you must specify the content type of request, +which you do by specifying the ``Content-Type`` header using the ``-H`` +command-line option: + +.. code-block:: bash + + shell> curl -H 'Content-Type: application/json' http://127.0.0.1:5984/_uuids + +You can also submit 'payload' data, that is, data in the body of the +HTTP request using the ``-d`` option. This is useful if you need to +submit JSON structures, for example document data, as part of the +request. For example, to submit a simple document to the ``demo`` +database: + +.. code-block:: bash + + shell> curl -H 'Content-Type: application/json' \ + -X POST http://127.0.0.1:5984/demo \ + -d '{"company": "Example, Inc."}' + {"ok":true,"id":"8843faaf0b831d364278331bc3001bd8", + "rev":"1-33b9fbce46930280dab37d672bbc8bb9"} + +In the above example, the argument after the ``-d`` option is the JSON +of the document we want to submit. + +The document can be accessed by using the automatically generated +document ID that was returned: + +.. code-block:: bash + + shell> curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8 + {"_id":"8843faaf0b831d364278331bc3001bd8", + "_rev":"1-33b9fbce46930280dab37d672bbc8bb9", + "company":"Example, Inc."} + +The API samples in the :ref:`api-basics` show the HTTP command, URL and any +payload information that needs to be submitted (and the expected return +value). All of these examples can be reproduced using ``curl`` with the +command-line examples shown above. diff --git a/share/doc/src/json-structure.rst b/share/doc/src/json-structure.rst new file mode 100644 index 000000000..aaba09e16 --- /dev/null +++ b/share/doc/src/json-structure.rst @@ -0,0 +1,658 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +======================== +JSON Structure Reference +======================== + +The following appendix provides a quick reference to all the JSON structures +that you can supply to CouchDB, or get in return to requests. + +All Database Documents +====================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| total_rows | Number of documents in the database/view | ++--------------------------------+---------------------------------------------+ +| offset | Offset where the document list started | ++--------------------------------+---------------------------------------------+ +| update_seq (optional) | Current update sequence for the database | ++--------------------------------+---------------------------------------------+ +| rows [array] | Array of document object | ++--------------------------------+---------------------------------------------+ + +Bulk Document Response +====================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| docs [array] | Bulk Docs Returned Documents | ++--------------------------------+---------------------------------------------+ +| id | Document ID | ++--------------------------------+---------------------------------------------+ +| error | Error type | ++--------------------------------+---------------------------------------------+ +| reason | Error string with extended reason | ++--------------------------------+---------------------------------------------+ + +Bulk Documents +============== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| all_or_nothing (optional) | Sets the database commit mode to use | +| | all-or-nothing semantics | ++--------------------------------+---------------------------------------------+ +| docs [array] | Bulk Documents Document | ++--------------------------------+---------------------------------------------+ +| _id (optional) | Document ID | ++--------------------------------+---------------------------------------------+ +| _rev (optional) | Revision ID (when updating an existing | +| | document) | ++--------------------------------+---------------------------------------------+ +| _deleted (optional) | Whether the document should be deleted | ++--------------------------------+---------------------------------------------+ + +Changes information for a database +================================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| last_seq | Last change sequence number | ++--------------------------------+---------------------------------------------+ +| results [array] | Changes made to a database | ++--------------------------------+---------------------------------------------+ +| seq | Update sequence number | ++--------------------------------+---------------------------------------------+ +| id | Document ID | ++--------------------------------+---------------------------------------------+ +| changes [array] | List of changes, field-by-field, for this | +| | document | ++--------------------------------+---------------------------------------------+ + +CouchDB Document +================ + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| _id (optional) | Document ID | ++--------------------------------+---------------------------------------------+ +| _rev (optional) | Revision ID (when updating an existing | +| | document) | ++--------------------------------+---------------------------------------------+ + +CouchDB Error Status +==================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| id | Document ID | ++--------------------------------+---------------------------------------------+ +| error | Error type | ++--------------------------------+---------------------------------------------+ +| reason | Error string with extended reason | ++--------------------------------+---------------------------------------------+ + +.. _dbinfo_object: + +CouchDB database information object +=================================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| db_name | The name of the database. | ++--------------------------------+---------------------------------------------+ +| committed_update_seq | The number of committed update. | ++--------------------------------+---------------------------------------------+ +| doc_count | A count of the documents in the specified | +| | database. | ++--------------------------------+---------------------------------------------+ +| doc_del_count | Number of deleted documents | ++--------------------------------+---------------------------------------------+ +| compact_running | Set to true if the database compaction | +| | routine is operating on this database. | ++--------------------------------+---------------------------------------------+ +| disk_format_version | The version of the physical format used for | +| | the data when it is stored on disk. | ++--------------------------------+---------------------------------------------+ +| disk_size | Size in bytes of the data as stored on the | +| | disk. Views indexes are not included in the | +| | calculation. | ++--------------------------------+---------------------------------------------+ +| instance_start_time | Timestamp of when the database was created, | +| | expressed in milliseconds since the epoch. | ++--------------------------------+---------------------------------------------+ +| purge_seq | The number of purge operations on the | +| | database. | ++--------------------------------+---------------------------------------------+ +| update_seq | The current number of updates to the | +| | database. | ++--------------------------------+---------------------------------------------+ + +Design Document +=============== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| _id | Design Document ID | ++--------------------------------+---------------------------------------------+ +| _rev | Design Document Revision | ++--------------------------------+---------------------------------------------+ +| views | View | ++--------------------------------+---------------------------------------------+ +| viewname | View Definition | ++--------------------------------+---------------------------------------------+ +| map | Map Function for View | ++--------------------------------+---------------------------------------------+ +| reduce (optional) | Reduce Function for View | ++--------------------------------+---------------------------------------------+ + +Design Document Information +=========================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| name | Name/ID of Design Document | ++--------------------------------+---------------------------------------------+ +| view_index | View Index | ++--------------------------------+---------------------------------------------+ +| compact_running | Indicates whether a compaction routine is | +| | currently running on the view | ++--------------------------------+---------------------------------------------+ +| disk_size | Size in bytes of the view as stored on disk | ++--------------------------------+---------------------------------------------+ +| language | Language for the defined views | ++--------------------------------+---------------------------------------------+ +| purge_seq | The purge sequence that has been processed | ++--------------------------------+---------------------------------------------+ +| signature | MD5 signature of the views for the design | +| | document | ++--------------------------------+---------------------------------------------+ +| update_seq | The update sequence of the corresponding | +| | database that has been indexed | ++--------------------------------+---------------------------------------------+ +| updater_running | Indicates if the view is currently being | +| | updated | ++--------------------------------+---------------------------------------------+ +| waiting_clients | Number of clients waiting on views from this| +| | design document | ++--------------------------------+---------------------------------------------+ +| waiting_commit | Indicates if there are outstanding commits | +| | to the underlying database that need to | +| | processed | ++--------------------------------+---------------------------------------------+ + +Design Document spatial index Information +========================================= + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| name | Name/ID of Design Document | ++--------------------------------+---------------------------------------------+ +| spatial_index | View Index | ++--------------------------------+---------------------------------------------+ +| compact_running | Indicates whether a compaction routine is | +| | currently running on the view | ++--------------------------------+---------------------------------------------+ +| disk_size | Size in bytes of the view as stored on disk | ++--------------------------------+---------------------------------------------+ +| language | Language for the defined views | ++--------------------------------+---------------------------------------------+ +| purge_seq | The purge sequence that has been processed | ++--------------------------------+---------------------------------------------+ +| signature | MD5 signature of the views for the design | +| | document | ++--------------------------------+---------------------------------------------+ +| update_seq | The update sequence of the corresponding | +| | database that has been indexed | ++--------------------------------+---------------------------------------------+ +| updater_running | Indicates if the view is currently being | +| | updated | ++--------------------------------+---------------------------------------------+ +| waiting_clients | Number of clients waiting on views from this| +| | design document | ++--------------------------------+---------------------------------------------+ +| waiting_commit | Indicates if there are outstanding commits | +| | to the underlying database that need to | +| | processed | ++--------------------------------+---------------------------------------------+ + +Document with Attachments +========================= + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| _id (optional) | Document ID | ++--------------------------------+---------------------------------------------+ +| _rev (optional) | Revision ID (when updating an existing | +| | document) | ++--------------------------------+---------------------------------------------+ +| _attachments (optional) | Document Attachment | ++--------------------------------+---------------------------------------------+ +| filename | Attachment information | ++--------------------------------+---------------------------------------------+ +| content_type | MIME Content type string | ++--------------------------------+---------------------------------------------+ +| data | File attachment content, Base64 encoded | ++--------------------------------+---------------------------------------------+ + +List of Active Tasks +==================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| tasks [array] | Active Task | ++--------------------------------+---------------------------------------------+ +| pid | Process ID | ++--------------------------------+---------------------------------------------+ +| status | Task status message | ++--------------------------------+---------------------------------------------+ +| task | Task name | ++--------------------------------+---------------------------------------------+ +| type | Operation Type | ++--------------------------------+---------------------------------------------+ + +Replication Settings +==================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| source | Source database name or URL | ++--------------------------------+---------------------------------------------+ +| target | Target database name or URL | ++--------------------------------+---------------------------------------------+ +| create_target (optional) | Creates the target database | ++--------------------------------+---------------------------------------------+ +| continuous (optional) | Configure the replication to be continuous | ++--------------------------------+---------------------------------------------+ +| cancel (optional) | Cancels the replication | ++--------------------------------+---------------------------------------------+ +| doc_ids (optional) | Array of document IDs to be synchronized | ++--------------------------------+---------------------------------------------+ +| proxy (optional) | Address of a proxy server through which | +| | replication should occur | ++--------------------------------+---------------------------------------------+ + +Replication Status +================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| ok | Replication status | ++--------------------------------+---------------------------------------------+ +| session_id | Unique session ID | ++--------------------------------+---------------------------------------------+ +| source_last_seq | Last sequence number read from source | +| | database | ++--------------------------------+---------------------------------------------+ +| history [array] | Replication History | ++--------------------------------+---------------------------------------------+ +| session_id | Session ID for this replication operation | ++--------------------------------+---------------------------------------------+ +| recorded_seq | Last recorded sequence number | ++--------------------------------+---------------------------------------------+ +| docs_read | Number of documents read | ++--------------------------------+---------------------------------------------+ +| docs_written | Number of documents written to target | ++--------------------------------+---------------------------------------------+ +| doc_write_failures | Number of document write failures | ++--------------------------------+---------------------------------------------+ +| start_time | Date/Time replication operation started | ++--------------------------------+---------------------------------------------+ +| start_last_seq | First sequence number in changes stream | ++--------------------------------+---------------------------------------------+ +| end_time | Date/Time replication operation completed | ++--------------------------------+---------------------------------------------+ +| end_last_seq | Last sequence number in changes stream | ++--------------------------------+---------------------------------------------+ +| missing_checked | Number of missing documents checked | ++--------------------------------+---------------------------------------------+ +| missing_found | Number of missing documents found | ++--------------------------------+---------------------------------------------+ + +.. _request_object: + +Request object +============== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| body | Request body data as `string`. | +| | If request method is `GET` method contains | +| | this field contains ``"undefined"`` value, | +| | while if `DELETE` or `HEAD` value is ``""`` | +| | (empty string) | ++--------------------------------+---------------------------------------------+ +| cookie | Cookies `object`. | ++--------------------------------+---------------------------------------------+ +| form | Form data `object`. | +| | Contains decoded body as key-value pairs if | +| | `Content-Type` header was | +| | ``application/x-www-form-urlencoded``. | ++--------------------------------+---------------------------------------------+ +| headers | Request headers `object`. | ++--------------------------------+---------------------------------------------+ +| id | Requested document id `string` if it was | +| | specified or ``null`` otherwise. | ++--------------------------------+---------------------------------------------+ +| info | :ref:`Database information <dbinfo_object>` | ++--------------------------------+---------------------------------------------+ +| method | Request method as `string` or `array`. | +| | String value is method is one of: `HEAD`, | +| | `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS`, | +| | and `TRACE`, otherwise it will be | +| | represented as array of char codes. | ++--------------------------------+---------------------------------------------+ +| path | List of requested path sections. | ++--------------------------------+---------------------------------------------+ +| peer | Request source IP address. | ++--------------------------------+---------------------------------------------+ +| query | URL query parameters `object`. | +| | Note that multiple keys not supported and | +| | last key value suppress others. | ++--------------------------------+---------------------------------------------+ +| requested_path | List of actual requested path section. | ++--------------------------------+---------------------------------------------+ +| raw_path | Raw requested path `string`. | ++--------------------------------+---------------------------------------------+ +| secObj | :ref:`security_object`. | ++--------------------------------+---------------------------------------------+ +| userCtx | :ref:`userctx_object`. | ++--------------------------------+---------------------------------------------+ +| uuid | Generated UUID by specified algorithm in | +| | config file. | ++--------------------------------+---------------------------------------------+ + +.. code-block:: javascript + + { + "body": "undefined", + "cookie": { + "AuthSession": "cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw", + "m": "3234" + }, + "form": {}, + "headers": { + "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", + "Accept-Charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.3", + "Accept-Encoding": "gzip,deflate,sdch", + "Accept-Language": "en-US,en;q=0.8", + "Connection": "keep-alive", + "Cookie": "m=3234:t|3247:t|6493:t|6967:t|34e2:|18c3:t|2c69:t|5acb:t|ca3:t|c01:t|5e55:t|77cb:t|2a03:t|1d98:t|47ba:t|64b8:t|4a01:t; AuthSession=cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw", + "Host": "127.0.0.1:5984", + "User-Agent": "Mozilla/5.0 (Windows NT 5.2) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.75 Safari/535.7" + }, + "id": "foo", + "info": { + "committed_update_seq": 2701412, + "compact_running": false, + "data_size": 7580843252, + "db_name": "mailbox", + "disk_format_version": 6, + "disk_size": 14325313673, + "doc_count": 2262757, + "doc_del_count": 560, + "instance_start_time": "1347601025628957", + "purge_seq": 0, + "update_seq": 2701412 + }, + "method": "GET", + "path": [ + "mailbox", + "_design", + "request", + "_show", + "dump", + "foo" + ], + "peer": "127.0.0.1", + "query": {}, + "raw_path": "/mailbox/_design/request/_show/dump/foo", + "requested_path": [ + "mailbox", + "_design", + "request", + "_show", + "dump", + "foo" + ], + "secObj": { + "admins": { + "names": [ + "Bob" + ], + "roles": [] + }, + "members": { + "names": [ + "Mike", + "Alice" + ], + "roles": [] + } + }, + "userCtx": { + "db": "mailbox", + "name": "Mike", + "roles": [ + "user" + ] + }, + "uuid": "3184f9d1ea934e1f81a24c71bde5c168" + } + + +.. _response_object: + +Response object +=============== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| code | HTTP status code `number`. | ++--------------------------------+---------------------------------------------+ +| json | JSON encodable `object`. | +| | Implicitly sets `Content-Type` header as | +| | ``application/json``. | ++--------------------------------+---------------------------------------------+ +| body | Raw response text `string`. | +| | Implicitly sets `Content-Type` header as | +| | ``text/html; charset=utf-8``. | ++--------------------------------+---------------------------------------------+ +| base64 | Base64 encoded `string`. | +| | Implicitly sets `Content-Type` header as | +| | ``application/binary``. | ++--------------------------------+---------------------------------------------+ +| headers | Response headers `object`. | +| | `Content-Type` header from this object | +| | overrides any implicitly assigned one. | ++--------------------------------+---------------------------------------------+ +| stop | `boolean` signal to stop iteration over | +| | view result rows (for list functions only) | ++--------------------------------+---------------------------------------------+ + +.. warning:: + ``body``, ``base64`` and ``json`` object keys are overlaps each other and + the last wins. Since most realizations of key-value objects doesn't preserve + key order mixing them may create confusing situation. Try to use only one of + them. + +.. note:: + Any custom property makes CouchDB raise internal exception. + Also `Response object` could be a simple string value which would be + implicitly wrapped into ``{"body": ...}`` object. + + +Returned CouchDB Document with Detailed Revision Info +===================================================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| _id (optional) | Document ID | ++--------------------------------+---------------------------------------------+ +| _rev (optional) | Revision ID (when updating an existing | +| | document) | ++--------------------------------+---------------------------------------------+ +| _revs_info [array] | CouchDB Document Extended Revision Info | ++--------------------------------+---------------------------------------------+ +| rev | Full revision string | ++--------------------------------+---------------------------------------------+ +| status | Status of the revision | ++--------------------------------+---------------------------------------------+ + +Returned CouchDB Document with Revision Info +============================================ + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| _id (optional) | Document ID | ++--------------------------------+---------------------------------------------+ +| _rev (optional) | Revision ID (when updating an existing | +| | document) | ++--------------------------------+---------------------------------------------+ +| _revisions | CouchDB Document Revisions | ++--------------------------------+---------------------------------------------+ +| ids [array] | Array of valid revision IDs, in reverse | +| | order (latest first) | ++--------------------------------+---------------------------------------------+ +| start | Prefix number for the latest revision | ++--------------------------------+---------------------------------------------+ + +Returned Document with Attachments +================================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| _id (optional) | Document ID | ++--------------------------------+---------------------------------------------+ +| _rev (optional) | Revision ID (when updating an existing | +| | document) | ++--------------------------------+---------------------------------------------+ +| _attachments (optional) | Document Attachment | ++--------------------------------+---------------------------------------------+ +| filename | Attachment | ++--------------------------------+---------------------------------------------+ +| stub | Indicates whether the attachment is a stub | ++--------------------------------+---------------------------------------------+ +| content_type | MIME Content type string | ++--------------------------------+---------------------------------------------+ +| length | Length (bytes) of the attachment data | ++--------------------------------+---------------------------------------------+ +| revpos | Revision where this attachment exists | ++--------------------------------+---------------------------------------------+ + +.. _security_object: + +Security Object +=============== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| admins | Roles/Users with admin privileges | ++--------------------------------+---------------------------------------------+ +| roles [array] | List of roles with parent privilege | ++--------------------------------+---------------------------------------------+ +| users [array] | List of users with parent privilege | ++--------------------------------+---------------------------------------------+ +| readers | Roles/Users with reader privileges | ++--------------------------------+---------------------------------------------+ +| roles [array] | List of roles with parent privilege | ++--------------------------------+---------------------------------------------+ +| users [array] | List of users with parent privilege | ++--------------------------------+---------------------------------------------+ + +.. code-block:: javascript + + { + "admins": { + "names": [ + "Bob" + ], + "roles": [] + }, + "members": { + "names": [ + "Mike", + "Alice" + ], + "roles": [] + } + } + + +.. _userctx_object: + +User Context Object +=================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| db | Database name in context of provided | +| | operation. | ++--------------------------------+---------------------------------------------+ +| name | User name. | ++--------------------------------+---------------------------------------------+ +| roles | List of user roles. | ++--------------------------------+---------------------------------------------+ + +.. code-block:: javascript + + { + "db": "mailbox", + "name": null, + "roles": [ + "_admin" + ] + } + + +.. _view_head_info_object: + +View Head Information +===================== + ++--------------------------------+---------------------------------------------+ +| Field | Description | ++================================+=============================================+ +| total_rows | Number of documents in the view | ++--------------------------------+---------------------------------------------+ +| offset | Offset where the document list started | ++--------------------------------+---------------------------------------------+ + +.. code-block:: javascript + + { + "total_rows": 42, + "offset": 3 + } diff --git a/share/doc/src/os-daemons.rst b/share/doc/src/os-daemons.rst new file mode 100644 index 000000000..5ff850c15 --- /dev/null +++ b/share/doc/src/os-daemons.rst @@ -0,0 +1,50 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +OS Daemons +========== + +CouchDB now supports starting external processes. The support is simple +and enables CouchDB to start each configured OS daemon. If the daemon +stops at any point, CouchDB will restart it (with protection to ensure +regularly failing daemons are not repeatedly restarted). + +The daemon starting process is one-to-one; for each each configured +daemon in the configuration file, CouchDB will start exactly one +instance. If you need to run multiple instances, then you must create +separate individual configurations. Daemons are configured within the +``[os_daemons]`` section of your configuration file (``local.ini``). The +format of each configured daemon is: + +.. code-block:: ini + + NAME = PATH ARGS + +Where ``NAME`` is an arbitrary (and unique) name to identify the daemon; +``PATH`` is the full path to the daemon to be executed; ``ARGS`` are any +required arguments to the daemon. + +For example: + +.. code-block:: ini + + [os_daemons] + basic_responder = /usr/local/bin/responder.js + +There is no interactivity between CouchDB and the running process, but +you can use the OS Daemons service to create new HTTP servers and +responders and then use the new proxy service to redirect requests and +output to the CouchDB managed service. For more information on proxying, +see :ref:`http-proxying`. For further background on the OS Daemon service, see +`CouchDB Externals API`_. + +.. _CouchDB Externals API: http://davispj.com/2010/09/26/new-couchdb-externals-api.html diff --git a/share/doc/src/pretty_urls.rst b/share/doc/src/pretty_urls.rst new file mode 100644 index 000000000..9f2bdc2f3 --- /dev/null +++ b/share/doc/src/pretty_urls.rst @@ -0,0 +1,136 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _pretty_urls: + +=========== +Pretty URLs +=========== + +CouchDB incorporates a straightforwards URL routing and rewriting engine. +While it is not as comprehensive as a front-end proxy, it caters for most +needs out of the box, including using virtual hostnames to map URLs to +specific databases, and provides more complex use cases through a rewriting +engine. + +This `post +<http://blog.couchbase.com/what%E2%80%99s-new-apache-couchdb-011-%E2%80%94-part-one-nice-urls-rewrite-rules-and-virtual-hosts>`_ has a detailed example of a combined vhost and rewriter configuration. + +Virtual Hosts +============= + +CouchDB, since 0.11.0, can map requests to different locations based on +the ``Host`` header, even if they arrive on the some inbound IP address. + +This allows different virtual hosts on the same machine to map to different +databases or design documents, etc. The most common use case is to map a +virtual host to a Rewrite Handler, to provide full control over the +application's URIs. + +To add a virtual host, add a CNAME pointer to the DNS for your domain +name. For development and testing, it is sufficient to add an entry in +the hosts file, typically `/etc/hosts`` on Unix-like operating systems: + +.. code-block:: bash + + # CouchDB vhost definitions, refer to local.ini for further details + 127.0.0.1 sofa.couchdb + +Test that this is working: + +.. code-block:: bash + + $ ping sofa.couchdb + PING sofa.couchdb (127.0.0.1) 56(84) bytes of data. + 64 bytes from localhost.localdomain (127.0.0.1): icmp_req=1 ttl=64 time=0.025 ms + 64 bytes from localhost.localdomain (127.0.0.1): icmp_req=2 ttl=64 time=0.051 ms + ^C + +Finally, add an entry to your :ref:`configuration file <configuring>` in the ``[vhosts]`` +section: + +.. code-block:: ini + + [vhosts] + sofa.couchdb:5984 = /sofa/_design/sofa/_rewrite + +If your CouchDB is listening on the default HTTP port, or is sitting +behind a proxy, then don't specify a port number in the vhost key. + +With the above setup, a request to ``http://sofa.couchdb:5984/sweet-o`` +will be mapped to +``http://127.0.0.1:5984/sofa/_design/sofa/_rewrite/sweet-o`` + +.. versionadded:: 0.11.0 added `vhosts` functionality + +HTTP Rewrite Handler +==================== + +Following on from `virtual hosts`_, CouchDB includes a custom URL rewriter. +All rewriting is done from ``/dbname/_design/ddocname/_rewrite`` by default. + +The rewriter is flexible, and can handle methods and custom query formats. + +Each rule should be in the ``rewrites`` top-level key of the design doc. +Example of a complete rule : + +.. code-block:: json + + { + .... + "rewrites": [ + { + "from": "", + "to": "index.html", + "method": "GET", + "query": {} + } + ] + } + + +**from**: is the path rule used to bind current uri to the rule. It +uses pattern matching for that. + +**to**: rule to rewrite an url. It can contain variables depending on +binding variables discovered during pattern matching and query args +(url args and from the query member.) + +**method**: method to bind the request method to the rule. If method +is missing, any method will be matched in the rewrite. + +**query**: optional query arguments, that may contain dynamic variables, +by binding keys in the to be used with the matching URL. + +``to`` and ``from`` are paths with patterns. The pattern can be strings starting +with ``:`` or ``*``, for example ``/somepath/:var/*``. + +The pattern matching is done by first matching the request method to a +rule. Then it will try to match the path to one specific rule. If no rule +match, then a 404 error is displayed. + +The path is converted into an erlang list, by regex splitting on ``/``. Each +variable is converted into an atom. The subsequent pattern matching step is +done by splitting ``/`` in the request url into a list of atoms. A string +pattern will match the equivalent token. The ``*`` atom will match any number +of tokens, but may only be present as the last pattern in the path. If all +tokens are matched, and all path terms have been consumed, then the overall +path specification matches. + +Once a matching ``from`` rule is found we rewrite the request url using the +``from``, ``to``, and ``query`` members. Each identified token will be reused +within the rule, and in the subsequent query if required. The identified +tokens are matched to the rule and will replace var. If ``*`` is found in +the rule it will contain any remaining suffix. + +The rewriter is re-entrant, and has a configurable recursion limit, set +by default at 100. diff --git a/share/doc/src/query-servers.rst b/share/doc/src/query-servers.rst new file mode 100644 index 000000000..e77abd7b6 --- /dev/null +++ b/share/doc/src/query-servers.rst @@ -0,0 +1,481 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. default-domain:: js + +============= +Query servers +============= + +.. _queryserver_js: + +JavaScript +========== + +.. note:: While every design function has access to all JavaScript objects, + the table below describes appropriate usage cases. For example, + you may use :func:`emit` in :ref:`listfun`, but :func:`getRow` is not permitted during :ref:`mapfun`. + ++--------------------------------+---------------------------------------------+ +| JS Function | Reasonable to use in design doc functions | ++================================+=============================================+ +| :func:`emit` | :ref:`mapfun` | ++--------------------------------+---------------------------------------------+ +| :func:`getRow` | :ref:`listfun` | ++--------------------------------+---------------------------------------------+ +| :data:`JSON` | any | ++--------------------------------+---------------------------------------------+ +| :func:`isArray` | any | ++--------------------------------+---------------------------------------------+ +| :func:`log` | any | ++--------------------------------+---------------------------------------------+ +| :func:`provides` | :ref:`showfun`, :ref:`listfun` | ++--------------------------------+---------------------------------------------+ +| :func:`registerType` | :ref:`showfun`, :ref:`listfun` | ++--------------------------------+---------------------------------------------+ +| :func:`require` | every except :ref:`reducefun` | ++--------------------------------+---------------------------------------------+ +| :func:`send` | :ref:`listfun` | ++--------------------------------+---------------------------------------------+ +| :func:`start` | :ref:`listfun` | ++--------------------------------+---------------------------------------------+ +| :func:`sum` | any | ++--------------------------------+---------------------------------------------+ +| :func:`toJSON` | any | ++--------------------------------+---------------------------------------------+ + +Design functions context +------------------------ + +Each design function executes within special context of predefined objects, +modules and functions: + + +.. function:: emit(key, value) + + Puts `key`-`value` pair into inner stack for further passing to CouchDB + when map function is done. + + :param key: View's key. + :param value: Associated value with `key`. + + .. code-block:: javascript + + function(doc){ + emit(doc._id, doc._rev); + } + + +.. function:: getRow() + + Extracts next row from the related view result. + + :return: View result row + :rtype: object + + .. code-block:: javascript + + function(head, req){ + send('['); + row = getRow(); + if (row){ + send(toJSON(row)); + while(row = getRow()){ + send(','); + send(toJSON(row)); + } + } + return ']'; + } + + +.. data:: JSON + + `JSON2 <https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=share/server/json2.js>`_ + object. + + +.. function:: isArray(obj) + + Helper to check is provided value `array` or not + + :param obj: Any Javascript value + :return: ``true`` is `obj` is `array` typed, ``false`` otherwise. + :rtype: boolean + + +.. function:: log(message) + + :param message: Message to log in at CouchDB `INFO` level. + + .. code-block:: javascript + + function(doc){ + log('Procesing doc ' + doc['_id']); + emit(doc['_id'], null); + } + + On map function run in CouchDB logs (e.g. at `/var/log/couchdb/couch.log`) + you may find next record: + + .. code-block:: text + + [Sat, 03 Nov 2012 17:38:02 GMT] [info] [<0.7543.0>] OS Process #Port<0.3289> Log :: Processing doc 8d300b86622d67953d102165dbe99467 + + +.. function:: provides(key, func) + + Registers callable handler for specified MIME key. + + :param key: MIME key previously defined by :func:`registerType` + :param func: MIME type handler. + + +.. function:: registerType(key, *mimes) + + Registers list of MIME types by associated `key`. + + :param key: MIME types + :param mimes: MIME types enumeration. + + Predefined mappings (`key`-`array`): + + - **all**: ``*/*`` + - **text**: ``text/plain; charset=utf-8``, ``txt`` + - **html**: ``text/html; charset=utf-8`` + - **xhtml**: ``application/xhtml+xml``, ``xhtml`` + - **xml**: ``application/xml``, ``text/xml``, ``application/x-xml`` + - **js**: ``text/javascript``, ``application/javascript``, + ``application/x-javascript`` + - **css**: ``text/css`` + - **ics**: ``text/calendar`` + - **csv**: ``text/csv`` + - **rss**: ``application/rss+xml`` + - **atom**: ``application/atom+xml`` + - **yaml**: ``application/x-yaml``, ``text/yaml`` + - **multipart_form**: ``multipart/form-data`` + - **url_encoded_form**: ``application/x-www-form-urlencoded`` + - **json**: ``application/json``, ``text/x-json`` + + +.. function:: require(path) + + Loads CommonJS module by specified `path`. Path shouldn't starts with slash. + + :param path: CommonJS module path started from design document root. + :return: Exported statements. + + +.. function:: send(chunk) + + Sends a single string `chunk` in response. + + :param chunk: Text chunk + + .. code-block:: javascript + + function(head, req){ + send('Hello,'); + send(' '); + send('Couch'); + return ! + } + + +.. function:: start(init_resp) + + Initiates chunked response. As an option, custom + :ref:`response <response_object>` object may be sent at this point. + For `list`-functions only! + + .. note:: + + Only at this point list functions may set response `HTTP code` and + `headers`. Also, you need to run this function before :func:`send`, + :func:`getRow` or `return` statement or query server will implicitly call + this function with empty object (``{}``). + + .. code-block:: javascript + + function(head, req){ + start({ + "code": 302, + "headers": { + "Location": "http://couchdb.apache.org" + } + }); + return "Relax!"; + } + + +.. function:: sum(arr) + + Summarize `arr` items. + + :param arr: Array of numbers. + :rtype: number + + +.. function:: toJSON(obj) + + Encodes `obj` to JSON string. Actually is a proxy to ``JSON.stringify`` + method. + + :param obj: JSON encodable object. + :return: JSON string. + + + +CommonJS Modules +---------------- + +`CommonJS Modules <http://wiki.commonjs.org/wiki/Modules/1.1.1>`_ is the one of +major CouchDB feature introduced in 0.11.0 version that allows to create modular +design functions without needs to duplicate a lot of same functionality. + +Example of CommonJS module that checks user permissions: + +.. code-block:: javascript + + function user_context(userctx, secobj){ + var is_admin = function(){ + return userctx.indexOf('_admin') != -1; + } + var is_db_admin = function(){ + if (is_admin() || !secobj){ + return true; + } + if (secobj.admins.names.indexOf(userctx.name) != -1){ + return true; + } + for (var idx in userctx.roles){ + if (secobj.admins.roles.indexOf(userctx.roles[idx]) != -1){ + return true; + } + } + return false; + } + var is_db_member = function(){ + if (is_admin() || is_db_admin() || !secobj){ + return true; + } + if (secobj.members.names.indexOf(userctx.name) != -1){ + return true; + } + for (var idx in userctx.roles){ + if (secobj.members.roles.indexOf(userctx.roles[idx]) != -1){ + return true; + } + } + return false; + } + var has_all_roles = function(roles){ + for (var idx in roles){ + if (userctx.roles.indexOf(roles[idx]) == -1){ + return false; + } + } + return true; + } + var has_any_role = function(roles){ + for (var idx in roles){ + if (userctx.roles.indexOf(roles[idx]) != -1){ + return true; + } + } + return false; + } + return { + 'is_admin': is_admin, + 'is_db_admin': is_db_admin, + 'is_db_member': is_db_member, + 'has_all_roles': has_all_roles, + 'has_any_role': has_any_role + } + } + + exports['user'] = user_context + +Each module has access to additional global variables: + +- **module** (`object`): Contains information about stored module. + + - **id** (`string`): Module id that is actually JSON path in ddoc context. + - **current** (`code`): Compiled module code object. + - **parent** (`object`): Parent frame. + - **exports** (`object`): Export statements. + +- **exports** (`object`): Shortcut to ``module.exports`` object. + +Lets place module above within design document under `lib/validate` path. +Now we could use it in our design functions: + +.. code-block:: javascript + + function(newdoc, olddoc, userctx, secobj){ + user = require('lib/validate').user(userctx, secobj); + if (user.is_admin()){ + return true; + } + if (newdoc.author != olddoc.author){ + throw({'forbidden': 'unable to update `author` field'}); + } + } + + +.. _queryserver_erlang: + +Erlang +====== + +.. warning:: + + Erlang query server runs out of sandbox feature like JavaScript has to! + This means, that Erlang code has full access to your OS, file system and + network which may leads to security issues. While Erlang functions are + faster than JavaScript ones, you need to be careful with running them, + especially if they wasn't written by your own hands. + + Keep in mind: don't trust every code - review it first before running. + + +.. note:: + + Due to security restriction, Erlang query server is disabled by default. + To enable it you'll need to edit your `local.ini` to include a + ``native_query_servers`` section: + + .. code-block:: ini + + [native_query_servers] + erlang = {couch_native_process, start_link, []} + + And don't forget to restart CouchDB after that and use ``language: "erlang"`` + property in your Erlang design documents. + + +.. function:: Emit(Id, Value) + + Emits `key`-`value` pair to view indexer process. + + .. code-block:: erlang + + fun({Doc}) -> + <<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null), + V = proplists:get_value(<<"_id">>, Doc, null), + Emit(<<K>>, V) + end. + + +.. function:: FoldRows(Fun, Acc) + + Helper to iterate over all rows in list function. + + :param Fun: Function object. + :param Acc: Previous returned value by `Fun`. + + .. code-block:: erlang + + fun(Head, {Req}) -> + Fun = fun({Row}, Acc) -> + Id = couch_util:get_value(<<"id">>, Row), + Send(list_to_binary(io_lib:format("Previous doc id: ~p~n", [Acc]))), + Send(list_to_binary(io_lib:format("Current doc id: ~p~n", [Id]))), + {ok, Id} + end, + FoldRows(Fun, nil), + "" + end. + + +.. function:: GetRow() + + Retrieves next row from related view result. + + .. code-block:: erlang + + %% FoldRows background implementation. + %% https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=src/couchdb/couch_native_process.erl;hb=HEAD#l368 + %% + foldrows(GetRow, ProcRow, Acc) -> + case GetRow() of + nil -> + {ok, Acc}; + Row -> + case (catch ProcRow(Row, Acc)) of + {ok, Acc2} -> + foldrows(GetRow, ProcRow, Acc2); + {stop, Acc2} -> + {ok, Acc2} + end + end. + +.. function:: Log(Msg) + + :param Msg: Message to log in at CouchDB `INFO` level. + + .. code-block:: erlang + + fun({Doc}) -> + <<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null), + V = proplists:get_value(<<"_id">>, Doc, null), + Log(lists:flatten(io_lib:format("Hello from ~s doc!", [V]))), + Emit(<<K>>, V) + end. + + On map function run in CouchDB logs (e.g. at `/var/log/couchdb/couch.log`) + you may find next record: + + .. code-block:: text + + [Sun, 04 Nov 2012 11:33:58 GMT] [info] [<0.9144.2>] Hello from 8d300b86622d67953d102165dbe99467 doc! + + +.. function:: Send(Chunk) + + Sends a single string `Chunk` in response. + + .. code-block:: erlang + + fun(Head, {Req}) -> + Send("Hello,"), + Send(" "), + Send("Couch"), + "!" + end. + + Function above produces next response: + + .. code-block:: text + + Hello, Couch! + + +.. function:: Start(Headers) + + :param Headers: Proplist of :ref:`response object<response_object>`. + + Initialize :ref:`listfun` response. At this point response code and headers + may be defined. For example, next function redirect to CouchDB web site: + + .. code-block:: erlang + + fun(Head, {Req}) -> + Start({[{<<"code">>, 302}, + {<<"headers">>, {[ + {<<"Location">>, <<"http://couchdb.apache.org">>}] + }} + ]}), + "Relax!" + end. + + diff --git a/share/doc/src/range.rst b/share/doc/src/range.rst new file mode 100644 index 000000000..a2f6ed11b --- /dev/null +++ b/share/doc/src/range.rst @@ -0,0 +1,72 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +HTTP Range Requests +=================== + +HTTP allows you to specify byte ranges for requests. This allows the +implementation of resumable downloads and skippable audio and video +streams alike. This is available for all attachments inside CouchDB. + +This is just a real quick run through how this looks under the hood. +Usually, you will have larger binary files to serve from CouchDB, like +MP3s and videos, but to make things a little more obvious, I use a text +file here (Note that I use the ``application/octet-stream`` Content-Type +instead of ``text/plain``). + +.. code-block:: bash + + shell> cat file.txt + My hovercraft is full of eels! + +Now let's store this text file as an attachment in CouchDB. First, we +create a database: + +.. code-block:: bash + + shell> curl -X PUT http://127.0.0.1:5984/test + {"ok":true} + +Then we create a new document and the file attachment in one go: + +.. code-block:: bash + + shell> curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \ + -H "Content-Type: application/octet-stream" -d@file.txt + {"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"} + +Now we can request the whole file easily: + +.. code-block:: bash + + shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt + My hovercraft is full of eels! + +But say we only want the first 13 bytes: + +.. code-block:: bash + + shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt \ + -H "Range: bytes=0-12" + My hovercraft + +HTTP supports many ways to specify single and even multiple byte +ranges. Read all about it in `RFC 2616`_. + +.. note:: + Databases that have been created with CouchDB 1.0.2 or earlier will + support range requests in |version|, but they are using a less-optimal + algorithm. If you plan to make heavy use of this feature, make sure + to compact your database with CouchDB |version| to take advantage of a + better algorithm to find byte ranges. + +.. _RFC 2616: http://tools.ietf.org/html/rfc2616#section-14.27 diff --git a/share/doc/src/release.rst b/share/doc/src/release.rst new file mode 100644 index 000000000..c61d8ad6a --- /dev/null +++ b/share/doc/src/release.rst @@ -0,0 +1,47 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +======================================= +CouchDB Release |version| Feature Guide +======================================= + +Upgrading to CouchDB |version| +============================== + +You can upgrade your existing CouchDB 1.0.x installation to CouchDB |version| +without any specific steps or migration. When you run CouchDB |version| the +existing data and index files will be opened and used as normal. + +The first time you run a compaction routine on your database within +CouchDB |version|, the data structure and indexes will be updated to the new +version of the CouchDB database format that can only be read by CouchDB +|version| and later. This step is not reversible. Once the data files have +been updated and migrated to the new version the data files will no +longer work with a CouchDB 1.0.x release. + +.. warning:: + If you want to retain support for opening the data files in + CouchDB 1.0.x you must back up your data files before performing the + upgrade and compaction process. + +New features in CouchDB |version| +================================= + +.. toctree:: +.. :maxdepth: 2 +.. +.. replicator +.. ssl +.. range +.. proxy +.. commonjs +.. other diff --git a/share/doc/src/replication.rst b/share/doc/src/replication.rst new file mode 100644 index 000000000..9245a0874 --- /dev/null +++ b/share/doc/src/replication.rst @@ -0,0 +1,383 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _replication: + +Replicator Database +=================== + +A database where you ``PUT``/``POST`` documents to trigger replications +and you ``DELETE`` to cancel ongoing replications. These documents have +exactly the same content as the JSON objects we used to ``POST`` to +``_replicate`` (fields ``source``, ``target``, ``create_target``, +``continuous``, ``doc_ids``, ``filter``, ``query_params``. + +Replication documents can have a user defined ``_id``. Design documents +(and ``_local`` documents) added to the replicator database are ignored. + +The default name of this database is ``_replicator``. The name can be +changed in the ``local.ini`` configuration, section ``[replicator]``, +parameter ``db``. + +Basics +------ + +Let's say you PUT the following document into ``_replicator``: + +.. code-block:: javascript + + { + "_id": "my_rep", + "source": "http://myserver.com:5984/foo", + "target": "bar", + "create_target": true + } + +In the couch log you'll see 2 entries like these: + +.. code-block:: text + + [Thu, 17 Feb 2011 19:43:59 GMT] [info] [<0.291.0>] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target` + [Thu, 17 Feb 2011 19:44:37 GMT] [info] [<0.124.0>] Replication `c0ebe9256695ff083347cbf95f93e280+create_target` finished (triggered by document `my_rep`) + +As soon as the replication is triggered, the document will be updated by +CouchDB with 3 new fields: + +.. code-block:: javascript + + { + "_id": "my_rep", + "source": "http://myserver.com:5984/foo", + "target": "bar", + "create_target": true, + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "triggered", + "_replication_state_time": 1297974122 + } + +Special fields set by the replicator start with the prefix +``_replication_``. + +- ``_replication_id`` + + The ID internally assigned to the replication. This is also the ID + exposed by ``/_active_tasks``. + +- ``_replication_state`` + + The current state of the replication. + +- ``_replication_state_time`` + + A Unix timestamp (number of seconds since 1 Jan 1970) that tells us + when the current replication state (marked in ``_replication_state``) + was set. + +When the replication finishes, it will update the ``_replication_state`` +field (and ``_replication_state_time``) with the value ``completed``, so +the document will look like: + +.. code-block:: javascript + + { + "_id": "my_rep", + "source": "http://myserver.com:5984/foo", + "target": "bar", + "create_target": true, + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "completed", + "_replication_state_time": 1297974122 + } + +When an error happens during replication, the ``_replication_state`` +field is set to ``error`` (and ``_replication_state`` gets updated of +course). + +When you PUT/POST a document to the ``_replicator`` database, CouchDB +will attempt to start the replication up to 10 times (configurable under +``[replicator]``, parameter ``max_replication_retry_count``). If it +fails on the first attempt, it waits 5 seconds before doing a second +attempt. If the second attempt fails, it waits 10 seconds before doing a +third attempt. If the third attempt fails, it waits 20 seconds before +doing a fourth attempt (each attempt doubles the previous wait period). +When an attempt fails, the Couch log will show you something like: + +.. code-block:: text + + [error] [<0.149.0>] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,<<"could not open http://myserver:5986/foo/">> + +.. note:: + The ``_replication_state`` field is only set to ``error`` when all + the attempts were unsuccessful. + +There are only 3 possible values for the ``_replication_state`` field: +``triggered``, ``completed`` and ``error``. Continuous replications +never get their state set to ``completed``. + +Documents describing the same replication +----------------------------------------- + +Lets suppose 2 documents are added to the ``_replicator`` database in +the following order: + +.. code-block:: javascript + + { + "_id": "doc_A", + "source": "http://myserver.com:5984/foo", + "target": "bar" + } + +and + +.. code-block:: javascript + + { + "_id": "doc_B", + "source": "http://myserver.com:5984/foo", + "target": "bar" + } + +Both describe exactly the same replication (only their ``_ids`` differ). +In this case document ``doc_A`` triggers the replication, getting +updated by CouchDB with the fields ``_replication_state``, +``_replication_state_time`` and ``_replication_id``, just like it was +described before. Document ``doc_B`` however, is only updated with one +field, the ``_replication_id`` so it will look like this: + +.. code-block:: javascript + + { + "_id": "doc_B", + "source": "http://myserver.com:5984/foo", + "target": "bar", + "_replication_id": "c0ebe9256695ff083347cbf95f93e280" + } + +While document ``doc_A`` will look like this: + +.. code-block:: javascript + + { + "_id": "doc_A", + "source": "http://myserver.com:5984/foo", + "target": "bar", + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "triggered", + "_replication_state_time": 1297974122 + } + +Note that both document get exactly the same value for the +``_replication_id`` field. This way you can identify which documents +refer to the same replication - you can for example define a view which +maps replication IDs to document IDs. + +Canceling replications +---------------------- + +To cancel a replication simply ``DELETE`` the document which triggered +the replication. The Couch log will show you an entry like the +following: + +.. code-block:: text + + [Thu, 17 Feb 2011 20:16:29 GMT] [info] [<0.125.0>] Stopped replication `c0ebe9256695ff083347cbf95f93e280+continuous+create_target` because replication document `doc_A` was deleted + +.. note:: + You need to ``DELETE`` the document that triggered the replication. + ``DELETE``-ing another document that describes the same replication + but did not trigger it, will not cancel the replication. + +Server restart +-------------- + +When CouchDB is restarted, it checks its ``_replicator`` database and +restarts any replication that is described by a document that either has +its ``_replication_state`` field set to ``triggered`` or it doesn't have +yet the ``_replication_state`` field set. + +.. note:: + Continuous replications always have a ``_replication_state`` field + with the value ``triggered``, therefore they're always restarted + when CouchDB is restarted. + +Changing the Replicator Database +-------------------------------- + +Imagine your replicator database (default name is ``_replicator``) has the +two following documents that represent pull replications from servers A +and B: + +.. code-block:: javascript + + { + "_id": "rep_from_A", + "source": "http://aserver.com:5984/foo", + "target": "foo_a", + "continuous": true, + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "triggered", + "_replication_state_time": 1297971311 + } + +.. code-block:: javascript + + { + "_id": "rep_from_B", + "source": "http://bserver.com:5984/foo", + "target": "foo_b", + "continuous": true, + "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1", + "_replication_state": "triggered", + "_replication_state_time": 1297974122 + } + +Now without stopping and restarting CouchDB, you change the name of the +replicator database to ``another_replicator_db``: + +.. code-block:: bash + + $ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"' + "_replicator" + +As soon as this is done, both pull replications defined before, are +stopped. This is explicitly mentioned in CouchDB's log: + +.. code-block:: text + + [Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.104.0>] Stopping all ongoing replications because the replicator database was deleted or changed + [Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.127.0>] 127.0.0.1 - - PUT /_config/replicator/db 200 + +Imagine now you add a replication document to the new replicator +database named ``another_replicator_db``: + +.. code-block:: javascript + + { + "_id": "rep_from_X", + "source": "http://xserver.com:5984/foo", + "target": "foo_x", + "continuous": true + } + +From now own you have a single replication going on in your system: a +pull replication pulling from server X. Now you change back the +replicator database to the original one ``_replicator``: + +:: + + $ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"' + "another_replicator_db" + +Immediately after this operation, the replication pulling from server X +will be stopped and the replications defined in the ``_replicator`` +database (pulling from servers A and B) will be resumed. + +Changing again the replicator database to ``another_replicator_db`` will +stop the pull replications pulling from servers A and B, and resume the +pull replication pulling from server X. + +Replicating the replicator database +----------------------------------- + +Imagine you have in server C a replicator database with the two +following pull replication documents in it: + +.. code-block:: javascript + + { + "_id": "rep_from_A", + "source": "http://aserver.com:5984/foo", + "target": "foo_a", + "continuous": true, + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "triggered", + "_replication_state_time": 1297971311 + } + +.. code-block:: javascript + + { + "_id": "rep_from_B", + "source": "http://bserver.com:5984/foo", + "target": "foo_b", + "continuous": true, + "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1", + "_replication_state": "triggered", + "_replication_state_time": 1297974122 + } + +Now you would like to have the same pull replications going on in server +D, that is, you would like to have server D pull replicating from +servers A and B. You have two options: + +- Explicitly add two documents to server's D replicator database + +- Replicate server's C replicator database into server's D replicator + database + +Both alternatives accomplish exactly the same goal. + +Delegations +----------- + +Replication documents can have a custom ``user_ctx`` property. This +property defines the user context under which a replication runs. For +the old way of triggering replications (POSTing to ``/_replicate/``), +this property was not needed (it didn't exist in fact) - this is because +at the moment of triggering the replication it has information about the +authenticated user. With the replicator database, since it's a regular +database, the information about the authenticated user is only present +at the moment the replication document is written to the database - the +replicator database implementation is like a ``_changes`` feed consumer +(with ``?include_docs=true``) that reacts to what was written to the +replicator database - in fact this feature could be implemented with an +external script/program. This implementation detail implies that for non +admin users, a ``user_ctx`` property, containing the user's name and a +subset of his/her roles, must be defined in the replication document. +This is ensured by the document update validation function present in +the default design document of the replicator database. This validation +function also ensure that a non admin user can set a user name property +in the ``user_ctx`` property that doesn't match his/her own name (same +principle applies for the roles). + +For admins, the ``user_ctx`` property is optional, and if it's missing +it defaults to a user context with name null and an empty list of roles +- this mean design documents will not be written to local targets. If +writing design documents to local targets is desired, the a user context +with the roles ``_admin`` must be set explicitly. + +Also, for admins the ``user_ctx`` property can be used to trigger a +replication on behalf of another user. This is the user context that +will be passed to local target database document validation functions. + +.. note:: + The ``user_ctx`` property only has effect for local endpoints. + +Example delegated replication document: + +.. code-block:: javascript + + { + "_id": "my_rep", + "source": "http://bserver.com:5984/foo", + "target": "bar", + "continuous": true, + "user_ctx": { + "name": "joe", + "roles": ["erlanger", "researcher"] + } + } + +As stated before, for admins the ``user_ctx`` property is optional, while +for regular (non admin) users it's mandatory. When the roles property of +``user_ctx`` is missing, it defaults to the empty list ``[ ]``. diff --git a/share/doc/src/ssl.rst b/share/doc/src/ssl.rst new file mode 100644 index 000000000..3a546d877 --- /dev/null +++ b/share/doc/src/ssl.rst @@ -0,0 +1,109 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +Native SSL Support +================== + +CouchDB |version| supports SSL natively. All your secure connection needs can +now be served without needing to setup and maintain a separate proxy server +that handles SSL. + +SSL setup can be tricky, but the configuration in CouchDB was designed +to be as easy as possible. All you need is two files; a certificate and +a private key. If you bought an official SSL certificate from a +certificate authority, both should be in your possession already. + +If you just want to try this out and don't want to pay anything upfront, +you can create a self-signed certificate. Everything will work the same, +but clients will get a warning about an insecure certificate. + +You will need the OpenSSL command line tool installed. It probably +already is. + +:: + + shell> mkdir cert && cd cert + shell> openssl genrsa > privkey.pem + shell> openssl req -new -x509 -key privkey.pem -out mycert.pem -days 1095 + shell> ls + mycert.pem privkey.pem + +Now, you need to edit CouchDB's configuration, either by editing your +``local.ini`` file or using the ``/_config`` API calls or the +configuration screen in Futon. Here is what you need to do in +``local.ini``, you can infer what needs doing in the other places. + +Be sure to make these edits. Under ``[daemons]`` you should see: + +:: + + ; enable SSL support by uncommenting the following line and supply the PEM's below. + ; the default ssl port CouchDB listens on is 6984 + ;httpsd = {couch_httpd, start_link, [https]} + +Here uncomment the last line: + +:: + + httpsd = {couch_httpd, start_link, [https]} + +Next, under ``[ssl]`` you will see: + +:: + + ;cert_file = /full/path/to/server_cert.pem + ;key_file = /full/path/to/server_key.pem + +Uncomment and adjust the paths so it matches your system's paths: + +:: + + cert_file = /home/jan/cert/mycert.pem + key_file = /home/jan/cert/privkey.pem + +For more information please read +`http://www.openssl.org/docs/HOWTO/certificates.txt`_. + +Now start (or restart) CouchDB. You should be able to connect to it +using HTTPS on port 6984: + +:: + + shell> curl https://127.0.0.1:6984/ + curl: (60) SSL certificate problem, verify that the CA cert is OK. Details: + error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed + More details here: http://curl.haxx.se/docs/sslcerts.html + + curl performs SSL certificate verification by default, using a "bundle" + of Certificate Authority (CA) public keys (CA certs). If the default + bundle file isn't adequate, you can specify an alternate file + using the --cacert option. + If this HTTPS server uses a certificate signed by a CA represented in + the bundle, the certificate verification probably failed due to a + problem with the certificate (it might be expired, or the name might + not match the domain name in the URL). + If you'd like to turn off curl's verification of the certificate, use + the -k (or --insecure) option. + +Oh no what happened?! — Remember, clients will notify their users that +your certificate is self signed. ``curl`` is the client in this case and +it notifies you. Luckily you trust yourself (don't you?) and you can +specify the ``-k`` option as the message reads: + +:: + + shell> curl -k https://127.0.0.1:6984/ + {"couchdb":"Welcome","version":"|version|"} + +All done. + +.. _`http://www.openssl.org/docs/HOWTO/certificates.txt`: http://www.openssl.org/docs/HOWTO/certificates.txt diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-auth-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-auth-metasrc.xml deleted file mode 100644 index 417500a7a..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-api-auth-metasrc.xml +++ /dev/null @@ -1,36 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-auth"> - - <title>CouchDB API Server Authentication Methods</title> - - <para> - The CouchDB Authentication methods provide an interface for - obtaining session and authorization data. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <para role="meta" id="table-couchdb-api-auth-summary"> - <remark role="title">Authentication API Calls</remark> - - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="summarytable"/> - - <remark role="filter_class" condition="auth"/> - - <remark role="version" condition="inherit"/> - - <remark role="idprefix" condition="couchdb-api-auth"/> - </para> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-config-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-config-metasrc.xml deleted file mode 100644 index aa1ac2777..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-api-config-metasrc.xml +++ /dev/null @@ -1,359 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-config"> - - <title>CouchDB API Server Configuration Methods</title> - - <para> - The CouchDB API Server Configuration Methods provide an interface to - query and update the various configuration values within a running - CouchDB instance. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <para role="meta" id="table-couchdb-api-config-summary"> - <remark role="title">Configuration API Calls</remark> - - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="summarytable"/> - - <remark role="filter_class" condition="config"/> - - <remark role="version" condition="inherit"/> - - <remark role="idprefix" condition="couchdb-api-config"/> - </para> - - <section id="couchdb-api-config_config_get"> - - <title><literal>GET /_config</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="config"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Returns the entire CouchDB server configuration as a JSON - structure. The structure is organized by different configuration - sections, with individual values. - </para> - - <para> - For example, to get the configuration for a server: - </para> - -<programlisting> -GET http://couchdb:5984/_config -Accept: application/json -</programlisting> - - <para> - The response is the JSON structure: - </para> - -<programlisting> -<![CDATA[{ - "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}" - } -}]]> - </programlisting> - - </section> - - <section id="couchdb-api-config_config-section_get"> - - <title><literal>GET /_config/section</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="config-section"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Gets the configuration structure for a single section. For - example, to retrieve the CouchDB configuration section values: - </para> - -<programlisting> -GET http://couchdb:5984/_config/couchdb -Accept: application/json -</programlisting> - - <para> - The returned JSON contains just the configuration values for this - section: - </para> - -<programlisting> -{ - "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" -} -</programlisting> - - </section> - - <section id="couchdb-api-config_config-section-key_get"> - - <title><literal>GET /_config/section/key</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="config-section-key"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Gets a single configuration value from within a specific - configuration section. For example, to obtain the current log - level: - </para> - -<programlisting> -GET http://couchdb:5984/_config/log/level -Accept: application/json -</programlisting> - - <para> - Returns the string of the log level: - </para> - -<programlisting> -"info" -</programlisting> - - <note> - <para> - 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. - </para> - </note> - - </section> - - <section id="couchdb-api-config_config-section-key_put"> - - <title><literal>PUT /_config/section/key</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="config-section-key"/> - - <remark role="method" condition="PUT"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - 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. - </para> - - <para> - For example, to set the function used to generate UUIDs by the - <literal>GET /_uuids</literal> API call to use the - <literal>utc_random</literal> generator: - </para> - -<programlisting> -PUT http://couchdb:5984/_config/uuids/algorithm -Content-Type: application/json - -"utc_random" -</programlisting> - - <para> - The return value will be empty, with the response code indicating - the success or failure of the configuration setting. - </para> - - </section> - - <section id="couchdb-api-config_config-section-key_delete"> - - <title><literal>DELETE /_config/section/key</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="config-section-key"/> - - <remark role="method" condition="DELETE"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - 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: - </para> - -<programlisting> -DELETE http://couchdb:5984/_config/uuids/algorithm -Content-Type: application/json -</programlisting> - - <para> - The returned value is the last configured UUID function: - </para> - -<programlisting> -"random" -</programlisting> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-db-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-db-metasrc.xml deleted file mode 100644 index 0b3084aa7..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-api-db-metasrc.xml +++ /dev/null @@ -1,1828 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-db"> - - <title>CouchDB API Server Database Methods</title> - - <para> - The Database methods provide an interface to an entire database - withing CouchDB. These are database, rather than document, level - requests. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <para role="meta" id="table-couchdb-api-db-summary"> - <remark role="title">Database API Calls</remark> - - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="summarytable"/> - - <remark role="filter_class" condition="db"/> - - <remark role="version" condition="inherit"/> - - <remark role="idprefix" condition="couchdb-api-db"/> - </para> - - <para> - 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 - <literal>recipes</literal>, you would use the HTTP request: - </para> - -<programlisting> -GET /recipes -</programlisting> - - <para> - For clarity, the form below is used in the URL paths: - </para> - -<programlisting> -GET /db -</programlisting> - - <para> - Where <literal>db</literal> is the name of any database. - </para> - - <section id="couchdb-api-db_db_get"> - - <title><literal>GET /db</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Gets information about the specified database. For example, to - retrieve the information for the database - <literal>recipe</literal>: - </para> - -<programlisting role="httprequest"> -GET http://couchdb:5984/recipes -Accept: application/json -</programlisting> - - <para> - The JSON response contains meta information about the database. A - sample of the JSON returned for an empty database is provided - below: - </para> - -<programlisting role="httpresponse"> -{ - "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 -} - </programlisting> - - <para> - The elements of the returned structure are shown in the table - below: - </para> - - <para role="meta" id="table-couchdb-api-db-json-db-info"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="db-info"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section id="couchdb-api-db_db_put"> - - <title><literal>PUT /db</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db"/> - - <remark role="method" condition="PUT"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Creates a new database. The database name must be composed of one - or more of the following characters: - </para> - - <itemizedlist> - - <listitem> - <para> - Lowercase characters (<literal>a-z</literal>) - </para> - </listitem> - - <listitem> - <para> - Name must begin with a lowercase letter - </para> - </listitem> - - <listitem> - <para> - Digits (<literal>0-9</literal>) - </para> - </listitem> - - <listitem> - <para> - Any of the characters <literal>_</literal>, - <literal>$</literal>, <literal>(</literal>, - <literal>)</literal>, <literal>+</literal>, - <literal>-</literal>, and <literal>/</literal>. - </para> - </listitem> - - </itemizedlist> - - <para> - Trying to create a database that does not meet these requirements - will return an error quoting these restrictions. - </para> - - <para> - To create the database <literal>recipes</literal>: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes -Content-Type: application/json -</programlisting> - - <para> - The returned content contains the JSON status: - </para> - -<programlisting> -{ - "ok" : true -} -</programlisting> - - <para> - Anything should be treated as an error, and the problem should be - taken form the HTTP response code. - </para> - - </section> - - <section id="couchdb-api-db_db_delete"> - - <title><literal>DELETE /db</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db"/> - - <remark role="method" condition="DELETE"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Deletes the specified database, and all the documents and - attachments contained within it. - </para> - - <para> - To delete the database <literal>recipes</literal> you would send - the request: - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes -Content-Type: application/json -</programlisting> - - <para> - If successful, the returned JSON will indicate success - </para> - -<programlisting> -{ - "ok" : true -} -</programlisting> - - </section> - - <section id="couchdb-api-db_db-changes_get"> - - <title><literal>GET /db/_changes</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-changes"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - 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 <literal>feed</literal> query argument. - </para> - - <para> - <itemizedlist> - - <listitem> - <para> - <emphasis role="bold">Poll</emphasis> - </para> - - <para> - 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 - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes/_changes -Content-Type: application/json -</programlisting> - - <para> - Will get all of the changes in the database. You can request - a starting point using the <literal>since</literal> 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 - <literal>since</literal> parameter. - </para> - </listitem> - - <listitem> - <para> - <emphasis role="bold">Longpoll</emphasis> - </para> - - <para> - 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. - </para> - - <para> - Because the wait for a change can be significant you can set - a timeout before the connection is automatically closed (the - <literal>timeout</literal> argument). You can also set a - heartbeat interval (using the <literal>heartbeat</literal> - query argument), which sends a newline to keep the - connection open. - </para> - </listitem> - - <listitem> - <para> - <emphasis role="bold">Continuous</emphasis> - </para> - - <para> - 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. - </para> - - <para> - 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. - </para> - </listitem> - - </itemizedlist> - </para> - - <para> - The return structure for <literal>normal</literal> and - <literal>longpoll</literal> modes is a JSON array of changes - objects, and the last update sequence number. The structure is - described in the following table. - </para> - - <para role="meta" id="table-couchdb-api-db_db-json-changes"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="changes"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - The return format for <literal>continuous</literal> mode the - server sends a CRLF (carriage-return, linefeed) delimited line for - each change. Each line contains the - <link linkend="table-couchdb-api-db_db-json-changes">JSON - object</link>. - </para> - - <para> - You can also request the full contents of each document change - (instead of just the change notification) by using the - <literal>include_docs</literal> parameter. - </para> - - <section id="couchdb-api-db_db-changes_get-filters"> - - <title>Filtering</title> - - <para> - 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. - </para> - - <para> - You can also filter the <literal>_changes</literal> 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 - <literal>filter</literal> parameter, specifying the design - document name and filter name. For example: - </para> - -<programlisting> -GET /db/_changes?filter=design_doc/filtername -</programlisting> - - <para> - The <literal>_changes</literal> feed can be used to watch - changes to specific document ID's or the list of - <literal>_design</literal> documents in a database. If the - <literal>filters</literal> parameter is set to - <literal>_doc_ids</literal> a list of doc IDs can be passed in - the <option>doc_ids</option> parameter as a JSON array. - </para> - - <para> - For more information, see - <xref linkend="couchdb-single-changes-filters"/>. - </para> - - </section> - - </section> - - <section id="couchdb-api-db_db-compact_post"> - - <title><literal>POST /db/_compact</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-compact"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Request compaction of the specified database. Compaction - compresses the disk database file by performing the following - operations: - </para> - - <itemizedlist> - - <listitem> - <para> - 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. - </para> - </listitem> - - <listitem> - <para> - Removes old revisions of documents from the database, up to - the per-database limit specified by the - <literal>_revs_limit</literal> database parameter. See - <xref linkend="couchdb-api-db_db_get"/> . - </para> - </listitem> - - </itemizedlist> - - <para> - 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. - </para> - - <para> - You can determine if the compaction process is operating on a - database by obtaining the database meta information, the - <literal>compact_running</literal> value of the returned database - structure will be set to true. See - <xref linkend="couchdb-api-db_db_get"/> . - </para> - - <para> - You can also obtain a list of running processes to determine - whether compaction is currently running. See - <xref linkend="couchdb-api-misc_active-tasks_get"/>. - </para> - - </section> - - <section id="couchdb-api-db_db-compact-design-doc_post"> - - <title><literal>POST /db/_compact/design-doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-compact-design-doc"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - 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. - </para> - - <para> - For example, to compact the views associated with the - <literal>recipes</literal> design document: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_compact/recipes -Content-Type: application/json -</programlisting> - - <para> - CouchDB will immediately return with a status indicating that the - compaction request has been received (HTTP status code 202): - </para> - -<programlisting> -{ - "ok" : true -} - </programlisting> - - </section> - - <section id="couchdb-api-db_db-view-cleanup_post"> - - <title><literal>POST /db/_view_cleanup</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-view-cleanup"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Cleans up the cached view output on disk for a given view. For - example: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_view_cleanup -Content-Type: application/json -</programlisting> - - <para> - If the request is successful, a basic status message us returned: - </para> - -<programlisting> -{ - "ok" : true -} - </programlisting> - - </section> - - <section id="couchdb-api-db_db-ensure-full-commit_post"> - - <title><literal>POST /db/_ensure_full_commit</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-ensure-full-commit"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - 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 <literal>recipes</literal> you would use: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_ensure_full_commit -Content-Type: application/json -</programlisting> - - <para> - This returns a status message, containing the success message and - the timestamp for when the CouchDB instance was started: - </para> - -<programlisting> -{ - "ok" : true, - "instance_start_time" : "1288186189373361" -} -</programlisting> - -<!-- <para>You can also optionally commit to disk all the updates up to a - specified update sequence ID by using the <literal>seq</literal> - argument to the request. The value should be the sequence ID returned - when creating or updating a document:</para> - --> - - </section> - - <section id="couchdb-api-db_db-bulk-docs_post"> - - <title><literal>POST /db/_bulk_docs</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-bulk-docs"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - 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. - </para> - - <para> - For both inserts and updates the basic structure of the JSON is - the same: - </para> - - <para role="meta" id="table-couchdb-api-db_db-bulk-docs-json"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="bulkdocs"/> - - <remark role="version" condition="inherit"/> - </para> - - <section id="couchdb-api-db_db-bulk-docs_post-insert"> - - <title>Inserting Documents in Bulk</title> - - <para> - 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. - </para> - - <para> - For example, the following inserts three new documents, two with - the supplied document IDs, and one which will have a document ID - generated: - </para> - -<programlisting> -{ - "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" - }, - ] -} - </programlisting> - - <para> - 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. - </para> - - <para> - The return structure from the example above contains a list of - the documents created, here with the combination and their - revision IDs: - </para> - -<programlisting> -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", - } -] - </programlisting> - - <para> - The content and structure of the returned JSON will depend on - the transaction semantics being used for the bulk update; see - <xref - linkend="couchdb-api-db_db-bulk-docs_post-commit"/> - for more information. Conflicts and validation errors when - updating documents in bulk must be handled separately; see - <xref - linkend="couchdb-api-db_db-bulk-docs_post-errors"/>. - </para> - - </section> - - <section id="couchdb-api-db_db-bulk-docs_post-update"> - - <title>Updating Documents in Bulk</title> - - <para> - 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. - </para> - - <para> - For example, you could send the following request: - </para> - -<programlisting> -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" - } - ] -} -</programlisting> - - <para> - The return structure is the JSON of the updated documents, with - the new revision and ID information: - </para> - -<programlisting> -[ - { - "id" : "FishStew", - "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1" - }, - { - "id" : "LambStew", - "rev" : "2-0786321986194c92dd3b57dfbfc741ce" - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "rev" : "2-bdd3bf3563bee516b96885a66c743f8e" - } -] -</programlisting> - - <para> - You can optionally delete documents during a bulk update by - adding the <literal>_deleted</literal> field with a value of - <literal>true</literal> to each docment ID/revision combination - within the submitted JSON structure. - </para> - - <para> - 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. - </para> - - <para> - The content and structure of the returned JSON will depend on - the transaction semantics being used for the bulk update; see - <xref - linkend="couchdb-api-db_db-bulk-docs_post-commit"/> - for more information. Conflicts and validation errors when - updating documents in bulk must be handled separately; see - <xref - linkend="couchdb-api-db_db-bulk-docs_post-errors"/>. - </para> - - </section> - - <section id="couchdb-api-db_db-bulk-docs_post-commit"> - - <title>Bulk Documents Transaction Semantics</title> - - <para> - 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: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>non-atomic</literal> - </para> - - <para> - 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. - </para> - - <para> - In this mode, the response structure will indicate whether - the document was updated by supplying the new - <literal>_rev</literal> parameter indicating a new document - revision was created. If the update failed, then you will - get an <literal>error</literal> of type - <literal>conflict</literal>. For example: - </para> - -<programlisting> -[ - { - "id" : "FishStew", - "error" : "conflict", - "reason" : "Document update conflict." - }, - { - "id" : "LambStew", - "error" : "conflict", - "reason" : "Document update conflict." - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "error" : "conflict", - "reason" : "Document update conflict." - } -] - </programlisting> - - <para> - 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. - </para> - </listitem> - - <listitem> - <para> - <literal>all-or-nothing</literal> - </para> - - <para> - 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. - </para> - - <para> - 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: - </para> - -<programlisting> -[ - { - "id" : "FishStew", - "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1" - }, - { - "id" : "LambStew", - "rev" : "2-0786321986194c92dd3b57dfbfc741ce" - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "rev" : "2-bdd3bf3563bee516b96885a66c743f8e" - } -] -</programlisting> - - <para> - 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 - <literal>conflicts=true</literal> query argument when - accessing the view. Conflicts should be handled individually - to ensure the consistency of your database. - </para> - -<!-- TODO: Add the forward reference to conflict resolution --> - - <para> - To use this mode, you must include the - <literal>all_or_nothing</literal> field (set to true) within - the main body of the JSON of the request. - </para> - </listitem> - - </itemizedlist> - - <para> - The effects of different database operations on the different - modes are summarized in the table below: - </para> - - <table id="table-couchdb-api-db_db-bulk-docs_post-commit"> - <title>Conflicts on Bulk Inserts</title> - <tgroup cols="4"> - <thead> - <row> - <entry> - Transaction Mode - </entry> - <entry> - Transaction - </entry> - <entry> - Cause - </entry> - <entry> - Resolution - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - Non-atomic - </entry> - <entry> - Insert - </entry> - <entry> - Requested document ID already exists - </entry> - <entry> - Resubmit with different document ID, or update the - existing document - </entry> - </row> - <row> - <entry> - Non-atomic - </entry> - <entry> - Update - </entry> - <entry> - Revision missing or incorrect - </entry> - <entry> - Resubmit with correct revision - </entry> - </row> - <row> - <entry> - All-or-nothing - </entry> - <entry> - Insert - </entry> - <entry> - Additional revision inserted - </entry> - <entry> - Resolve conflicted revisions - </entry> - </row> - <row> - <entry> - All-or-nothing - </entry> - <entry> - Update - </entry> - <entry> - Additional revision inserted - </entry> - <entry> - Resolve conflicted revisions - </entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - 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. - </para> - - </section> - - <section id="couchdb-api-db_db-bulk-docs_post-errors"> - - <title>Bulk Document Validation and Conflict Errors</title> - - <para> - The JSON returned by the <literal>_bulk_docs</literal> 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. - </para> - - <para> - The exact structure of the returned information is shown in - <xref - linkend="table-couchdb-api-db_db-bulk-docs-return-json"/>. - </para> - - <para role="meta" id="table-couchdb-api-db_db-bulk-docs-return-json"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="bulkdocsreturn"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - When a document (or document revision) is not correctly comitted - to the database because of an error, you should check the - <literal>error</literal> field to determine error type and - course of action. Errors will be one of the following type: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>conflict</literal> - </para> - - <para> - 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 - <literal>all-or-nothing</literal> mode then you will need to - manually resolve the conflicted revisions of the document. - </para> - - <para> - Conflict resolution of documents added using the bulk docs - interface is identical to the resolution procedures used - when resolving conflict errors during replication. - </para> - -<!-- TODO: Add a reference/link to the conflict/replication docs --> - </listitem> - - <listitem> - <para> - <literal>forbidden</literal> - </para> - - <para> - Entries with this error type indicate that the validation - routine applied to the document during submission has - returned an error. - </para> - - <para> - For example, if your validation routine includes the - following: - </para> - -<programlisting> throw({forbidden: 'invalid recipe ingredient'});</programlisting> - - <para> - The error returned will be: - </para> - -<programlisting> -{ - "id" : "7f7638c86173eb440b8890839ff35433", - "error" : "forbidden", - "reason" : "invalid recipe ingredient" -} - </programlisting> - - <para> - For more information, see - <xref linkend="couchdb-api-functional-validation"/>. - </para> - </listitem> - - </itemizedlist> - - </section> - - </section> - - <section id="couchdb-api-db_db-temp-view_post"> - - <title><literal>POST /db/_temp_view</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-temp-view"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Creates (and executes) a temporary view based on the view function - supplied in the JSON request. For example: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_temp_view -Content-Type: application/json - -{ - "map" : "function(doc) { if (doc.value > 9995) { emit(null, doc.value); } }" -} -</programlisting> - - <para> - The resulting JSON response is the result from the execution of - the temporary view: - </para> - -<programlisting> -{ - "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 -} -</programlisting> - - <para> - 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. - </para> - - <para> - For more information, see - <xref linkend="couchdb-api-functional-views"/>. - </para> - - </section> - - <section id="couchdb-api-db_db-purge_post"> - - <title><literal>POST /db/_purge</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-purge"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - 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. - </para> - - <para> - 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. - </para> - - <note> - <para> - Purging documents does not remove the space used by them on - disk. To reclaim disk space, you should run a database compact - (see <xref - linkend="couchdb-api-db_db-compact_post"/>, and - compact views (see - <xref - linkend="couchdb-api-db_db-compact-design-doc_post"/>). - </para> - </note> - - <para> - To perform a purge operation you must send a request including the - JSON of the document IDs that you want to purge. For example: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_purge -Content-Type: application/json - -{ - "FishStew" : [ - "17-b3eb5ac6fbaef4428d712e66483dcb79" - ] -} -</programlisting> - - <para> - The format of the request must include the document ID and one or - more revisions that must be purged. - </para> - - <para> - The response will contain the purge sequence number, and a list of - the document IDs and revisions successfully purged. - </para> - -<programlisting> -{ - "purged" : { - "FishStew" : [ - "17-b3eb5ac6fbaef4428d712e66483dcb79" - ] - }, - "purge_seq" : 11 -} -</programlisting> - - <section id="couchdb-api-db_db-purge_post-indexrebuild"> - - <title>Updating Indexes</title> - - <para> - 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. - </para> - - <para> - 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. - </para> - - <para> - 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. - </para> - - </section> - - </section> - - <section id="couchdb-api-db_db-all-docs_get"> - - <title><literal>GET /db/_all_docs</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-all-docs"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - 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. - </para> - - <para role="meta" id="table-couchdb-api-db_db-all-docs"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="all-docs"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - By default the information returned contains only the document ID - and revision. For example, the request: - </para> - -<programlisting role="httprequest"> -GET http://couchdb:5984/recipes/_all_docs -Accept: application/json -</programlisting> - - <para> - Returns the following structure: - </para> - -<programlisting role="httpresponse"> -{ - "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 -} -</programlisting> - - <para> - 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. - </para> - -<!-- TODO Add link to view --> - - </section> - - <section id="couchdb-api-db_db-all-docs_post"> - - <title><literal>POST /db/_all_docs</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-all-docs"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - The <literal>POST</literal> to <literal>_all_docs</literal> 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 - <xref - linkend="couchdb-api-dbdoc_db-doc_get"/> requests. - </para> - - <para> - The request body should contain a list of the keys to be returned - as an array to a <literal>keys</literal> object. For example: - </para> - -<programlisting role="httprequest"> -POST http://couchdb:5984/recipes/_all_docs -User-Agent: MyApp/0.1 libwww-perl/5.837 - -{ - "keys" : [ - "Zingylemontart", - "Yogurtraita" - ] -} -</programlisting> - - <para> - The return JSON is the all documents structure, but with only the - selected keys in the output: - </para> - -<programlisting role="httpresponse"> -{ - "total_rows" : 2666, - "rows" : [ - { - "value" : { - "rev" : "1-a3544d296de19e6f5b932ea77d886942" - }, - "id" : "Zingylemontart", - "key" : "Zingylemontart" - }, - { - "value" : { - "rev" : "1-91635098bfe7d40197a1b98d7ee085fc" - }, - "id" : "Yogurtraita", - "key" : "Yogurtraita" - } - ], - "offset" : 0 -} -</programlisting> - -<!-- TODO Add link to view --> - - </section> - - <section id="couchdb-api-db_db-missing-revs_post"> - - <title><literal>POST /db/_missing_revs</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-missing-revs"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section id="couchdb-api-db_db-revs-diff_post"> - - <title><literal>POST /db/_revs_diff</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-revs-diff"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section id="couchdb-api-db_db-security_get"> - - <title><literal>GET /db/_security</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-security"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Gets the current secrity object from the specified database. The - security object consists of two compulsory elements, - <literal>admins</literal> and <literal>readers</literal>, 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. - </para> - - <para> - To get the existing security object you would send the following - request: - </para> - -<programlisting> -{ - "admins" : { - "roles" : [], - "names" : [ - "mc", - "slp" - ] - }, - "readers" : { - "roles" : [], - "names" : [ - "tim", - "brian" - ] - } -} -</programlisting> - - <para role="meta" id="table-couchdb-api-db-json-security"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="security"/> - - <remark role="version" condition="inherit"/> - </para> - - <note> - <para> - If the security object for a database has never beent set, then - the value returned will be empty. - </para> - </note> - - </section> - - <section id="couchdb-api-db_db-security_put"> - - <title><literal>PUT /db/_security</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-security"/> - - <remark role="method" condition="PUT"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Sets the security object for the given database.For example, to - set the security object for the <literal>recipes</literal> - database: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/_security -Content-Type: application/json - -{ - "admins" : { - "roles" : [], - "names" : [ - "mc", - "slp" - ] - }, - "readers" : { - "roles" : [], - "names" : [ - "tim", - "brian" - ] - } -}</programlisting> - - <para> - If the setting was successful, a JSON status object will be - returned: - </para> - -<programlisting> -{ - "ok" : true -} -</programlisting> - - </section> - - <section id="couchdb-api-db_db-revs-limit_get"> - - <title><literal>GET /db/_revs_limit</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-revs-limit"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Gets the current <literal>revs_limit</literal> (revision limit) - setting. - </para> - - <para> - For example to get the current limit: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_revs_limit -Content-Type: application/json -</programlisting> - - <para> - The returned information is the current setting as a numerical - scalar: - </para> - -<programlisting> -1000 -</programlisting> - - </section> - - <section id="couchdb-api-db_db-revs-limit_put"> - - <title><literal>PUT /db/_revs_limit</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-revs-limit"/> - - <remark role="method" condition="PUT"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - 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 <literal>PUT</literal> with - a scalar integer of the limit that you want to set as the request - body. - </para> - - <para> - For example to set the revs limit to 100 for the - <literal>recipes</literal> database: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/_revs_limit -Content-Type: application/json - -100 -</programlisting> - - <para> - If the setting was successful, a JSON status object will be - returned: - </para> - -<programlisting> -{ - "ok" : true -} -</programlisting> - - </section> - -</chapter> 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 deleted file mode 100644 index 7b680064e..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-api-dbdoc-metasrc.xml +++ /dev/null @@ -1,1016 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-dbdoc"> - - <title>CouchDB API Server Document Methods</title> - - <para> - The CouchDB API Server Document methods detail how to create, read, - update and delete documents within a database. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <para role="meta" id="table-couchdb-api-dbdoc-summary"> - <remark role="title">Document API Calls</remark> - - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="summarytable"/> - - <remark role="filter_class" condition="dbdoc"/> - - <remark role="version" condition="inherit"/> - - <remark role="idprefix" condition="couchdb-api-dbdoc"/> - </para> - - <section id="couchdb-api-dbdoc_db_post"> - - <title><literal>POST /db</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="dbdoc"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Create a new document in the specified database, using the - supplied JSON document structure. If the JSON structure includes - the <literal>_id</literal> field, then the document will be - created with the specified document ID. If the - <literal>_id</literal> field is not specified, a new unique ID - will be generated. - </para> - - <para> - For example, you can generate a new document with a generated UUID - using the following request: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/ -Content-Type: application/json - -{ - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" -} -</programlisting> - - <para> - The return JSON will specify the automatically enerated ID and - revision information: - </para> - -<programlisting> -{ - "id" : "64575eef70ab90a2b8d55fc09e00440d", - "ok" : true, - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -} -</programlisting> - - <section id="couchdb-api-dbdoc_db_post-docid"> - - <title>Specifying the Document ID</title> - - <para> - The document ID can be specified by including the - <literal>_id</literal> field in the JSON of the submitted - record. The following request will create the same document with - the ID <literal>FishStew</literal>: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/ -Content-Type: application/json - -{ - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" -} -</programlisting> - - <para> - The structure of the submitted document is as shown in the table - below: - </para> - - <para role="meta" id="table-couchdb-api-json-document"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="document"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - In either case, the returned JSON will specify the document ID, - revision ID, and status message: - </para> - -<programlisting> -{ - "id" : "FishStew", - "ok" : true, - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -} - </programlisting> - - </section> - - <section id="couchdb-api-dbdoc_db_batchmode"> - - <title>Batch Mode Writes</title> - - <para> - You can write documents to the database at a higher rate by - using the batch option. This collects document writes together - in memory (on a user-by-user basis) before they are committed to - disk. This increases the risk of the documents not being stored - in the event of a failure, since the documents are not written - to disk immediately. - </para> - - <para> - To use the batched mode, append the <literal>batch=ok</literal> - query argument to the URL of the <literal>PUT</literal> or - <literal>POST</literal> request. The CouchDB server will respond - with a 202 HTTP response code immediately. - </para> - - </section> - - <section id="couchdb-api-dbdoc_db-doc-attachments"> - - <title>Including Attachments</title> - - <para> - You can include one or more attachments with a given document by - incorporating the attachment information within the JSON of the - document. This provides a simpler alternative to loading - documents with attachments than making a separate call (see - <xref - linkend="couchdb-api-dbdoc_db-doc-attachment_put"/>). - </para> - - <para role="meta" id="table-couchdb-api-dbdoc-documentattachments"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="document_with_attachments"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - The <literal>filename</literal> will be the attachment name. For - example, when sending the JSON structure below: - </para> - -<programlisting> -{ - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" - "_attachments" : { - "styling.css" : { - "content-type" : "text/css", - "data" : "cCB7IGZvbnQtc2l6ZTogMTJwdDsgfQo=", - }, - }, -} - </programlisting> - - <para> - The attachment <literal>styling.css</literal> can be accessed - using <literal>/recipes/FishStew/styling.css</literal>. For more - information on attachments, see - <xref - linkend="couchdb-api-dbdoc_db-doc-attachment_get"/>. - </para> - - <para> - The document data embedded in to the structure must be encoded - using base64. - </para> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_get"> - - <title><literal>GET /db/doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-doc"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Returns the specified <literal>doc</literal> from the specified - <literal>db</literal>. For example, to retrieve the document with - the id <literal>FishStew</literal> you would send the following - request: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/FishStew -Content-Type: application/json -Accept: application/json -</programlisting> - - <para> - The returned JSON is the JSON of the document, including the - document ID and revision number: - </para> - -<programlisting> -{ - "_id" : "FishStew", - "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c", - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "title" : "Irish Fish Stew" -} - </programlisting> - - <para> - Unless you request a specific revision, the latest revision of the - document will always be returned. - </para> - - <section id="couchdb-api-dbdoc_db-doc_get-attachments"> - - <title>Attachments</title> - - <para> - If the document includes attachments, then the returned - structure will contain a summary of the attachments associatd - with the document, but not the attachment data itself. - </para> - - <para> - The JSON for the returned document will include the - <literal>_attachments</literal> field, with one or more - attachment definitions. For example: - </para> - -<programlisting> -{ - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" - "_attachments" : { - "styling.css" : { - "stub" : true, - "content-type" : "text/css", - "length" : 783426, - }, - }, -} -</programlisting> - - <para> - The format of the returned JSON is shown in the table below: - </para> - - <para role="meta" id="table-couchdb-api-dbdoc-returneddocumentattachments"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="returneddocument_with_attachments"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_get-revs"> - - <title>Getting a List of Revisions</title> - - <para> - You can obtain a list of the revisions for a given document by - adding the <literal>revs=true</literal> parameter to the request - URL. For example: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/FishStew?revs=true -Accept: application/json -</programlisting> - - <para> - The returned JSON structure includes the original document, - including a <literal>_revisions</literal> structure that - includes the revision information: - </para> - -<programlisting> -{ - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "_id" : "FishStew", - "title" : "Irish Fish Stew", - "_revisions" : { - "ids" : [ - "a1a9b39ee3cc39181b796a69cb48521c", - "7c4740b4dcf26683e941d6641c00c39d", - "9c65296036141e575d32ba9c034dd3ee" - ], - "start" : 3 - }, - "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" -} -</programlisting> - - <para role="meta" id="table-couchdb-api-dbdoc-document_with_revs"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="document_with_revs"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_get-revsextended"> - - <title>Obtaining an Extended Revision History</title> - - <para> - You can get additional information about the revisions for a - given document by supplying the <literal>revs_info</literal> - argument to the query: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/FishStew?revs_info=true -Accept: application/json -</programlisting> - - <para> - This returns extended revision information, including the - availability and status of each revision: - </para> - -<programlisting> -{ - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "_id" : "FishStew", - "_revs_info" : [ - { - "status" : "available", - "rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" - }, - { - "status" : "available", - "rev" : "2-7c4740b4dcf26683e941d6641c00c39d" - }, - { - "status" : "available", - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" - } - ], - "title" : "Irish Fish Stew", - "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" -} -</programlisting> - - <para role="meta" id="table-couchdb-api-dbdoc-document_with_revs_info"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="document_with_revs_info"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_get-specrev"> - - <title>Obtaining a Specific Revision</title> - - <para> - To get a specific revision, use the <literal>rev</literal> - argument to the request, and specify the full revision number: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d -Accept: application/json -</programlisting> - - <para> - The specified revision of the document will be returned, - including a <literal>_rev</literal> field specifying the - revision that was requested: - </para> - -<programlisting> -{ - "_id" : "FishStew", - "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d", - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "title" : "Fish Stew" -} -</programlisting> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_head"> - - <title><literal>HEAD /db/doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-doc"/> - - <remark role="method" condition="HEAD"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Returns the HTTP Headers containing a minimal amount of - information about the specified document. The method supports the - same query arguments as the <literal>GET</literal> method, but - only the header information (including document size, and the - revision as an ETag), is returned. For example, a simple - <literal>HEAD</literal> request: - </para> - -<programlisting> -HEAD http://couchdb:5984/recipes/FishStew -Content-Type: application/json - </programlisting> - - <para> - Returns the following HTTP Headers: - </para> - -<programlisting> -HTTP/1.1 200 OK -Server: CouchDB/1.0.1 (Erlang OTP/R13B) -Etag: "7-a19a1a5ecd946dad70e85233ba039ab2" -Date: Fri, 05 Nov 2010 14:54:43 GMT -Content-Type: text/plain;charset=utf-8 -Content-Length: 136 -Cache-Control: must-revalidate -</programlisting> - - <para> - The <literal>Etag</literal> header shows the current revision for - the requested document, and the <literal>Content-Length</literal> - specifies the length of the data, if the document were requested - in full. - </para> - - <para> - Adding any of the query arguments (as supported by - <link linkend="couchdb-api-dbdoc_db-doc_get"><literal>GET</literal></link> - method), then the resulting HTTP Headers will correspond to what - would be returned. Note that the current revision is not returned - when the <literal>refs_info</literal> argument is used. For - example: - </para> - -<programlisting> -HTTP/1.1 200 OK -Server: CouchDB/1.0.1 (Erlang OTP/R13B) -Date: Fri, 05 Nov 2010 14:57:16 GMT -Content-Type: text/plain;charset=utf-8 -Content-Length: 609 -Cache-Control: must-revalidate -</programlisting> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_put"> - - <title><literal>PUT /db/doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-doc"/> - - <remark role="method" condition="PUT"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - The <literal>PUT</literal> method creates a new named document, or - creates a new revision of the existing document. Unlike the - <link linkend="couchdb-api-dbdoc_db_post"><literal>POST</literal></link> - method, you must specify the document ID in the request URL. - </para> - - <para> - For example, to create the docment <literal>FishStew</literal>, - you would send the following request: - </para> - -<programlisting>PUT http://couchdb:5984/recipes/FishStew -Content-Type: application/json - -{ - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" -} -</programlisting> - - <para> - The return type is JSON of the status, document ID,and revision - number: - </para> - -<programlisting> -{ - "id" : "FishStew", - "ok" : true, - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -} -</programlisting> - - <section id="couchdb-api-dbdoc_db-doc_put-update"> - - <title>Updating an Existing Document</title> - - <para> - To update an existing document you must specify the current - revision number within the <literal>_rev</literal> parameter. - For example: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/FishStew -Content-Type: application/json - -{ - "_rev" : "1-9c65296036141e575d32ba9c034dd3ee", - "servings" : 4, - "subtitle" : "Delicious with fresh salad", - "title" : "Fish Stew" -} -</programlisting> - - <para> - Alternatively, you can supply the current revision number in the - <literal>If-Match</literal> HTTP header of the request. For - example: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/FishStew -If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea -Content-Type: application/json - -{ - "servings" : 4, - "subtitle" : "Delicious with fresh salad", - "title" : "Fish Stew" -} -</programlisting> - - <para> - The JSON returned will include the updated revision number: - </para> - -<programlisting> -{ - "id" : "FishStew99", - "ok" : true, - "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea" -} -</programlisting> - - <para> - For information on batched writes, which can provide improved - performance, see - <xref linkend="couchdb-api-dbdoc_db_batchmode"/>. - </para> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_delete"> - - <title><literal>DELETE /db/doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-doc"/> - - <remark role="method" condition="DELETE"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Deletes the specified document from the database. You must supply - the current (latest) revision, either by using the - <literal>rev</literal> parameter to specify the revision: - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c -Content-Type: application/json -</programlisting> - - <para> - Alternatively, you can use ETags with the - <literal>If-Match</literal> field: - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes/FishStew -If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c -Content-Type: application/json - </programlisting> - - <para> - The returned JSON contains the document ID, revision and status: - </para> - -<programlisting> -{ - "id" : "FishStew", - "ok" : true, - "rev" : "4-2719fd41187c60762ff584761b714cfb" -} -</programlisting> - - <note> - <para> - Note that deletion of a record increments the revision number. - The use of a revision for deletion of the record allows - replication of the database to correctly track the deletion in - synchronized copies. - </para> - </note> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_copy"> - - <title><literal>COPY /db/doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-doc"/> - - <remark role="method" condition="COPY"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - The <literal>COPY</literal> command (which is non-standard HTTP) - copies an existing document to a new or existing document. - </para> - - <para> - The source document is specified on the request line, with the - <literal>Destination</literal> HTTP Header of the request - specifying the target document. - </para> - - <section id="couchdb-api-dbdoc_db-doc_copy-simple"> - - <title>Copying a Document</title> - - <para> - You can copy the latest version of a document to a new document - by specifying the current document and target document: - </para> - -<programlisting> -COPY http://couchdb:5984/recipes/FishStew -Content-Type: application/json -Destination: IrishFishStew -</programlisting> - - <para> - The above request copies the document - <literal>FishStew</literal> to the new document - <literal>IrishFishStew</literal>. The response is the ID and - revision of the new document. - </para> - -<programlisting> -{ - "id" : "IrishFishStew", - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -} -</programlisting> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_copy-specrev"> - - <title>Copying from a Specific Revision</title> - - <para> - To copy <emphasis>from</emphasis> a specific version, use the - <literal>rev</literal> argument to the query string: - </para> - -<programlisting> -COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082 -Content-Type: application/json -Destination: IrishFishStew -</programlisting> - - <para> - The new document will be created using the information in the - specified revision of the source document. - </para> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_copy-existing"> - - <title>Copying to an Existing Document</title> - - <para> - To copy to an existing document, you must specify the current - revision string for the target document, using the - <literal>rev</literal> parameter to the - <literal>Destination</literal> HTTP Header string. For example: - </para> - -<programlisting> -COPY http://couchdb:5984/recipes/FishStew -Content-Type: application/json -Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee -</programlisting> - - <para> - The return value will be the new revision of the copied - document: - </para> - -<programlisting> -{ - "id" : "IrishFishStew", - "rev" : "2-55b6a1b251902a2c249b667dab1c6692" -} -</programlisting> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc-attachment_get"> - - <title><literal>GET /db/doc/attachment</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-doc-attachment"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Returns the file attachment <literal>attachment</literal> - associated with the document <literal>doc</literal>. The raw data - of the associated attachment is returned (just as if you were - accessing a static file. The returned HTTP - <literal>Content-type</literal> will be the same as the content - type set when the document attachment was submitted into the - database. - </para> - - </section> - - <section id="couchdb-api-dbdoc_db-doc-attachment_put"> - - <title><literal>PUT /db/doc/attachment</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-doc-attachment"/> - - <remark role="method" condition="PUT"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Upload the supplied content as an attachment to the specified - document (<literal>doc</literal>). The - <literal>attachment</literal> name provided must be a URL encoded - string. You must also supply either the <literal>rev</literal> - query argument or the <literal>If-Match</literal> HTTP header for - validation, and the HTTP headers (to set the attacment content - type). The content type is used when the attachment is requested - as the corresponding content-type in the returned document header. - </para> - - <para> - For example, you could upload a simple text document using the - following request: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca -Content-Length: 10 -Content-Type: text/plain - -Roast it - -</programlisting> - - <para> - Or by using the <literal>If-Match</literal> HTTP header: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/FishStew/basic -If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca -Content-Length: 10 -Content-Type: text/plain - -Roast it - -</programlisting> - - <para> - The returned JSON contains the new document information: - </para> - -<programlisting> -{ - "id" : "FishStew", - "ok" : true, - "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74" -} -</programlisting> - - <note> - <para> - Uploading an attachment updates the corresponding document - revision. Revisions are tracked for the parent document, not - individual attachments. - </para> - </note> - - <section id="couchdb-api-dbdoc_db-doc-attachment_put-existing"> - - <title>Updating an Existing Attachment</title> - - <para> - Uploading an attachment using an existing attachment name will - update the corresponding stored content of the database. Since - you must supply the revision information to add an attachment to - a document, this serves as validation to update the existing - attachment. - </para> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc-attachment_delete"> - - <title><literal>DELETE /db/doc/attachment</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-doc-attachment"/> - - <remark role="method" condition="DELETE"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Deletes the attachment <literal>attachment</literal> to the - specified <literal>doc</literal>. You must supply the - <literal>rev</literal> argument with the current revision to - delete the attachment. - </para> - - <para> - For example to delete the attachment <literal>basic</literal> from - the recipe <literal>FishStew</literal>: - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74 -Content-Type: application/json - - </programlisting> - - <para> - The returned JSON contains the updated revision information: - </para> - -<programlisting> -{ - "id" : "FishStew", - "ok" : true, - "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e" -} -</programlisting> - - </section> - -</chapter> 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 deleted file mode 100644 index f4edf75a3..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-api-design-metasrc.xml +++ /dev/null @@ -1,1462 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-design"> - - <title>CouchDB API Server Design Document Methods</title> - - <para> - In CouchDB, design documents provide the main interface for building - a CouchDB application. The design document defines the views used to - extract information from CouchDB through one or more views. Design - documents are created within your CouchDB instance in the same way - as you create database documents, but the content and definition of - the documents is different. Design Documents are named using an ID - defined with the design document URL path, and this URL can then be - used to access the database contents. - </para> - - <para> - Views and lists operate together to provide automated (and - formatted) output from your database. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <para role="meta" id="table-couchdb-api-design-summary"> - <remark role="title">Design Document API Calls</remark> - - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="summarytable"/> - - <remark role="filter_class" condition="design"/> - - <remark role="version" condition="inherit"/> - - <remark role="idprefix" condition="couchdb-api-design"/> - </para> - - <section id="couchdb-api-design_db-design-designdoc_get"> - - <title><literal>GET /db/_design/design-doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Returns the specified design document, - <literal>design-doc</literal> from the specified - <literal>db</literal>. For example, to retrieve the design - document <literal>recipes</literal> you would send the following - request: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_design/recipes -Content-Type: application/json -</programlisting> - - <para> - The returned string will be the JSON of the design document: - </para> - -<programlisting> -{ - "_id" : "_design/recipes", - "_rev" : "5-39f56a392b86bbee57e2138921346406" - "language" : "javascript", - "views" : { - "by_recipe" : { - "map" : "function(doc) { if (doc.title != null) emit(doc.title, doc) }" - }, - }, -} -</programlisting> - - <para> - A list of the revisions can be obtained by using the - <literal>revs</literal> query argument, or an extended list of - revisions using the <literal>revs_info</literal> query argument. - This operates in the same way as for other documents. Fur further - examples, see - <xref - linkend="couchdb-api-dbdoc_db-doc_get"/>. - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_put"> - - <title><literal>PUT /db/_design/design-doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc"/> - - <remark role="method" condition="PUT"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Upload the specified design document, - <literal>design-doc</literal>, to the specified database. The - design document should follow the definition of a design document, - as summarised in the following table. - </para> - - <para role="meta" id="table-couchdb-api-json-designdoc"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="design-doc"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - For more information on writing views, see - <xref - linkend="couchdb-api-functional-views"/>. - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_delete"> - - <title><literal>DELETE /db/_design/design-doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc"/> - - <remark role="method" condition="DELETE"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Delete an existing design document. Deleting a design document - also deletes all of the associated view indexes, and recovers the - corresponding space on disk for the indexes in question. - </para> - - <para> - To delete, you must specify the current revision of the design - document using the <literal>rev</literal> query argument. - </para> - - <para> - For example: - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8 -Content-Type: application/json -</programlisting> - - <para> - The response contains the delete document ID and revision: - </para> - -<programlisting> -{ - "id" : "recipe/_design/recipes" - "ok" : true, - "rev" : "3-7a05370bff53186cb5d403f861aca154", -} -</programlisting> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_copy"> - - <title><literal>COPY /db/_design/design-doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc"/> - - <remark role="method" condition="COPY"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - The <literal>COPY</literal> command (non-standard HTTP) copies an - existing design document to a new or existing document. - </para> - - <para> - The source design document is specified on the request line, with - the <literal>Destination</literal> HTTP Header of the request - specifying the target document. - </para> - - <section id="couchdb-api-design_db-design-designdoc_copy-simple"> - - <title>Copying a Design Document</title> - - <para> - To copy the latest version of a design document to a new - document you specify the base document and target document: - </para> - -<programlisting> -COPY http://couchdb:5984/recipes/_design/recipes -Content-Type: application/json -Destination: /recipes/_design/recipelist -</programlisting> - - <para> - The above request copies the design document - <literal>recipes</literal> to the new design document - <literal>recipelist</literal>. The response is the ID and - revision of the new document. - </para> - -<programlisting> -{ - "id" : "recipes/_design/recipelist" - "rev" : "1-9c65296036141e575d32ba9c034dd3ee", -} -</programlisting> - - <note> - <para> - Copying a design document does automatically reconstruct the - view indexes. These will be recreated, as with other views, - the first time the new view is accessed. - </para> - </note> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_copy-specrev"> - - <title>Copying from a Specific Revision</title> - - <para> - To copy <emphasis>from</emphasis> a specific version, use the - <literal>rev</literal> argument to the query string: - </para> - -<programlisting> -COPY http://couchdb:5984/recipes/_design/recipes?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5 -Content-Type: application/json -Destination: recipes/_design/recipelist -</programlisting> - - <para> - The new design document will be created using the specified - revision of the source document. - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_copy-existing"> - - <title>Copying to an Existing Design Document</title> - - <para> - To copy to an existing document, you must specify the current - revision string for the target document, using the - <literal>rev</literal> parameter to the - <literal>Destination</literal> HTTP Header string. For example: - </para> - -<programlisting> -COPY http://couchdb:5984/recipes/_design/recipes -Content-Type: application/json -Destination: recipes/_design/recipelist?rev=1-9c65296036141e575d32ba9c034dd3ee -</programlisting> - - <para> - The return value will be the new revision of the copied - document: - </para> - -<programlisting> -{ - "id" : "recipes/_design/recipes" - "rev" : "2-55b6a1b251902a2c249b667dab1c6692", -} -</programlisting> - - </section> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-attachment_get"> - - <title><literal>GET /db/_design/design-doc/attachment</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-attachment"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Returns the file attachment <literal>attachment</literal> - associated with the design document - <literal>/_design_/design-doc</literal>. The raw data of the - associated attachment is returned (just as if you were accessing a - static file. The returned HTTP <literal>Content-type</literal> - will be the same as the content type set when the document - attachment was submitted into the database. - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-attachment_put"> - - <title><literal>PUT /db/_design/design-doc/attachment</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-attachment"/> - - <remark role="method" condition="PUT"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Upload the supplied content as an attachment to the specified - design document (<literal>/_design/design-doc</literal>). The - <literal>attachment</literal> name provided must be a URL encoded - string. You must also supply either the <literal>rev</literal> - query argument or the <literal>If-Match</literal> HTTP header for - validation, and the HTTP headers (to set the attacment content - type). The content type is used when the attachment is requested - as the corresponding content-type in the returned document header. - </para> - - <para> - For example, you could upload a simple text document using the - following request: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/_design/recipes/view.css?rev=7-f7114d4d81124b223283f3e89eee043e -Content-Length: 39 -Content-Type: text/plain - -div.recipetitle { -font-weight: bold; -} - -</programlisting> - - <para> - Or by using the <literal>If-Match</literal> HTTP header: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/FishStew/basic -If-Match: 7-f7114d4d81124b223283f3e89eee043e -Content-Length: 39 -Content-Type: text/plain - -div.recipetitle { -font-weight: bold; -} - -</programlisting> - - <para> - The returned JSON contains the new document information: - </para> - -<programlisting> -{ - "id" : "_design/recipes" - "ok" : true, - "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5", -} -</programlisting> - - <note> - <para> - Uploading an attachment updates the corresponding document - revision. Revisions are tracked for the parent document, not - individual attachments. - </para> - </note> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-attachment_delete"> - - <title><literal>DELETE /db/_design/design-doc/attachment</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-attachment"/> - - <remark role="method" condition="DELETE"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Deletes the attachment <literal>attachment</literal> to the - specified <literal>_design/design-doc</literal>. You must supply - the <literal>rev</literal> argument with the current revision to - delete the attachment. - </para> - - <para> - For example to delete the attachment <literal>view.css</literal> - from the design document <literal>recipes</literal>: - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a - </programlisting> - - <para> - The returned JSON contains the updated revision information for - the parent document: - </para> - -<programlisting> -{ - "id" : "_design/recipes" - "ok" : true, - "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c", -} -</programlisting> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-info_get"> - - <title><literal>GET /db/_design/design-doc/_info</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-info"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Obtains information about a given design document, including the - index, index size and current status of the design document and - associated index information. - </para> - - <para> - For example, to get the information for the - <literal>recipes</literal> design document: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_design/recipes/_info -Content-Type: application/json -</programlisting> - - <para> - This returns the following JSON structure: - </para> - -<programlisting> -{ - "name" : "recipes" - "view_index" : { - "compact_running" : false, - "updater_running" : false, - "language" : "javascript", - "purge_seq" : 10, - "waiting_commit" : false, - "waiting_clients" : 0, - "signature" : "fc65594ee76087a3b8c726caf5b40687", - "update_seq" : 375031, - "disk_size" : 16491 - }, -} -</programlisting> - - <para> - The individual fields in the returned JSON structure are detailed - in - <xref linkend="table-couchdb-api-design_db-designdoc-info-json"/>. - </para> - - <para role="meta" id="table-couchdb-api-design_db-designdoc-info-json"> - <remark role="title">Design Document Info JSON Contents</remark> - - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="design-doc_info"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_get"> - - <title><literal>GET /db/_design/design-doc/_view/view-name</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-view-viewname"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Executes the specified <literal>view-name</literal> from the - specified <literal>design-doc</literal> design document. - </para> - - <section - id="couchdb-api-design_db-design-designdoc-view-viewname_get-indexes"> - - <title>Querying Views and Indexes</title> - - <para> - The definition of a view within a design document also creates - an index based on the key information defined within each view. - The production and use of the index significantly increases the - speed of access and searching or selecting documents from the - view. - </para> - - <para> - However, the index is not updated when new documents are added - or modified in the database. Instead, the index is generated or - updated, either when the view is first accessed, or when the - view is accessed after a document has been updated. In each - case, the index is updated before the view query is executed - against the database. - </para> - - <para> - View indexes are updated incrementally in the following - situations: - </para> - - <itemizedlist> - - <listitem> - <para> - A new document has been added to the database. - </para> - </listitem> - - <listitem> - <para> - A document has been deleted from the database. - </para> - </listitem> - - <listitem> - <para> - A document in the database has been updated. - </para> - </listitem> - - </itemizedlist> - - <para> - View indexes are rebuilt entirely when the view definition - changes. To achieve this, a 'fingerprint' of the view definition - is created when the design document is updated. If the - fingerprint changes, then the view indexes are entirely rebuilt. - This ensures that changes to the view definitions are reflected - in the view indexes. - </para> - - <note> - <para> - View index rebuilds occur when one view from the same the view - group (i.e. all the views defined within a single a design - document) has been determined as needing a rebuild. For - example, if if you have a design document with different - views, and you update the database, all three view indexes - within the design document will be updated. - </para> - </note> - - <para> - Because the view is updated when it has been queried, it can - result in a delay in returned information when the view is - accessed, especially if there are a large number of documents in - the database and the view index does not exist. There are a - number of ways to mitigate, but not completely eliminate, these - issues. These include: - </para> - - <itemizedlist> - - <listitem> - <para> - Create the view definition (and associated design documents) - on your database before allowing insertion or updates to the - documents. If this is allowed while the view is being - accessed, the index can be updated incrementally. - </para> - </listitem> - - <listitem> - <para> - Manually force a view request from the database. You can do - this either before users are allowed to use the view, or you - can access the view manually after documents are added or - updated. - </para> - </listitem> - - <listitem> - <para> - Use the <literal>/db/_changes</literal> method to monitor - for changes to the database and then access the view to - force the corresponding view index to be updated. See - <xref - linkend="couchdb-api-db_db-changes_get"/> - for more information. - </para> - </listitem> - - <listitem> - <para> - Use a monitor with the - <literal>update_notification</literal> section of the - CouchDB configuration file to monitor for changes to your - database, and trigger a view query to force the view to be - updated. For more information, see - <xref - linkend="couchdb-single-configuration-update_notification"/>. - </para> - </listitem> - - </itemizedlist> - - <para> - None of these can completely eliminate the need for the indexes - to be rebuilt or updated when the view is accessed, but they may - lessen the effects on end-users of the index update affecting - the user experience. - </para> - - <para> - Another alternative is to allow users to access a 'stale' - version of the view index, rather than forcing the index to be - updated and displaying the updated results. Using a stale view - may not return the latest information, but will return the - results of the view query using an existing version of the - index. - </para> - - <para> - For example, to access the existing stale view - <literal>by_recipe</literal> in the <literal>recipes</literal> - design document: - </para> - -<programlisting>http://couchdb:5984/recipes/_design/recipes/_view/by_recipe?stale=ok</programlisting> - - <para> - Accessing a stale view: - </para> - - <itemizedlist> - - <listitem> - <para> - Does not trigger a rebuild of the view indexes, even if - there have been changes since the last access. - </para> - </listitem> - - <listitem> - <para> - Returns the current version of the view index, if a current - version exists. - </para> - </listitem> - - <listitem> - <para> - Returns an empty result set if the given view index does - exist. - </para> - </listitem> - - </itemizedlist> - - <para> - As an alternative, you use the <literal>update_after</literal> - value to the <option>stale</option> paramater. This causes the - view to be returned as a stale view, but for the update process - to be triggered after the view information has been returned to - the client. - </para> - - <para> - In addition to using stale views, you can also make use of the - <literal>update_seq</literal> query argument. Using this query - argument generates the view information including the update - sequence of the database from which the view was generated. The - returned value can be compared this to the current update - sequence exposed in the database information (returned by - <xref linkend="couchdb-api-db_db_get"/>). - </para> - - </section> - - <section - id="couchdb-api-design_db-design-designdoc-view-viewname_get-sorting"> - - <title>Sorting Returned Rows</title> - - <para> - Each element within the returned array is sorted using native - UTF-8 sorting according to the contents of the key portion of - the emitted content. The basic order of output is as follows: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>null</literal> - </para> - </listitem> - - <listitem> - <para> - <literal>false</literal> - </para> - </listitem> - - <listitem> - <para> - <literal>true</literal> - </para> - </listitem> - - <listitem> - <para> - Numbers - </para> - </listitem> - - <listitem> - <para> - Text (case sensitive, lowercase first) - </para> - </listitem> - - <listitem> - <para> - Arrays (according to the values of each element, in order) - </para> - </listitem> - - <listitem> - <para> - Objects (according to the values of keys, in key order) - </para> - </listitem> - - </itemizedlist> - -<!-- TODO: Point to the view definition docs for information on the collation - specification --> - - <para> - You can reverse the order of the returned view information by - using the <literal>descending</literal> query value set to true. - For example, Retrieving the list of recipes using the - <literal>by_title</literal> (limited to 5 records) view: - </para> - -<programlisting> -{ - "offset" : 0, - "rows" : [ - { - "id" : "3-tiersalmonspinachandavocadoterrine", - "key" : "3-tier salmon, spinach and avocado terrine", - "value" : [ - null, - "3-tier salmon, spinach and avocado terrine" - ] - }, - { - "id" : "Aberffrawcake", - "key" : "Aberffraw cake", - "value" : [ - null, - "Aberffraw cake" - ] - }, - { - "id" : "Adukiandorangecasserole-microwave", - "key" : "Aduki and orange casserole - microwave", - "value" : [ - null, - "Aduki and orange casserole - microwave" - ] - }, - { - "id" : "Aioli-garlicmayonnaise", - "key" : "Aioli - garlic mayonnaise", - "value" : [ - null, - "Aioli - garlic mayonnaise" - ] - }, - { - "id" : "Alabamapeanutchicken", - "key" : "Alabama peanut chicken", - "value" : [ - null, - "Alabama peanut chicken" - ] - } - ], - "total_rows" : 2667 -} -</programlisting> - - <para> - Requesting the same in descending order will reverse the entire - view content. For example the request - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_design/recipes/_view/by_title?limit=5&descending=true -Accept: application/json -Content-Type: application/json</programlisting> - - <para> - Returns the last 5 records from the view: - </para> - -<programlisting> -{ - "offset" : 0, - "rows" : [ - { - "id" : "Zucchiniinagrodolcesweet-sourcourgettes", - "key" : "Zucchini in agrodolce (sweet-sour courgettes)", - "value" : [ - null, - "Zucchini in agrodolce (sweet-sour courgettes)" - ] - }, - { - "id" : "Zingylemontart", - "key" : "Zingy lemon tart", - "value" : [ - null, - "Zingy lemon tart" - ] - }, - { - "id" : "Zestyseafoodavocado", - "key" : "Zesty seafood avocado", - "value" : [ - null, - "Zesty seafood avocado" - ] - }, - { - "id" : "Zabaglione", - "key" : "Zabaglione", - "value" : [ - null, - "Zabaglione" - ] - }, - { - "id" : "Yogurtraita", - "key" : "Yogurt raita", - "value" : [ - null, - "Yogurt raita" - ] - } - ], - "total_rows" : 2667 -} -</programlisting> - - <para> - The sorting direction is applied before the filtering applied - using the <literal>startkey</literal> and - <literal>endkey</literal> query arguments. For example the - following query: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?startkey=%22carrots%22&endkey=%22egg%22 -Accept: application/json -Content-Type: application/json -</programlisting> - - <para> - Will operate correctly when listing all the matching entries - between <quote>carrots</quote> and <literal>egg</literal>. If - the order of output is reversed with the - <literal>descending</literal> query argument, the view request - will return no entries: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22carrots%22&endkey=%22egg%22 -Accept: application/json -Content-Type: application/json -</programlisting> - - <para> - The returned result is empty: - </para> - -<programlisting> -{ - "total_rows" : 26453, - "rows" : [], - "offset" : 21882 -} -</programlisting> - - <para> - The results will be empty because the entries in the view are - reversed before the key filter is applied, and therefore the - <literal>endkey</literal> of <quote>egg</quote> will be seen - before the <literal>startkey</literal> of - <quote>carrots</quote>, resulting in an empty list. - </para> - - <para> - Instead, you should reverse the values supplied to the - <literal>startkey</literal> and <literal>endkey</literal> - parameters to match the descending sorting applied to the keys. - Changing the previous example to: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22egg%22&endkey=%22carrots%22 -Accept: application/json -Content-Type: application/json -</programlisting> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_get-ranges"> - - <title>Specifying Start and End Values</title> - - <para> - The <literal>startkey</literal> and <literal>endkey</literal> - query arguments can be used to specify the range of values to be - displayed when querying the view. - </para> - - <note> - <para> - The values - </para> - </note> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_get-limit"> - - <title>Using Limits and Skipping Rows</title> - - <para> - TBC - </para> - - </section> - - <section - id="couchdb-api-design_db-design-designdoc-view-viewname_get-reduction"> - - <title>View Reduction and Grouping</title> - - <para> - TBC - </para> - - </section> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_post"> - - <title><literal>POST /db/_design/design-doc/_view/view-name</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-view-viewname"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Executes the specified <literal>view-name</literal> from the - specified <literal>design-doc</literal> design document. Unlike - the <literal>GET</literal> method for accessing views, the - <literal>POST</literal> method supports the specification of - explicit keys to be retrieved from the view results. The remainder - of the <literal>POST</literal> view functionality is identical to - the - <xref - linkend="couchdb-api-design_db-design-designdoc-view-viewname_get"/> - fun - </para> - - <para> - For example, the request below will return all the recipes where - the key for the view matches either <quote>claret</quote> or - <quote>clear apple cider</quote> : - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient -Content-Type: application/json - -{ - "keys" : [ - "claret", - "clear apple juice" - ] -} - </programlisting> - - <para> - The returned view data contains the standard view information, but - only where the keys match. - </para> - -<programlisting> -{ - "total_rows" : 26484, - "rows" : [ - { - "value" : [ - "Scotch collops" - ], - "id" : "Scotchcollops", - "key" : "claret" - }, - { - "value" : [ - "Stand pie" - ], - "id" : "Standpie", - "key" : "clear apple juice" - } - ], - "offset" : 6324 -} -</programlisting> - - <section - id="couchdb-api-design_db-design-designdoc-view-viewname_post-multidoc"> - - <title>Multi-document Fetching</title> - - <para> - By combining the <literal>POST</literal> method to a given view - with the <literal>include_docs=true</literal> query argument you - can obtain multiple documents from a database. The result is - more efficient than using multiple - <xref - linkend="couchdb-api-dbdoc_db-doc_get"/> - requests. - </para> - - <para> - For example, sending the following request for ingredients - matching <quote>claret</quote> and <quote>clear apple - juice</quote>: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?include_docs=true -Content-Type: application/json - -{ - "keys" : [ - "claret", - "clear apple juice" - ] -} -</programlisting> - - <para> - Returns the full document for each recipe: - </para> - -<programlisting> -{ - "offset" : 6324, - "rows" : [ - { - "doc" : { - "_id" : "Scotchcollops", - "_rev" : "1-bcbdf724f8544c89697a1cbc4b9f0178", - "cooktime" : "8", - "ingredients" : [ - { - "ingredient" : "onion", - "ingredtext" : "onion, peeled and chopped", - "meastext" : "1" - }, - ... - ], - "keywords" : [ - "cook method.hob, oven, grill@hob", - "diet@wheat-free", - "diet@peanut-free", - "special collections@classic recipe", - "cuisine@british traditional", - "diet@corn-free", - "diet@citrus-free", - "special collections@very easy", - "diet@shellfish-free", - "main ingredient@meat", - "occasion@christmas", - "meal type@main", - "diet@egg-free", - "diet@gluten-free" - ], - "preptime" : "10", - "servings" : "4", - "subtitle" : "This recipe comes from an old recipe book of 1683 called 'The Gentlewoman's Kitchen'. This is an excellent way of making a rich and full-flavoured meat dish in a very short time.", - "title" : "Scotch collops", - "totaltime" : "18" - }, - "id" : "Scotchcollops", - "key" : "claret", - "value" : [ - "Scotch collops" - ] - }, - { - "doc" : { - "_id" : "Standpie", - "_rev" : "1-bff6edf3ca2474a243023f2dad432a5a", - "cooktime" : "92", - "ingredients" : [ -... ], - "keywords" : [ - "diet@dairy-free", - "diet@peanut-free", - "special collections@classic recipe", - "cuisine@british traditional", - "diet@corn-free", - "diet@citrus-free", - "occasion@buffet party", - "diet@shellfish-free", - "occasion@picnic", - "special collections@lunchbox", - "main ingredient@meat", - "convenience@serve with salad for complete meal", - "meal type@main", - "cook method.hob, oven, grill@hob / oven", - "diet@cow dairy-free" - ], - "preptime" : "30", - "servings" : "6", - "subtitle" : "Serve this pie with pickled vegetables and potato salad.", - "title" : "Stand pie", - "totaltime" : "437" - }, - "id" : "Standpie", - "key" : "clear apple juice", - "value" : [ - "Stand pie" - ] - } - ], - "total_rows" : 26484 -} -</programlisting> - - </section> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-show-showname_get"> - - <title><literal>POST /db/_design/design-doc/_show/show-name</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-show-showname"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para></para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-show-showname-doc_get"> - - <title><literal>POST /db/_design/design-doc/_show/show-name/doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-show-showname-doc"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para></para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-list-listname-otherdesigndoc-viewname_get"> - - <title><literal>GET - /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-list-listname-otherdesigndoc-viewname"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-list-listname-otherdesigndoc-viewname_post"> - - <title><literal>POST - /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-list-listname-otherdesigndoc-viewname"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-list-listname-viewname_get"> - - <title><literal>GET /db/_design/design-doc/_list/list-name/view-name</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-list-listname-viewname"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-list-listname-viewname_post"> - - <title><literal>POST /db/_design/design-doc/_list/list-name/view-name</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-list-listname-viewname"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-update-updatename-doc_put"> - - <title><literal>PUT /db/_design/design-doc/_update/updatename/doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" - condition="db-design-designdoc-update-updatename-doc"/> - - <remark role="method" condition="PUT"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section - id="couchdb-api-design_db-design-designdoc-update-updatename_post"> - - <title><literal>POST /db/_design/design-doc/_update/updatename</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" - condition="db-design-designdoc-update-updatename"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section - id="couchdb-api-design_db-design-designdoc-rewrite-rewritename-anything"> - - <title><literal>ALL - /db/_design/design-doc/_rewrite/rewrite-name/anything</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-design-designdoc-rewrite-rewritename-anything"/> - - <remark role="method" condition="ALL"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-introduction.xml b/share/docs/couchdb-manual-1.1/couchdb-api-introduction.xml deleted file mode 100644 index 714e5b0bb..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-api-introduction.xml +++ /dev/null @@ -1,851 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- -*- docbook-xml -*- --> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-basics"> - - <title>CouchDB API</title> - - <para> - 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. - </para> - - <para> - 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 <literal>GET</literal> operation, while updates are - handled by either a <literal>POST</literal> or - <literal>PUT</literal> 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 - <xref linkend="couchdb-api-introduction-requests"/>. - </para> - - <para> - 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 <xref linkend="couchdb-api-introduction-json"/>. - </para> - - <para> - 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 - <xref linkend="couchdb-api-introduction-returncodes"/>. - </para> - - <para> - 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 - <xref - linkend="couchdb-api-overview"/>. - </para> - - <section id="couchdb-api-introduction-requests"> - - <title>Request Format and Responses</title> - - <para> - CouchDB supports the following HTTP request methods: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>GET</literal> - </para> - - <para> - 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. - </para> - </listitem> - - <listitem> - <para> - <literal>HEAD</literal> - </para> - - <para> - The <literal>HEAD</literal> method is used to get the HTTP - header of a <literal>GET</literal> request without the body of - the response. - </para> - </listitem> - - <listitem> - <para> - <literal>POST</literal> - </para> - - <para> - Upload data. Within CouchDB <literal>POST</literal> is used to - set values, including uploading documents, setting document - values, and starting certain administration commands. - </para> - </listitem> - - <listitem> - <para> - <literal>PUT</literal> - </para> - - <para> - Used to put a specified resource. In CouchDB - <literal>PUT</literal> is used to create new objects, - including databases, documents, views and design documents. - </para> - </listitem> - - <listitem> - <para> - <literal>DELETE</literal> - </para> - - <para> - Deletes the specified resource, including documents, views, - and design documents. - </para> - </listitem> - - <listitem> - <para> - <literal>COPY</literal> - </para> - - <para> - A special method that can be used to copy documents and - objects. - </para> - </listitem> - - </itemizedlist> - - <para> - 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: - </para> - -<programlisting> -{ - "error":"method_not_allowed", - "reason":"Only GET,HEAD allowed" -} - </programlisting> - -<!-- TODO: Link should be updated when we look at HTML return object --> - - <para> - 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 <literal>headers</literal> - block of the return object. For more information, see - <xref linkend="couchdb-api-functional"/>. - </para> - - </section> - - <section id="couchdb-api-introduction-request-header"> - - <title>HTTP Headers</title> - - <para> - 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. - </para> - - <section id="couchdb-api-introduction-request-header-request"> - - <title>Request Headers</title> - - <itemizedlist> - - <listitem> - <para> - <literal>Content-type</literal> - </para> - - <para> - 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 (<literal>application/json</literal>). 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 - (<literal>application/octet-stream</literal>). - </para> - - <para> - The use of the <literal>Content-type</literal> on a request - is highly recommended. - </para> - </listitem> - - <listitem> - <para> - <literal>Accept</literal> - </para> - - <para> - 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. - </para> - - <para> - For the majority of requests the definition should be for - JSON data (<literal>application/json</literal>). For - attachments you can either specify the MIME type explicitly, - or use <literal>*/*</literal> to specify that all file types - are supported. If the <literal>Accept</literal> header is - not supplied, then the <literal>*/*</literal> MIME type is - assumed (i.e. client accepts all formats). - </para> - - <para> - The use of <literal>Accept</literal> 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. - </para> - - <para> - If you specify a data type using the - <literal>Accept</literal> header, CouchDB will honor the - specified type in the <literal>Content-type</literal> header - field returned. For example, if you explicitly request - <literal>application/json</literal> in the - <literal>Accept</literal> of a request, the returned HTTP - headers will use the value in the returned - <literal>Content-type</literal> field. - </para> - - <para> - For example, when sending a request without an explicit - <literal>Accept</literal> header, or when specifying - <literal>*/*</literal>: - </para> - -<programlisting> -GET /recipes HTTP/1.1 -Host: couchdb:5984 -Accept: */* -</programlisting> - - <para> - The returned headers are: - </para> - -<programlisting> -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 -</programlisting> - - <para> - Note that the returned content type is - <literal>text/plain</literal> even though the information - returned by the request is in JSON format. - </para> - - <para> - Explicitly specifying the <literal>Accept</literal> header: - </para> - -<programlisting> -GET /recipes HTTP/1.1 -Host: couchdb:5984 -Accept: application/json -</programlisting> - - <para> - The headers returned include the - <literal>application/json</literal> content type: - </para> - -<programlisting> -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 -</programlisting> - </listitem> - - </itemizedlist> - - </section> - - <section id="couchdb-api-introduction-request-header-response"> - - <title>Response Headers</title> - - <para> - 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. - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>Content-type</literal> - </para> - - <para> - Specifies the MIME type of the returned data. For most - request, the returned MIME type is - <literal>text/plain</literal>. All text is encoded in - Unicode (UTF-8), and this is explicitly stated in the - returned <literal>Content-type</literal>, as - <literal>text/plain;charset=utf-8</literal>. - </para> - </listitem> - - <listitem> - <para> - <literal>Cache-control</literal> - </para> - - <para> - The cache control HTTP response header provides a suggestion - for client caching mechanisms on how to treat the returned - information. CouchDB typically returns the - <literal>must-revalidate</literal>, 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. - </para> - </listitem> - - <listitem> - <para> - <literal>Content-length</literal> - </para> - - <para> - The length (in bytes) of the returned content. - </para> - </listitem> - - <listitem> - <para> - <literal>Etag</literal> - </para> - - <para> - The <literal>Etag</literal> HTTP header field is used to - show the revision for a document. - </para> - </listitem> - - </itemizedlist> - - </section> - - </section> - - <section id="couchdb-api-introduction-json"> - - <title>JSON Basics</title> - - <para> - 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. - </para> - - <para> - 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. - </para> - - <para> - JSON supports the same basic types as supported by JavaScript, - these are: - </para> - - <itemizedlist> - - <listitem> - <para> - Number (either integer or floating-point). - </para> - </listitem> - - <listitem> - <para> - String; this should be enclosed by double-quotes and supports - Unicode characters and backslash escaping. For example: - </para> - -<programlisting>"A String"</programlisting> - </listitem> - - <listitem> - <para> - Boolean - a <literal>true</literal> or - <literal>false</literal> value. You can use these strings - directly. For example: - </para> - -<programlisting>{ "value": true}</programlisting> - </listitem> - - <listitem> - <para> - Array - a list of values enclosed in square brackets. For - example: - </para> - -<programlisting>["one", "two", "three"]</programlisting> - </listitem> - - <listitem> - <para> - Object - a set of key/value pairs (i.e. an associative array, - or hash). The key must be a string, but the value can be any - of the supported JSON values. For example: - </para> - -<programlisting> -{ - "servings" : 4, - "subtitle" : "Easy to make in advance, and then cook when ready", - "cooktime" : 60, - "title" : "Chicken Coriander" -} - </programlisting> - - <para> - In CouchDB, the JSON object is used to represent a variety of - structures, including the main CouchDB document. - </para> - </listitem> - - </itemizedlist> - - <para> - Parsing JSON into a JavaScript object is supported through the - <literal>eval()</literal> function in JavaScript, or through - various libraries that will perform the parsing of the content - into a JavaScript object for you. Libraries for parsing and - generating JSON are available in many languages, including Perl, - Python, Ruby, Erlang and others. - </para> - - <warning> - <para> - Care should be taken to ensure that your JSON structures are - valid, invalid structures will cause CouchDB to return an HTTP - status code of 500 (server error). See - <xref - linkend="couchdb-api-introduction-returncode-500"/> - . - </para> - </warning> - - </section> - - <section id="couchdb-api-introduction-returncodes"> - - <title>HTTP Status Codes</title> - - <para> - With the interface to CouchDB working through HTTP, error codes - and statuses are reported using a combination of the HTTP status - code number, and corresponding data in the body of the response - data. - </para> - - <para> - A list of the error codes returned by CouchDB, and generic - descriptions of the related errors are provided below. The meaning - of different status codes for specific request types are provided - in the corresponding API call reference. - </para> - - <itemizedlist> - - <listitem> - <para id="couchdb-api-introduction-returncode-200"> - <literal>200 - OK</literal> - </para> - - <para> - Request completed successfully. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-201"> - <literal>201 - Created</literal> - </para> - - <para> - Document created successfully. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-202"> - <literal>202 - Accepted</literal> - </para> - - <para> - Request has been accepted, but the corresponding operation may - not have completed. This is used for background operations, - such as database compaction. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-304"> - <literal>304 - Not Modified</literal> - </para> - - <para> - The additional content requested has not been modified. This - is used with the ETag system to identify the version of - information returned. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-400"> - <literal>400 - Bad Request</literal> - </para> - - <para> - Bad request structure. The error can indicate an error with - the request URL, path or headers. Differences in the supplied - MD5 hash and content also trigger this error, as this may - indicate message corruption. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-401"> - <literal>401 - Unauthorized</literal> - </para> - - <para> - The item requested was not available using the supplied - authorization, or authorization was not supplied. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-403"> - <literal>403 - Forbidden</literal> - </para> - - <para> - The requested item or operation is forbidden. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-404"> - <literal>404 - Not Found</literal> - </para> - - <para> - The requested content could not be found. The content will - include further information, as a JSON object, if available. - The structure will contain two keys, <literal>error</literal> - and <literal>reason</literal>. For example: - </para> - -<programlisting>{"error":"not_found","reason":"no_db_file"}</programlisting> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-405"> - <literal>405 - Resource Not Allowed</literal> - </para> - - <para> - A request was made using an invalid HTTP request type for the - URL requested. For example, you have requested a - <literal>PUT</literal> when a <literal>POST</literal> is - required. Errors of this type can also triggered by invalid - URL strings. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-406"> - <literal>406 - Not Acceptable</literal> - </para> - - <para> - The requested content type is not supported by the server. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-409"> - <literal>409 - Conflict</literal> - </para> - - <para> - Request resulted in an update conflict. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-412"> - <literal>412 - Precondition Failed</literal> - </para> - - <para> - The request headers from the client and the capabilities of - the server do not match. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-415"> - <literal>415 - Bad Content Type</literal> - </para> - - <para> - The content types supported, and the content type of the - information being requested or submitted indicate that the - content type is not supported. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-416"> - <literal>416 - Requested Range Not Satisfiable</literal> - </para> - - <para> - The range specified in the request header cannot be satisfied - by the server. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-417"> - <literal>417 - Expectation Failed</literal> - </para> - - <para> - When sending documents in bulk, the bulk load operation - failed. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-500" xreflabel="HTTP - Status Code 500"> - <literal>500 - Internal Server Error</literal> - </para> - - <para> - The request was invalid, either because the supplied JSON was - invalid, or invalid information was supplied as part of the - request. - </para> - </listitem> - - </itemizedlist> - - </section> - - <section id="couchdb-api-overview"> - - <title>CouchDB API Overview</title> - - <para> - The components of the API URL path help determine the part of the - CouchDB server that is being accessed. The result is the structure - of the URL request both identifies and effectively describes the - area of the database you are accessing. - </para> - - <para> - As with all URLs, the individual components are separated by a - forward slash. - </para> - - <para> - As a general rule, URL components and JSON fields starting with - the <literal>_</literal> (underscore) character represent a - special component or entity within the server or returned object. - For example, the URL fragment <literal>/_all_dbs</literal> gets a - list of all of the databases in a CouchDB instance. - </para> - - <para> - The remainder of the URL API structure can be divided up according - to the URL structure. The different sections are divided as - follows: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>/db</literal> - </para> - - <para> - Database methods, related to adding, updating or deleting - databases, and setting database parameters and operations. For - more detailed information, see - <xref - linkend="couchdb-api-db"/> . - </para> - </listitem> - - <listitem> - <para> - <literal>/db/doc</literal> - </para> - - <para> - Document methods, those that create, store, update or delete - CouchDB documents and their attachments. For more information, - see <xref - linkend="couchdb-api-dbdoc"/>. - </para> - </listitem> - - <listitem> - <para> - <literal>/db/_local/local-doc</literal> - </para> - - <para> - Document methods, those that create, store, update or delete - CouchDB documents only within the local database. Local - documents are not synchronized with other databases. For more - information, see - <xref - linkend="couchdb-api-localdb"/>. - </para> - </listitem> - - <listitem> - <para> - <literal>/db/_design/design-doc</literal> - </para> - - <para> - Design documents provide the methods and structure for - recovering information from a CouchDB database in the form of - views, shows and lists. For more information, see - <xref - linkend="couchdb-api-design"/>. - </para> - </listitem> - - <listitem> - <para> - <literal>/_special</literal> - </para> - - <para> - Special methods that obtain or set information about the - CouchDB instance, including methods for configuring - replication, accessing the logs, and generate Universally - Unique IDs (UUIDs). For more information, see - <xref - linkend="couchdb-api-misc"/>. - </para> - </listitem> - - <listitem> - <para> - <literal>/_config</literal> - </para> - - <para> - Methods for getting, and settings, CouchDB configuration - parameters. For more information, see - <xref - linkend="couchdb-api-misc"/>. - </para> - </listitem> - - </itemizedlist> - -<!-- - Databases and Documents - - To see a listing of databases: - - /_all_dbs - To see some basic information about a database: - - /dbname/ - To see all a listing of the data documents in a database: - - /dbname/_all_docs - To see a document: - - /dbname/docid - To download a file attachment: - - /dbname/docid/filename - Design Documents and Views - - To see a design document: - - /dbname/_design/designdocname - To query a view. - - /dbname/_design/designdocname/_view/viewname?query - NOTE: Apparently the structure depends on the version #. In 0.8.1 the above doesn't work, but the below works: - JohnWarden - - /dbname/_view/designdocname/viewname?query - To query a temporary ("slow") view (with the custom view function in the body of the request): - - /dbname/_temp_view?query - Formatting - - To format a document through a "show" template: - - /dbname/_design/designdocname/_show/showname/docid - To format a view through a "list" template: - - /dbname/_design/designdocname/_list/listname/viewname?query - --> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-json-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-json-metasrc.xml deleted file mode 100644 index 7f8d86e93..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-api-json-metasrc.xml +++ /dev/null @@ -1,43 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE appendix PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<appendix id="couchdb-api-json"> - - <title>JSON Structure Reference</title> - - <para> - The following appendix provides a quick reference to all the JSON - structures that you can supply to CouchDB, or get in return to - requests. - </para> - - <para role="meta" id="table-couchdb-api-json-summary"> - <remark role="title">JSON Structures</remark> - - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="summarytable"/> - - <remark role="version" condition="inherit"/> - - <remark role="idprefix" condition="table-couchdb-api-json"/> - </para> - - <para role="meta"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="alltables"/> - - <remark role="version" condition="inherit"/> - - <remark role="idprefix" condition="table-couchdb-api-json"/> - </para> - -</appendix> diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-localdb-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-localdb-metasrc.xml deleted file mode 100644 index 6bbd0f016..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-api-localdb-metasrc.xml +++ /dev/null @@ -1,186 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-localdb"> - - <title>CouchDB API Server Local (non-replicating) Document Methods</title> - - <para> - The Local (non-replicating) document interface allows you to create - local documents that are not replicated to other databases. These - documents can be used to hold configuration or other information - that is required specifically on the local CouchDB instance. - </para> - - <para> - Local documents have the following limitations: - </para> - - <itemizedlist> - - <listitem> - <para> - Local documents are not replicated to other databases. - </para> - </listitem> - - <listitem> - <para> - The ID of the local document must be known for the document to - accessed. You cannot obtain a list of local documents from the - database. - </para> - </listitem> - - <listitem> - <para> - Local documents are not output by views, or the - <literal>_all_docs</literal> view. - </para> - </listitem> - - </itemizedlist> - - <para> - Local documents can be used when you want to store configuration or - other information for the curent (local) instance of a given - database. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <para role="meta" id="table-couchdb-api-localdb-summary"> - <remark role="title">Local (non-replicating) Document API - Calls</remark> - - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="summarytable"/> - - <remark role="filter_class" condition="localdb"/> - - <remark role="version" condition="inherit"/> - - <remark role="idprefix" condition="couchdb-api-localdb"/> - </para> - - <section id="couchdb-api-localdb_db-local-localdoc_get"> - - <title><literal>GET /db/_local/local-doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-local-localdoc"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Gets the specified local document. The semantics are identical to - accessing a standard document in the specified database, except - that the document is not replicated. See - <xref - linkend="couchdb-api-dbdoc_db-doc_get"/>. - </para> - - </section> - - <section id="couchdb-api-localdb_db-local-localdoc_put"> - - <title><literal>PUT /db/_local/local-doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-local-localdoc"/> - - <remark role="method" condition="PUT"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Stores the specified local document. The semantics are identical - to storing a standard document in the specified database, except - that the document is not replicated. See - <xref - linkend="couchdb-api-dbdoc_db-doc_put"/>. - </para> - - </section> - - <section id="couchdb-api-localdb_db-local-localdoc_delete"> - - <title><literal>DELETE /db/_local/local-doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-local-localdoc"/> - - <remark role="method" condition="DELETE"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Deletes the specified local document. The semantics are identical - to deleting a standard document in the specified database, except - that the document is not replicated. See - <xref - linkend="couchdb-api-dbdoc_db-doc_delete"/>. - </para> - - </section> - - <section id="couchdb-api-localdb_db-local-localdoc_copy"> - - <title><literal>COPY /db/_local/local-doc</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="db-local-localdoc"/> - - <remark role="method" condition="COPY"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Copies the specified local document. The semantics are identical - to copying a standard document in the specified database, except - that the document is not replicated. See - <xref - linkend="couchdb-api-dbdoc_db-doc_copy"/>. - </para> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-misc-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-misc-metasrc.xml deleted file mode 100644 index 200749fab..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-api-misc-metasrc.xml +++ /dev/null @@ -1,1357 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-misc"> - - <title>CouchDB API Server Miscellaneous Methods</title> - - <para> - The CouchDB Miscellaneous interface provides the basic interface to - a CouchDB server for obtaining CouchDB information and getting and - setting configuration information. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <para role="meta" id="table-couchdb-api-misc-summary"> - <remark role="title">Miscellaneous API Calls</remark> - - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="summarytable"/> - - <remark role="filter_class" condition="misc"/> - - <remark role="version" condition="inherit"/> - - <remark role="idprefix" condition="couchdb-api-misc"/> - </para> - - <section id="couchdb-api-misc_root_get"> - - <title><literal>GET /</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="root"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Accessing the root of a CouchDB instance returns meta information - about the instance. The response is a JSON structure containing - information about the server, including a welcome message and the - version of the server. - </para> - -<programlisting> -{ - "couchdb" : "Welcome", - "version" : "1.0.1" -} -</programlisting> - - </section> - - <section id="couchdb-api-misc_active-tasks_get"> - - <title><literal>GET /_active_tasks</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="active-tasks"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - You can obtain a list of active tasks by using the - <literal>/_active_tasks</literal> URL. The result is a JSON array - of the currently running tasks, with each task being described - with a single object. For example: - </para> - -<programlisting> - -<![CDATA[ -[ - { - "pid" : "<0.11599.0>", - "status" : "Copied 0 of 18369 changes (0%)", - "task" : "recipes", - "type" : "Database Compaction" - } -] -]]> - - </programlisting> - - <para> - The returned structure includes the following fields for each - task: - </para> - - <para role="meta" id="table-couchdb-api-misc-active-tasks-json"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="activetasks"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - For operation type, valid values include: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>Database Compaction</literal> - </para> - </listitem> - - <listitem> - <para> - <literal>Replication</literal> - </para> - </listitem> - - <listitem> - <para> - <literal>View Group Compaction</literal> - </para> - </listitem> - - <listitem> - <para> - <literal>View Group Indexer</literal> - </para> - </listitem> - - </itemizedlist> - - </section> - - <section id="couchdb-api-misc_all-dbs_get"> - - <title><literal>GET /_all_dbs</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="all-dbs"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Returns a list of all the databases in the CouchDB instance. For - example: - </para> - -<programlisting> -GET http://couchdb:5984/_all_dbs -Accept: application/json -</programlisting> - - <para> - The return is a JSON array: - </para> - -<programlisting> -[ - "_users", - "contacts", - "docs", - "invoices", - "locations" -] - -</programlisting> - - </section> - - <section id="couchdb-api-misc_log_get"> - - <title><literal>GET /_log</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="log"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Gets the CouchDB log, equivalent to accessing the local log file - of the corresponding CouchDB instance. - </para> - - <para> - When you request the log, the response is returned as plain - (UTF-8) text, with an HTTP <literal>Content-type</literal> header - as <literal>text/plain</literal>. - </para> - - <para> - For example, the request: - </para> - -<programlisting> -GET http://couchdb:5984/_log -Accept: */* -</programlisting> - - <para> - The raw text is returned: - </para> - -<programlisting> -<![CDATA[ -[Wed, 27 Oct 2010 10:49:42 GMT] [info] [<0.23338.2>] 192.168.0.2 - - 'PUT' /authdb 401 - -[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /recipes/FishStew 200 - -[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /_session 200 - -[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.24199.2>] 192.168.0.116 - - 'GET' / 200 - -[Wed, 27 Oct 2010 13:03:38 GMT] [info] [<0.24207.2>] 192.168.0.116 - - 'GET' /_log?offset=5 200 -]]> -</programlisting> - - <para> - If you want to pick out specific parts of the log information you - can use the <literal>bytes</literal> argument, which specifies the - number of bytes to be returned, and <literal>offset</literal>, - which specifies where the reading of the log should start, counted - back from the end. For example, if you use the following request: - </para> - -<programlisting> -GET /_log?bytes=500&offset=2000 -</programlisting> - - <para> - Reading of the log will start at 2000 bytes from the end of the - log, and 500 bytes will be shown. - </para> - - </section> - - <section id="couchdb-api-misc_replicate_post"> - - <title><literal>POST /_replicate</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="replicate"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Request, configure, or stop, a replication operation. - </para> - - <para> - The specification of the replication request is controlled through - the JSON content of the request. The JSON should be an object with - the fields defining the source, target and other options. The - fields of the JSON request are shown in the table below: - </para> - - <para role="meta" id="table-couchdb-api-misc-json-replication"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="replication"/> - - <remark role="version" condition="inherit"/> - </para> - - <section id="couchdb-api-misc_replicate_post-operation"> - - <title>Replication Operation</title> - - <para> - The aim of the replication is that at the end of the process, - all active documents on the source database are also in the - destination database and all documents that were deleted in the - source databases are also deleted (if they exist) on the - destination database. - </para> - - <para> - Replication can be described as either push or pull replication: - </para> - - <itemizedlist> - - <listitem> - <para> - <emphasis>Pull replication</emphasis> is where the - <literal>source</literal> is the remote CouchDB instance, - and the <literal>destination</literal> is the local - database. - </para> - - <para> - Pull replication is the most useful solution to use if your - source database has a permanent IP address, and your - destination (local) database may have a dynamically assigned - IP address (for example, through DHCP). This is particularly - important if you are replicating to a mobile or other device - from a central server. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Push replication</emphasis> is where the - <literal>source</literal> is a local database, and - <literal>destination</literal> is a remote database. - </para> - </listitem> - - </itemizedlist> - - </section> - - <section id="couchdb-api-misc_replicate_post-sourcetarget"> - - <title>Specifying the Source and Target Database</title> - - <para> - You must use the URL specification of the CouchDB database if - you want to perform replication in either of the following two - situations: - </para> - - <itemizedlist> - - <listitem> - <para> - Replication with a remote database (i.e. another instance of - CouchDB on the same host, or a different host) - </para> - </listitem> - - <listitem> - <para> - Replication with a database that requires authentication - </para> - </listitem> - - </itemizedlist> - - <para> - For example, to request replication between a database local to - the CouchDB instance to which you send the request, and a remote - database you might use the following request: - </para> - -<programlisting> -POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "source" : "recipes", - "target" : "http://coucdb-remote:5984/recipes", -} - </programlisting> - - <para> - In all cases, the requested databases in the - <literal>source</literal> and <literal>target</literal> - specification must exist. If they do not, an error will be - returned within the JSON object: - </para> - -<programlisting> -{ - "error" : "db_not_found" - "reason" : "could not open http://couchdb-remote:5984/ol1ka/", -} - </programlisting> - - <para> - You can create the target database (providing your user - credentials allow it) by adding the - <literal>create_target</literal> field to the request object: - </para> - -<programlisting> -POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "create_target" : true - "source" : "recipes", - "target" : "http://couchdb-remote:5984/recipes", -} -</programlisting> - - <para> - The <literal>create_target</literal> field is not destructive. - If the database already exists, the replication proceeds as - normal. - </para> - - </section> - - <section id="couchdb-api-misc_replicate_post-single"> - - <title>Single Replication</title> - - <para> - You can request replication of a database so that the two - databases can be synchronized. By default, the replication - process occurs one time and synchronizes the two databases - together. For example, you can request a single synchronization - between two databases by supplying the <literal>source</literal> - and <literal>target</literal> fields within the request JSON - content. - </para> - -<programlisting> -POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "source" : "recipes", - "target" : "recipes-snapshot", -} -</programlisting> - - <para> - In the above example, the databases <literal>recipes</literal> - and <literal>recipes-snapshot</literal> will be synchronized. - These databases are local to the CouchDB instance where the - request was made. The response will be a JSON structure - containing the success (or failure) of the synchronization - process, and statistics about the process: - </para> - -<programlisting> -{ - "ok" : true, - "history" : [ - { - "docs_read" : 1000, - "session_id" : "52c2370f5027043d286daca4de247db0", - "recorded_seq" : 1000, - "end_last_seq" : 1000, - "doc_write_failures" : 0, - "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT", - "start_last_seq" : 0, - "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT", - "missing_checked" : 0, - "docs_written" : 1000, - "missing_found" : 1000 - } - ], - "session_id" : "52c2370f5027043d286daca4de247db0", - "source_last_seq" : 1000 -} -</programlisting> - - <para> - The structure defines the replication status, as described in - the table below: - </para> - - <para role="meta" id="table-couchdb-api-misc-json-replication-status"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="replication-status"/> - - <remark role="version" condition="inherit"/> - </para> - - </section> - - <section id="couchdb-api-misc_replicate_post-continuous"> - - <title>Continuous Replication</title> - - <para> - Synchronization of a database with the previously noted methods - happens only once, at the time the replicate request is made. To - have the target database permanently replicated from the source, - you must set the <literal>continuous</literal> field of the JSON - object within the request to true. - </para> - - <para> - With continuous replication changes in the source database are - replicated to the target database in perpetuity until you - specifically request that replication ceases. - </para> - -<programlisting> -POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "continuous" : true - "source" : "recipes", - "target" : "http://couchdb-remote:5984/recipes", -} -</programlisting> - - <para> - Changes will be replicated between the two databases as long as - a network connection is available between the two instances. - </para> - - <note> - <para> - Two keep two databases synchronized with each other, you need - to set replication in both directions; that is, you must - replicate from <literal>databasea</literal> to - <literal>databaseb</literal>, and separately from - <literal>databaseb</literal> to <literal>databasea</literal>. - </para> - </note> - - </section> - - <section id="couchdb-api-misc_replicate_post-cancel"> - - <title>Canceling Continuous Replication</title> - - <para> - You can cancel continuous replication by adding the - <literal>cancel</literal> field to the JSON request object and - setting the value to true. Note that the structure of the - request must be identical to the original for the cancelation - request to be honoured. For example, if you requested continuous - replication, the cancellation request must also contain the - <literal>continuous</literal> field. - </para> - - <para> - For example, the replication request: - </para> - -<programlisting> -POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "source" : "recipes", - "target" : "http://couchdb-remote:5984/recipes", - "create_target" : true, - "continuous" : true -} -</programlisting> - - <para> - Must be canceled using the request: - </para> - -<programlisting> -POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "cancel" : true, - "continuous" : true - "create_target" : true, - "source" : "recipes", - "target" : "http://couchdb-remote:5984/recipes", -} -</programlisting> - - <para> - Requesting cancellation of a replication that does not exist - results in a 404 error. - </para> - - </section> - - </section> - - <section id="couchdb-api-misc_restart_post"> - - <title><literal>POST /_restart</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="restart"/> - - <remark role="method" condition="POST"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Restarts the CouchDB instance. You must be authenticated as a user - with administration privileges for this to work. - </para> - - <para> - For example: - </para> - -<programlisting> -POST http://admin:password@couchdb:5984/_restart -</programlisting> - - <para> - The return value (if the server has not already restarted) is a - JSON status object indicating that the request has been received: - </para> - -<programlisting> -{ - "ok" : true, -} -</programlisting> - - <para> - If the server has already restarted, the header may be returned, - but no actual data is contained in the response. - </para> - - </section> - - <section id="couchdb-api-misc_stats_get"> - - <title><literal>GET /_stats</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="stats"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - The <literal>_stats</literal> method returns a JSON object - containting the statistics for the running server. The object is - structured with top-level sections collating the statistics for a - range of entries, with each individual statistic being easily - identified, and the content of each statistic is self-describing. - For example, the request time statistics, within the - <literal>couchdb</literal> section are structured as follows: - </para> - -<programlisting> -{ - "couchdb" : { -... - "request_time" : { - "stddev" : "27.509", - "min" : "0.333333333333333", - "max" : "152", - "current" : "400.976", - "mean" : "10.837", - "sum" : "400.976", - "description" : "length of a request inside CouchDB without MochiWeb" - }, -... - } -} - </programlisting> - - <para> - The fields provide the current, minimum and maximum, and a - collection of statistical means and quantities. The quantity in - each case is not defined, but the descriptions below provide - </para> - - <para> - The statistics are divided into the following top-level sections: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>couchdb</literal> - </para> - - <para> - Describes statistics specific to the internals of CouchDB. - </para> - - <table> - <title><literal>couchdb</literal> statistics</title> - <tgroup cols="3"> - <colspec colname="stat"/> - <colspec colname="desc"/> - <colspec colname="unit"/> - <thead> - <row> - <entry> - Statistic ID - </entry> - <entry> - Description - </entry> - <entry> - Unit - </entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>auth_cache_hits</literal> - </entry> - <entry> - Number of authentication cache hits - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>auth_cache_misses</literal> - </entry> - <entry> - Number of authentication cache misses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>database_reads</literal> - </entry> - <entry> - Number of times a document was read from a database - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>database_writes</literal> - </entry> - <entry> - Number of times a database was changed - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>open_databases</literal> - </entry> - <entry> - Number of open databases - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>open_os_files</literal> - </entry> - <entry> - Number of file descriptors CouchDB has open - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>request_time</literal> - </entry> - <entry> - Length of a request inside CouchDB without MochiWeb - </entry> - <entry> - milliseconds - </entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - - <listitem> - <para> - <literal>httpd_request_methods</literal> - </para> - - <table> - <title><literal>httpd_request_methods</literal> statistics</title> - <tgroup cols="3"> - <colspec colname="stat"/> - <colspec colname="desc"/> - <colspec colname="unit"/> - <thead> - <row> - <entry> - Statistic ID - </entry> - <entry> - Description - </entry> - <entry> - Unit - </entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>COPY</literal> - </entry> - <entry> - Number of HTTP COPY requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>DELETE</literal> - </entry> - <entry> - Number of HTTP DELETE requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>GET</literal> - </entry> - <entry> - Number of HTTP GET requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>HEAD</literal> - </entry> - <entry> - Number of HTTP HEAD requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>POST</literal> - </entry> - <entry> - Number of HTTP POST requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>PUT</literal> - </entry> - <entry> - Number of HTTP PUT requests - </entry> - <entry> - number - </entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - - <listitem> - <para> - <literal>httpd_status_codes</literal> - </para> - - <table> - <title><literal>httpd_status_codes</literal> statistics</title> - <tgroup cols="3"> - <colspec colname="stat"/> - <colspec colname="desc"/> - <colspec colname="unit"/> - <thead> - <row> - <entry> - Statistic ID - </entry> - <entry> - Description - </entry> - <entry> - Unit - </entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>200</literal> - </entry> - <entry> - Number of HTTP 200 OK responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>201</literal> - </entry> - <entry> - Number of HTTP 201 Created responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>202</literal> - </entry> - <entry> - Number of HTTP 202 Accepted responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>301</literal> - </entry> - <entry> - Number of HTTP 301 Moved Permanently responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>304</literal> - </entry> - <entry> - Number of HTTP 304 Not Modified responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>400</literal> - </entry> - <entry> - Number of HTTP 400 Bad Request responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>401</literal> - </entry> - <entry> - Number of HTTP 401 Unauthorized responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>403</literal> - </entry> - <entry> - Number of HTTP 403 Forbidden responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>404</literal> - </entry> - <entry> - Number of HTTP 404 Not Found responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>405</literal> - </entry> - <entry> - Number of HTTP 405 Method Not Allowed responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>409</literal> - </entry> - <entry> - Number of HTTP 409 Conflict responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>412</literal> - </entry> - <entry> - Number of HTTP 412 Precondition Failed responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>500</literal> - </entry> - <entry> - Number of HTTP 500 Internal Server Error responses - </entry> - <entry> - number - </entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - - <listitem> - <para> - <literal>httpd</literal> - </para> - - <table> - <title><literal>httpd</literal> statistics</title> - <tgroup cols="3"> - <colspec colname="stat"/> - <colspec colname="desc"/> - <colspec colname="unit"/> - <thead> - <row> - <entry> - Statistic ID - </entry> - <entry> - Description - </entry> - <entry> - Unit - </entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>bulk_requests</literal> - </entry> - <entry> - Number of bulk requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>clients_requesting_changes</literal> - </entry> - <entry> - Number of clients for continuous _changes - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>requests</literal> - </entry> - <entry> - Number of HTTP requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>temporary_view_reads</literal> - </entry> - <entry> - Number of temporary view reads - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>view_reads</literal> - </entry> - <entry> - Number of view reads - </entry> - <entry> - number - </entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - - </itemizedlist> - - <para> - You can also access individual statistics by quoting the - statistics sections and statistic ID as part of the URL path. For - example, to get the <literal>request_time</literal> statistics, - you can use: - </para> - -<programlisting> -GET /_stats/couchdb/request_time - </programlisting> - - <para> - This returns an entire statistics object, as with the full - request, but containining only the request individual statistic. - Hence, the returned structure is as follows: - </para> - -<programlisting> -{ - "couchdb" : { - "request_time" : { - "stddev" : 7454.305, - "min" : 1, - "max" : 34185, - "current" : 34697.803, - "mean" : 1652.276, - "sum" : 34697.803, - "description" : "length of a request inside CouchDB without MochiWeb" - } - } -} - </programlisting> - - </section> - - <section id="couchdb-api-misc_utils_get"> - - <title><literal>GET /_utils</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="utils"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Accesses the built-in Futon administration interface for CouchDB. - </para> - - </section> - - <section id="couchdb-api-misc_uuids_get"> - - <title><literal>GET /_uuids</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="uuids"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Requests one or more Universally Unique Identifiers (UUIDs) from - the CouchDB instance. The response is a JSON object providing a - list of UUIDs. For example: - </para> - -<programlisting> -{ - "uuids" : [ - "7e4b5a14b22ec1cf8e58b9cdd0000da3" - ] -} -</programlisting> - - <para> - You can use the <literal>count</literal> argument to specify the - number of UUIDs to be returned. For example: - </para> - -<programlisting> - GET http://couchdb:5984/_uuids?count=5 -</programlisting> - - <para> - Returns: - </para> - -<programlisting> -{ - "uuids" : [ - "c9df0cdf4442f993fc5570225b405a80", - "c9df0cdf4442f993fc5570225b405bd2", - "c9df0cdf4442f993fc5570225b405e42", - "c9df0cdf4442f993fc5570225b4061a0", - "c9df0cdf4442f993fc5570225b406a20" - ] -} -</programlisting> - - <para> - The UUID type is determined by the UUID type setting in the - CouchDB configuration. See - <xref linkend="couchdb-api-config_config-section-key_put"/>. - </para> - - <para> - For example, changing the UUID type to <literal>random</literal>: - </para> - -<programlisting> -PUT http://couchdb:5984/_config/uuids/algorithm -Content-Type: application/json -Accept: */* - -"random" -</programlisting> - - <para> - When obtaining a list of UUIDs: - </para> - -<programlisting> -{ - "uuids" : [ - "031aad7b469956cf2826fcb2a9260492", - "6ec875e15e6b385120938df18ee8e496", - "cff9e881516483911aa2f0e98949092d", - "b89d37509d39dd712546f9510d4a9271", - "2e0dbf7f6c4ad716f21938a016e4e59f" - ] -} -</programlisting> - - </section> - - <section id="couchdb-api-misc_favicon_get"> - - <title><literal>GET /favicon.ico</literal></title> - - <para role="meta"> - <remark role="type" condition="urlapi"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="accesstable"/> - - <remark role="itemid" condition="favicon"/> - - <remark role="method" condition="GET"/> - - <remark role="version" condition="inherit"/> - </para> - - <para> - Returns the site icon. The return <literal>Content-type</literal> - header is <literal>image/x-icon</literal>, and the content stream - is the image data. - </para> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/couchdb-changes-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-changes-metasrc.xml deleted file mode 100644 index 338748600..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-changes-metasrc.xml +++ /dev/null @@ -1,67 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-single-changes"> - - <title>Changes Feed</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-changes-json-changes"> - <remark role="type" condition="json"/> - - <remark role="src" condition="json"/> - - <remark role="output" condition="itemtable"/> - - <remark role="itemid" condition="changes"/> - - <remark role="version" condition="inherit"/> - </para> - - <section id="couchdb-single-changes-poll"> - - <title>Polling</title> - - <para> - - </para> - - </section> - - <section id="couchdb-single-changes-longpoll"> - - <title>Long Polling</title> - - <para> - - </para> - - </section> - - <section id="couchdb-single-changes-continuous"> - - <title>Continuous</title> - - <para> - - </para> - - </section> - - <section id="couchdb-single-changes-filters"> - - <title>Filters</title> - - <para> - - </para> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/couchdb-config-options-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-config-options-metasrc.xml deleted file mode 100644 index d8a5fa538..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-config-options-metasrc.xml +++ /dev/null @@ -1,393 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE section PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<section id="couchdb-single-config-options"> - - <title>CouchDB Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="classsummarytable"/> - - <remark role="version" condition="1.0"/> - -<!-- <remark role="idprefix" condition="config-couchdb-options"/>--> - </para> - - <section id="couchdb-single-config-options_attachments"> - - <title><literal>attachments</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-attachments-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="attachments"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_attachments"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_couchdb"> - - <title><literal>couchdb</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-couchdb-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="couchdb"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_couchdb"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_daemons"> - - <title><literal>daemons</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-daemons-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="daemons"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_daemons"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_httpd_db_handlers"> - - <title><literal>httpd_db_handlers</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-httpd_db_handlers-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="httpd_db_handlers"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_httpd_db_handlers"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_couch_httpd_auth"> - - <title><literal>couch_httpd_auth</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-couch_httpd_auth-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="couch_httpd_auth"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_couch_httpd_auth"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_httpd"> - - <title><literal>httpd</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-httpd-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="httpd"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_httpd"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_httpd_design_handlers"> - - <title><literal>httpd_design_handlers</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-httpd_design_handlers-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="httpd_design_handlers"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_httpd_design_handlers"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_httpd_global_handlers"> - - <title><literal>httpd_global_handlers</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-httpd_global_handlers-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="httpd_global_handlers"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_httpd_global_handlers"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_log"> - - <title><literal>log</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-log-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="log"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_log"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_query_servers"> - - <title><literal>query_servers</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-query_servers-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="query_servers"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_query_servers"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_query_server_config"> - - <title><literal>query_server_config</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-query_server_config-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="query_server_config"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_query_server_config"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_replicator"> - - <title><literal>replicator</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-replicator-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="replicator"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_replicator"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_stats"> - - <title><literal>stats</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-stats-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="stats"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_stats"/> --> - </para> - - </section> - - <section id="couchdb-single-config-options_uuids"> - - <title><literal>uuids</literal> Configuration Options</title> - - <para> - - </para> - - <para role="meta" id="table-couchdb-single-config-options-uuids-summary"> - <remark role="title">Configuration Groups</remark> - - <remark role="type" condition="config"/> - - <remark role="src" condition="couchdb"/> - - <remark role="output" condition="optionsummarytable"/> - - <remark role="version" condition="1.0"/> - - <remark role="itemid" condition="uuids"/> - -<!-- <remark role="idprefix" condition="couchdb-single-config-options_uuids"/> --> - </para> - - </section> - -</section> diff --git a/share/docs/couchdb-manual-1.1/couchdb-configuration.xml b/share/docs/couchdb-manual-1.1/couchdb-configuration.xml deleted file mode 100644 index ef1fd2b3c..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-configuration.xml +++ /dev/null @@ -1,328 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'> -<chapter id="couchdb-single-configuration"> - - <title>Configuring CouchDB</title> - - <para> - - </para> - - <section id="couchdb-single-configuration-files"> - - <title>CouchDB Configuration Files</title> - - <para> - - </para> - - </section> - - <section id="couchdb-single-configuration-files-locations"> - - <title>Configuration File Locations</title> - - <para> - CouchDB reads files from the following locations, in the following - order. - </para> - - <orderedlist> - - <listitem> - <para> - <filename>PREFIX/default.ini</filename> - </para> - </listitem> - - <listitem> - <para> - <filename>PREFIX/default.d/*</filename> - </para> - </listitem> - - <listitem> - <para> - <filename>PREFIX/local.ini</filename> - </para> - </listitem> - - <listitem> - <para> - <filename>PREFIX/local.d/*</filename> - </para> - </listitem> - - </orderedlist> - - <para> - Settings in successive documents override the settings in earlier - entries. For example, setting the <literal>bind_address</literal> - parameter in <filename>local.ini</filename> would override any - setting in <literal>default.ini</literal>. - </para> - - <warning> - <para> - The <filename>default.ini</filename> file may be overwritten - during an upgrade or re-installation, so localised changes - should be made to the <filename>local.ini</filename> file or - files within the <filename>local.d</filename> directory. - </para> - </warning> - - </section> - - <section id="couchdb-single-configuration-mochiweb"> - - <title>MochiWeb Server Options</title> - - <para> - Server options for the MochiWeb component of CouchDB can be added - to the configuration files. Settings should be added to the - <literal>server_options</literal> option of the - <literal>[httpd]</literal> section of - <filename>local.ini</filename>. For example: - </para> - -<programlisting> -[httpd] -server_options = [{backlog, 128}, {acceptor_pool_size, 16}] - </programlisting> - - </section> - - <section id="couchdb-single-configuration-osprocess"> - - <title>OS Daemons</title> - - <para> - CouchDB now supports starting external processes. The support is - simple and enables CouchDB to start each configured OS daemon. If - the daemon stops at any point, CouchDB will restart it (with - protection to ensure regularly failing daemons are not repeatedly - restarted). - </para> - - <para> - The daemon starting process is one-to-one; for each each - configured daemon in the configuration file, CouchDB will start - exactly one instance. If you need to run multiple instances, then - you must create separate individual configurations. Daemons are - configured within the <literal>[os_daemons]</literal> section of - your configuration file (<filename>local.ini</filename>). The - format of each configured daemon is: - </para> - -<programlisting> -NAME = PATH ARGS - </programlisting> - - <para> - Where <literal>NAME</literal> is an arbitrary (and unique) name to - identify the daemon; <literal>PATH</literal> is the full path to - the daemon to be executed; <literal>ARGS</literal> are any - required arguments to the daemon. - </para> - - <para> - For example: - </para> - -<programlisting> -[os_daemons] -basic_responder = /usr/local/bin/responsder.js -</programlisting> - - <para> - There is no interactivity between CouchDB and the running process, - but you can use the OS Daemons service to create new HTTP servers - and responders and then use the new proxy service to redirect - requests and output to the CouchDB managed service. For more - information on proxying, see - <xref - linkend="couchdb-single-features-proxying"/>. For - further background on the OS Daemon service, see - <ulink url="http://davispj.com/2010/09/26/new-couchdb-externals-api.html">CouchDB - Externals API</ulink> - </para> - - </section> - - <section id="couchdb-single-configuration-update_notification"> - - <title>Update Notifications</title> - - <para> - - </para> - - </section> - - <section id="couchdb-single-configuration-socketoptions"> - - <title>Socket Options Configuration Setting</title> - - <para> - The socket options for the listening socket in CouchDB can now be - set within the CouchDB configuration file. The setting should be - added to the <literal>[httpd]</literal> section of the file using - the option name <literal>socket_options</literal>. The - specification is as a list of tuples. For example: - </para> - -<programlisting> -[httpd] -socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}] -</programlisting> - - <para> - The options supported are a subset of full options supported by - the TCP/IP stack. A list of the supported options are provided in - the - <ulink - url="http://www.erlang.org/doc/man/inet.html#setopts-2">Erlang - inet</ulink> documentation. - </para> - - </section> - - <section id="couchdb-single-configuration-vhost"> - - <title><literal>vhosts</literal> definitions</title> - - <para> - Similar to the rewrites section of a <literal>_design</literal> - document, the <literal>vhosts</literal> system uses variables in - the form of :varname or wildcards in the form of asterisks. The - variable results can be output into the resulting path as they are - in the rewriter. - </para> - - </section> - - <section id="couchdb-single-configuration-ssl"> - - <title>Configuring SSL Network Sockets</title> - - <para> - SSL configuration in CouchDB was designed to be as easy as - possible. All you need is two files; a certificate and a private - key. If you bought an official SSL certificate from a certificate - authority, both should be in your possession already. - </para> - - <para> - If you just want to try this out and don't want to pay anything - upfront, you can create a self-signed certificate. Everything will - work the same, but clients will get a warning about an insecure - certificate. - </para> - - <para> - You will need the OpenSSL command line tool installed. It probably - already is. - </para> - -<programlisting> -shell> <userinput>mkdir cert && cd cert</userinput> -shell> <userinput>openssl genrsa > privkey.pem</userinput> -shell> <userinput>openssl req -new -x509 -key privkey.pem -out mycert.pem -days 1095</userinput> -shell> <userinput>ls</userinput> -mycert.pem privkey.pem -</programlisting> - - <para> - Now, you need to edit CouchDB's configuration, either by editing - your <filename>local.ini</filename> file or using the - <literal>/_config</literal> API calls or the configuration screen - in Futon. Here is what you need to do in - <filename>local.ini</filename>, you can infer what needs doing in - the other places. - </para> - - <para> - Be sure to make these edits. Under <literal>[daemons]</literal> - you should see: - </para> - -<programlisting> -; enable SSL support by uncommenting the following line and supply the PEM's below. -; the default ssl port CouchDB listens on is 6984 -;httpsd = {couch_httpd, start_link, [https]} -</programlisting> - - <para> - Here uncomment the last line: - </para> - -<programlisting> -httpsd = {couch_httpd, start_link, [https]} -</programlisting> - - <para> - Next, under <literal>[ssl]</literal> you will see: - </para> - -<programlisting> -;cert_file = /full/path/to/server_cert.pem -;key_file = /full/path/to/server_key.pem -</programlisting> - - <para> - Uncomment and adjust the paths so it matches your system's paths: - </para> - -<programlisting> -cert_file = /home/jan/cert/mycert.pem -key_file = /home/jan/cert/privkey.pem -</programlisting> - - <para> - For more information please read - <ulink - url="http://www.openssl.org/docs/HOWTO/certificates.txt">http://www.openssl.org/docs/HOWTO/certificates.txt</ulink>. - </para> - - <para> - Now start (or restart) CouchDB. You should be able to connect to - it using HTTPS on port 6984: - </para> - -<programlisting> -shell> <userinput>curl https://127.0.0.1:6984/</userinput> -curl: (60) SSL certificate problem, verify that the CA cert is OK. Details: -error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed -More details here: http://curl.haxx.se/docs/sslcerts.html - -curl performs SSL certificate verification by default, using a "bundle" -of Certificate Authority (CA) public keys (CA certs). If the default -bundle file isn't adequate, you can specify an alternate file -using the --cacert option. -If this HTTPS server uses a certificate signed by a CA represented in -the bundle, the certificate verification probably failed due to a -problem with the certificate (it might be expired, or the name might -not match the domain name in the URL). -If you'd like to turn off curl's verification of the certificate, use -the -k (or --insecure) option. -</programlisting> - - <para> - Oh no what happened?! — Remember, clients will notify their - users that your certificate is self signed. - <command>curl</command> is the client in this case and it notifies - you. Luckily you trust yourself (don't you?) and you can specify - the <option>-k</option> option as the message reads: - </para> - -<programlisting> -shell> <userinput>curl -k https://127.0.0.1:6984/</userinput> -{"couchdb":"Welcome","version":"1.1.0"} -</programlisting> - - </section> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="metadoc-couchdb-config-options.xml"/> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/couchdb-dbmaint.xml b/share/docs/couchdb-manual-1.1/couchdb-dbmaint.xml deleted file mode 100644 index bdd4184a0..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-dbmaint.xml +++ /dev/null @@ -1,15 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-single-dbmaint"> - - <title>Database Maintenance</title> - - <para> - - </para> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/couchdb-features.xml b/share/docs/couchdb-manual-1.1/couchdb-features.xml deleted file mode 100644 index 3c7edc39f..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-features.xml +++ /dev/null @@ -1,301 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-single-features"> - - <title>Features and Functionality</title> - - <para> - - </para> - - <section id="couchdb-single-features-httprange"> - - <title>HTTP Range Requests</title> - - <para> - HTTP allows you to specify byte ranges for requests. This allows - the implementation of resumable downloads and skippable audio and - video streams alike. The following example uses a text file to - make the range request process easier. - </para> - -<programlisting> -shell> <userinput>cat file.txt</userinput> -My hovercraft is full of eels! -</programlisting> - - <para> - Uploading this as an attachment to a <literal>text</literal> - database using <command>curl</command>: - </para> - -<programlisting> -shell> <userinput>curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \ - -H "Content-Type: application/octet-stream" -d@file.txt</userinput> -{"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"} -</programlisting> - - <para> - Requesting the whole file works as normal: - </para> - -<programlisting> -shell> <userinput>curl -X GET http://127.0.0.1:5984/test/doc/file.txt</userinput> -My hovercraft is full of eels! -</programlisting> - - <para> - But to retrieve only the first 13 bytes using - <command>curl</command>: - </para> - -<programlisting> -shell> <userinput>curl -X GET http://127.0.0.1:5984/test/doc/file.txt -H "Range: bytes=0-12"</userinput> -My hovercraft -</programlisting> - - <para> - HTTP supports many ways to specify single and even multiple byte - rangers. See - <ulink - url="http://tools.ietf.org/html/rfc2616#section-14.27">RFC - 2616</ulink>. - </para> - - <note> - <para> - Databases that have been created with CouchDB 1.0.2 or earlier - will support range requests in 1.1.0, but they are using a - less-optimal algorithm. If you plan to make heavy use of this - feature, make sure to compact your database with CouchDB 1.1.0 - to take advantage of a better algorithm to find byte ranges. - </para> - </note> - - </section> - - <section id="couchdb-single-features-proxying"> - - <title>HTTP Proxying</title> - - <para> - The HTTP proxy feature makes it easy to map and redirect different - content through your CouchDB URL. The proxy works by mapping a - pathname and passing all content after that prefix through to the - configured proxy address. - </para> - - <para> - Configuration of the proxy redirect is handled through the - <literal>[httpd_global_handlers]</literal> section of the CouchDB - configuration file (typically <filename>local.ini</filename>). The - format is: - </para> - -<programlisting> -[httpd_global_handlers] -PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>} - </programlisting> - - <para> - Where: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>PREFIX</literal> - </para> - - <para> - Is the string that will be matched. The string can be any - valid qualifier, although to ensure that existing database - names are not overridden by a proxy configuration, you can use - an underscore prefix. - </para> - </listitem> - - <listitem> - <para> - <literal>DESTINATION</literal> - </para> - - <para> - The fully-qualified URL to which the request should be sent. - The destination must include the <literal>http</literal> - prefix. The content is used verbatim in the original request, - so you can also forward to servers on different ports and to - specific paths on the target host. - </para> - </listitem> - - </itemizedlist> - - <para> - The proxy process then translates requests of the form: - </para> - -<programlisting> -http://couchdb:5984/PREFIX/path -</programlisting> - - <para> - To: - </para> - -<programlisting> -DESTINATION/path -</programlisting> - - <note> - <para> - Everything after <literal>PREFIX</literal> including the - required forward slash will be appended to the - <literal>DESTINATION</literal>. - </para> - </note> - - <para> - The response is then communicated back to the original client. - </para> - - <para> - For example, the following configuration: - </para> - -<programlisting> -<![CDATA[ -_google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>}]]> -</programlisting> - - <para> - Would forward all requests for - <literal>http://couchdb:5984/_google</literal> to the Google - website. - </para> - - <para> - The service can also be used to forward to related CouchDB - services, such as Lucene: - </para> - -<programlisting> - <![CDATA[ -[httpd_global_handlers] -_fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}]]> -</programlisting> - - <note> - <para> - The proxy service is basic. If the request is not identified by - the <literal>DESTINATION</literal>, or the remainder of the - <literal>PATH</literal> specification is incomplete, the - original request URL is interpreted as if the - <literal>PREFIX</literal> component of that URL does not exist. - </para> - - <para> - For example, requesting - <literal>http://couchdb:5984/_intranet/media</literal> when - <filename>/media</filename> on the proxy destination does not - exist, will cause the request URL to be interpreted as - <literal>http://couchdb:5984/media</literal>. Care should be - taken to ensure that both requested URLs and destination URLs - are able to cope - </para> - </note> - - </section> - - <section id="couchdb-single-features-commonjs"> - - <title>CommonJS support for map functions</title> - - <para> - CommonJS support allows you to use CommonJS notation inside - <methodname>map</methodname> and <methodname>reduce</methodname> - functions, but only of libraries that are stored inside the views - part of the design doc. - </para> - - <para> - So you could continue to access CommonJS code in design_doc.foo, - from your list functions etc, but we'd add the ability to require - CommonJS modules within map and reduce, but only from - <filename>design_doc.views.lib</filename>. - </para> - - <para> - There's no worry here about namespace collisions, as Couch just - plucks <literal>views.*.map</literal> and - <literal>views.*.reduce</literal> out of the design doc. So you - could have a view called <literal>lib</literal> if you wanted, and - still have CommonJS stored in <literal>views.lib.sha1</literal> - and <literal>views.lib.stemmer</literal> if you wanted. - </para> - - <para> - The implementation is simplified by enforcing that CommonJS - modules to be used in <methodname>map</methodname> functions be - stored in views.lib. - </para> - - <para> - A sample design doc (taken from the test suite in Futon) is below: - </para> - -<programlisting> -{ - "views" : { - "lib" : { - "baz" : "exports.baz = 'bam';", - "foo" : { - "zoom" : "exports.zoom = 'yeah';", - "boom" : "exports.boom = 'ok';", - "foo" : "exports.foo = 'bar';" - } - }, - "commonjs" : { - "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}" - } - }, - "_id" : "_design/test" -} -</programlisting> - - <para> - The <literal>require()</literal> statement is relative to the - design document, but anything loaded form outside of - <literal>views/lib</literal> will fail. - </para> - - </section> - - <section id="couchdb-single-features-etag"> - - <title>Granular ETag support</title> - - <para> - ETags have been assigned to a map/reduce group (the collection of - views in a single design document). Any change to any of the - indexes for those views would generate a new ETag for all view - URL's in a single design doc, even if that specific view's results - had not changed. - </para> - - <para> - In CouchDB 1.1 each <literal>_view</literal> URL has it's own ETag - which only gets updated when changes are made to the database that - effect that index. If the index for that specific view does not - change, that view keeps the original ETag head (therefore sending - back 304 Not Modified more often). - </para> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/couchdb-introduction.xml b/share/docs/couchdb-manual-1.1/couchdb-introduction.xml deleted file mode 100644 index 15c123bc9..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-introduction.xml +++ /dev/null @@ -1,578 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-single-introduction"> - - <title>Introduction</title> - - <para> - There are two interfaces to CouchDB, the built-in - Futon web-based interface and the CouchDB API accessed through the - HTTP REST interface. The former is the simplest way to view and - monitor your CouchDB installation and perform a - number of basic database and system operations. More information on - using the Futon interface can be found in - <xref linkend="couchdb-single-introduction-futon"/>. - </para> - - <para> - The primary way to interact with the CouchDB API is to use a client - library or other interface that provides access to the underlying - functionality through your chosen language or platform. However, - since the API is supported through HTTP REST, you can interact with - your CouchDB with any solution that supports the - HTTP protocol. - </para> - - <para> - There are a number of different tools that talk the HTTP protocol - and allow you to set and configure the necessary information. One - tool for this that allows for access from the command-line is - <command>curl</command>. See - <xref - linkend="couchdb-single-introduction-curl"/>. - </para> - - <section id="couchdb-single-introduction-futon"> - - <title>Using Futon</title> - - <para> - Futon is a native web-based interface built into CouchDB. It provides a basic interface to the majority of the - functionality, including the ability to create, update, delete and - view documents and views, provides access to the configuration - parameters, and an interface for initiating replication. - </para> - - <para> - The default view is the <guilabel>Overview</guilabel> page which - provides you with a list of the databases. The basic structure of - the page is consistent regardless of the section you are in. The - main panel on the left provides the main interface to the - databases, configuration or replication systems. The side panel on - the right provides navigation to the main areas of Futon - interface: - </para> - - <figure id="fig-ccouchdb-single-introduction-futon-overview"> - - <title>Futon Overview</title> - - <mediaobject> - - <imageobject> - - <imagedata width="100%" contentdepth="100%" scalefit="1" -fileref="images/futon-overview.png" -format="PNG" lang="en"/> - - </imageobject> - - <textobject> - - <phrase lang="en">Futon Overview</phrase> - - </textobject> - - </mediaobject> - - </figure> - - <para> - The main sections are: - </para> - - <itemizedlist> - - <listitem> - <para> - <guibutton>Overview</guibutton> - </para> - - <para> - The main overview page, which provides a list of the databases - and provides the interface for querying the database and - creating and updating documents. See - <xref - linkend="couchdb-single-introduction-futon-dbdocs"/>. - </para> - </listitem> - - <listitem> - <para> - <guibutton>Configuration</guibutton> - </para> - - <para> - An interface into the configuration of your CouchDB installation. The interface allows you to edit the - different configurable parameters. For more details on - configuration, see - <xref - linkend="couchdb-single-configuration"/>. - </para> - </listitem> - - <listitem> - <para> - <guibutton>Replicator</guibutton> - </para> - - <para> - An interface to the replication system, enabling you to - initiate replication between local and remote databases. See - <xref - linkend="couchdb-single-introduction-futon-replication"/>. - </para> - </listitem> - - <listitem> - <para> - <guibutton>Status</guibutton> - </para> - - <para> - Displays a list of the running background tasks on the server. - Background tasks include view index building, compaction and - replication. The <guibutton>Status</guibutton> page is an - interface to the - <link linkend="couchdb-api-misc_active-tasks_get">Active - Tasks</link> API call. See - <xref - linkend="couchdb-api-misc_active-tasks_get"/>. - </para> - </listitem> - - <listitem> - <para> - <guibutton>Verify Installation</guibutton> - </para> - - <para> - The <guibutton>Verify Installation</guibutton> allows you to - check whether all of the components of your CouchDB installation are correctly installed. - </para> - </listitem> - - <listitem> - <para> - <guibutton>Test Suite</guibutton> - </para> - - <para> - The <guibutton>Test Suite</guibutton> section allows you to - run the built-in test suite. This executes a number of test - routines entirely within your browser to test the API and - functionality of your CouchDB installation. If - you select this page, you can run the tests by using the - <guibutton>Run All</guibutton> button. This will execute all - the tests, which may take some time. - </para> - </listitem> - - </itemizedlist> - - <section id="couchdb-single-introduction-futon-dbdocs"> - - <title>Managing Databases and Documents</title> - - <para> - You can manage databases and documents within Futon using the - main <guibutton>Overview</guibutton> section of the Futon - interface. - </para> - - <para> - To create a new database, click the <guibutton>Create Database - &ellipsis;</guibutton> button. You will be prompted for the - database name, as shown in the figure below. - </para> - - <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-createdb"> - - <title>Creating a Database</title> - - <mediaobject> - - <imageobject> - - <imagedata width="100%" contentdepth="100%" scalefit="1" -fileref="images/futon-createdb.png" -format="PNG" lang="en"/> - - </imageobject> - - <textobject> - - <phrase lang="en">Creating a Database</phrase> - - </textobject> - - </mediaobject> - - </figure> - - <para> - Once you have created the database (or selected an existing - one), you will be shown a list of the current documents. If you - create a new document, or select an existing document, you will - be presented with the edit document display. - </para> - - <para> - Editing documents within Futon requires selecting the document - and then editing (and setting) the fields for the document - individually before saving the document back into the database. - </para> - - <para> - For example, the figure below shows the editor for a single - document, a newly created document with a single ID, the - document <literal>_id</literal> field. - </para> - - <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-editdoc"> - - <title>Editing a Document</title> - - <mediaobject> - - <imageobject> - - <imagedata width="100%" contentdepth="100%" scalefit="1" -fileref="images/futon-editdoc.png" -format="PNG" lang="en"/> - - </imageobject> - - <textobject> - - <phrase lang="en">Editing a Document</phrase> - - </textobject> - - </mediaobject> - - </figure> - - <para> - To add a field to the document: - </para> - - <orderedlist> - - <listitem> - <para> - Click <guibutton>Add Field</guibutton>. - </para> - </listitem> - - <listitem> - <para> - In the fieldname box, enter the name of the field you want - to create. For example, <quote>company</quote>. - </para> - </listitem> - - <listitem> - <para> - Click the green tick next to the field name to confirm the - field name change. - </para> - </listitem> - - <listitem> - <para> - Double-click the corresponding <guilabel>Value</guilabel> - cell. - </para> - </listitem> - - <listitem> - <para> - Enter a company name, for example <quote>Example</quote>. - </para> - </listitem> - - <listitem> - <para> - Click the green tick next to the field value to confirm the - field value. - </para> - </listitem> - - <listitem> - <para> - The document is still not saved as this point. You must - explicitly save the document by clicking the <guibutton>Save - Document</guibutton> button at the top of the page. This - will save the document, and then display the new document - with the saved revision information (the - <literal>_rev</literal> field). - </para> - - <figure - id="fig-ccouchdb-single-introduction-futon-dbdocs-finaldoc"> - - <title>Edited Document</title> - - <mediaobject> - - <imageobject> - - <imagedata width="100%" contentdepth="100%" scalefit="1" -fileref="images/futon-editeddoc.png" -format="PNG" lang="en"/> - - </imageobject> - - <textobject> - - <phrase lang="en">Edited Document</phrase> - - </textobject> - - </mediaobject> - - </figure> - </listitem> - - </orderedlist> - - <para> - The same basic interface is used for all editng operations - within Futon. You <emphasis>must</emphasis> rememmbr to save the - individual element (fieldname, value) using the green tick - button, before then saving the document. - </para> - - </section> - - <section id="couchdb-single-introduction-futon-replication"> - - <title>Configuring Replication</title> - - <para> - When you click the <guibutton>Replicator</guibutton> option - within the <guilabel>Tools</guilabel> menu you are presented - with the Replicator screen. This allows you to start replication - between two databases by filling in or select the appropriate - options within the form provided. - </para> - - <figure - id="fig-ccouchdb-single-introduction-futon-replication-form"> - - <title>Replication Form</title> - - <mediaobject> - - <imageobject> - - <imagedata width="100%" contentdepth="100%" scalefit="1" -fileref="images/futon-replform.png" -format="PNG" lang="en"/> - - </imageobject> - - <textobject> - - <phrase lang="en">Replication Form</phrase> - - </textobject> - - </mediaobject> - - </figure> - - <para> - To start a replication process, either the select the local - database or enter a remote database name into the corresponding - areas of the form. Replication occurs from the database on the - left to the database on the right. - </para> - - <para> - If you are specifying a remote database name, you must specify - the full URL of the remote database (including the host, port - number and database name). If the remote instance requires - authentication, you can specify the username and password as - part of the URL, for example - <literal>http://username:pass@remotehost:5984/demo</literal>. - </para> - - <para> - To enable continuous replication, click the - <guilabel>Continuous</guilabel> checkbox. - </para> - - <para> - To start the replication process, click the - <guibutton>Replicate</guibutton> button. The replication process - should start and will continue in the background. If the - replication process will take a long time, you can monitor the - status of the replication using the - <guibutton>Status</guibutton> option under the - <guilabel>Tools</guilabel> menu. - </para> - - <para> - Once replication has been completed, the page will show the - information returned when the replication process completes by - the API. - </para> - - <para> - The <guilabel>Replicator</guilabel> tool is an interface to the - underlying replication API. For more information, see - <xref - linkend="couchdb-api-misc_replicate_post"/>. - For more information on replication, see - <xref linkend="couchdb-single-replication"/>. - </para> - - </section> - - </section> - - <section id="couchdb-single-introduction-curl"> - - <title>Using <command>curl</command></title> - - <para> - The <command>curl</command> utility is a command line tool - available on Unix, Linux, Mac OS X and Windows and many other - platforms. <command>curl</command> provides easy access to the - HTTP protocol (among others) directly from the command-line and is - therefore an ideal way of interacting with CouchDB - over the HTTP REST API. - </para> - - <para> - For simple <literal>GET</literal> requests you can supply the URL - of the request. For example, to get the database information: - </para> - -<programlisting> -shell> <userinput>curl http://127.0.0.1:5984</userinput> -</programlisting> - - <para> - This returns the database information (formatted in the output - below for clarity): - </para> - -<programlisting> -{ - "modules" : { - "geocouch" : "7fd793c10f3aa667a1088a937398bc5b51472b7f" - }, - "couchdb" : "Welcome", - "version" : "1.1.0", -} -</programlisting> - - <note> - <para> - For some URLs, especially those that include special characters - such as ampersand, exclamation mark, or question mark, you - should quote the URL you are specifying on the command line. For - example: - </para> - -<programlisting> -shell> <userinput>curl 'http://couchdb:5984/_uuids?count=5'</userinput> -</programlisting> - </note> - - <para> - You can explicitly set the HTTP command using the - <option>-X</option> command line option. For example, when - creating a database, you set the name of the database in the URL - you send using a PUT request: - </para> - -<programlisting> -shell> <userinput>curl -X PUT http://127.0.0.1:5984/demo</userinput> -{"ok":true} -</programlisting> - - <para> - But to obtain the database information you use a - <literal>GET</literal> request (with the return information - formatted for clarity): - </para> - -<programlisting> -shell> <userinput>curl -X GET http://127.0.0.1:5984/demo</userinput> -{ - "compact_running" : false, - "doc_count" : 0, - "db_name" : "demo", - "purge_seq" : 0, - "committed_update_seq" : 0, - "doc_del_count" : 0, - "disk_format_version" : 5, - "update_seq" : 0, - "instance_start_time" : "1306421773496000", - "disk_size" : 79 -} -</programlisting> - - <para> - For certain operations, you must specify the content type of - request, which you do by specifying the - <literal>Content-Type</literal> header using the - <option>-H</option> command-line option: - </para> - -<programlisting> -shell> <userinput>curl -H 'Content-type: application/json' http://127.0.0.1:5984/_uuids</userinput> -</programlisting> - - <para> - You can also submit 'payload' data, that is, data in the body of - the HTTP request using the <option>-d</option> option. This is - useful if you need to submit JSON structures, for example document - data, as part of the request. For example, to submit a simple - document to the <literal>demo</literal> database: - </para> - -<programlisting> -shell> <userinput>curl -H 'Content-type: application/json' \ - -X POST http://127.0.0.1:5984/demo \ - -d '{"company": "Example, Inc."}'</userinput> -{"ok":true,"id":"8843faaf0b831d364278331bc3001bd8", - "rev":"1-33b9fbce46930280dab37d672bbc8bb9"} -</programlisting> - - <para> - In the above example, the argument after the <option>-d</option> - option is the JSON of the document we want to submit. - </para> - - <para> - The document can be accessed by using the automatically generated - document ID that was returned: - </para> - -<programlisting> -shell> <userinput>curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8</userinput> -{"_id":"8843faaf0b831d364278331bc3001bd8", - "_rev":"1-33b9fbce46930280dab37d672bbc8bb9", - "company":"Example, Inc."} -</programlisting> - - <para> - The API samples in the <xref linkend="couchdb-api-basics"/> show - the HTTP command, URL and any payload information that needs to be - submitted (and the expected return value). All of these examples - can be reproduced using <command>curl</command> with the - command-line examples shown above. - </para> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml b/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml deleted file mode 100644 index 8667927bd..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml +++ /dev/null @@ -1,9409 +0,0 @@ -<?xml version="1.0" encoding="utf-8" standalone="no"?> -<book id="couchdb-1-1"> - - <title>CouchDB 1.1 Manual</title> - - <bookinfo> - - <abstract> - - <para> - This manual documents the CouchDB - 1.1 database system, including the installation, - functionality, and CouchDB API. - </para> - - <para xml:base="../common/docbuilddate.xml"> - <emphasis>Last document update</emphasis>: 21 Feb 2012 20:09; - <emphasis>Document built</emphasis>: 21 Feb 2012 20:9. -</para> - - </abstract> - - </bookinfo> - - <chapter id="couchdb-single-introduction"> - - <title>Introduction</title> - - <para> - There are two interfaces to CouchDB, the built-in - Futon web-based interface and the CouchDB API accessed through the - HTTP REST interface. The former is the simplest way to view and - monitor your CouchDB installation and perform a - number of basic database and system operations. More information on - using the Futon interface can be found in - <xref linkend="couchdb-single-introduction-futon"/>. - </para> - - <para> - The primary way to interact with the CouchDB API is to use a client - library or other interface that provides access to the underlying - functionality through your chosen language or platform. However, - since the API is supported through HTTP REST, you can interact with - your CouchDB with any solution that supports the - HTTP protocol. - </para> - - <para> - There are a number of different tools that talk the HTTP protocol - and allow you to set and configure the necessary information. One - tool for this that allows for access from the command-line is - <command moreinfo="none">curl</command>. See - <xref linkend="couchdb-single-introduction-curl"/>. - </para> - - <section id="couchdb-single-introduction-futon"> - - <title>Using Futon</title> - - <para> - Futon is a native web-based interface built into CouchDB. It provides a basic interface to the majority of the - functionality, including the ability to create, update, delete and - view documents and views, provides access to the configuration - parameters, and an interface for initiating replication. - </para> - - <para> - The default view is the <guilabel moreinfo="none">Overview</guilabel> page which - provides you with a list of the databases. The basic structure of - the page is consistent regardless of the section you are in. The - main panel on the left provides the main interface to the - databases, configuration or replication systems. The side panel on - the right provides navigation to the main areas of Futon - interface: - </para> - - <figure id="fig-ccouchdb-single-introduction-futon-overview" float="0"> - - <title>Futon Overview</title> - - <mediaobject> - - <imageobject> - - <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-overview.png" format="PNG" lang="en"/> - - </imageobject> - - <textobject> - - <phrase lang="en">Futon Overview</phrase> - - </textobject> - - </mediaobject> - - </figure> - - <para> - The main sections are: - </para> - - <itemizedlist> - - <listitem> - <para> - <guibutton moreinfo="none">Overview</guibutton> - </para> - - <para> - The main overview page, which provides a list of the databases - and provides the interface for querying the database and - creating and updating documents. See - <xref linkend="couchdb-single-introduction-futon-dbdocs"/>. - </para> - </listitem> - - <listitem> - <para> - <guibutton moreinfo="none">Configuration</guibutton> - </para> - - <para> - An interface into the configuration of your CouchDB installation. The interface allows you to edit the - different configurable parameters. For more details on - configuration, see - <xref linkend="couchdb-single-configuration"/>. - </para> - </listitem> - - <listitem> - <para> - <guibutton moreinfo="none">Replicator</guibutton> - </para> - - <para> - An interface to the replication system, enabling you to - initiate replication between local and remote databases. See - <xref linkend="couchdb-single-introduction-futon-replication"/>. - </para> - </listitem> - - <listitem> - <para> - <guibutton moreinfo="none">Status</guibutton> - </para> - - <para> - Displays a list of the running background tasks on the server. - Background tasks include view index building, compaction and - replication. The <guibutton moreinfo="none">Status</guibutton> page is an - interface to the - <link linkend="couchdb-api-misc_active-tasks_get">Active - Tasks</link> API call. See - <xref linkend="couchdb-api-misc_active-tasks_get"/>. - </para> - </listitem> - - <listitem> - <para> - <guibutton moreinfo="none">Verify Installation</guibutton> - </para> - - <para> - The <guibutton moreinfo="none">Verify Installation</guibutton> allows you to - check whether all of the components of your CouchDB installation are correctly installed. - </para> - </listitem> - - <listitem> - <para> - <guibutton moreinfo="none">Test Suite</guibutton> - </para> - - <para> - The <guibutton moreinfo="none">Test Suite</guibutton> section allows you to - run the built-in test suite. This executes a number of test - routines entirely within your browser to test the API and - functionality of your CouchDB installation. If - you select this page, you can run the tests by using the - <guibutton moreinfo="none">Run All</guibutton> button. This will execute all - the tests, which may take some time. - </para> - </listitem> - - </itemizedlist> - - <section id="couchdb-single-introduction-futon-dbdocs"> - - <title>Managing Databases and Documents</title> - - <para> - You can manage databases and documents within Futon using the - main <guibutton moreinfo="none">Overview</guibutton> section of the Futon - interface. - </para> - - <para> - To create a new database, click the <guibutton moreinfo="none">Create Database - …</guibutton> button. You will be prompted for the - database name, as shown in the figure below. - </para> - - <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-createdb" float="0"> - - <title>Creating a Database</title> - - <mediaobject> - - <imageobject> - - <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-createdb.png" format="PNG" lang="en"/> - - </imageobject> - - <textobject> - - <phrase lang="en">Creating a Database</phrase> - - </textobject> - - </mediaobject> - - </figure> - - <para> - Once you have created the database (or selected an existing - one), you will be shown a list of the current documents. If you - create a new document, or select an existing document, you will - be presented with the edit document display. - </para> - - <para> - Editing documents within Futon requires selecting the document - and then editing (and setting) the fields for the document - individually before saving the document back into the database. - </para> - - <para> - For example, the figure below shows the editor for a single - document, a newly created document with a single ID, the - document <literal moreinfo="none">_id</literal> field. - </para> - - <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-editdoc" float="0"> - - <title>Editing a Document</title> - - <mediaobject> - - <imageobject> - - <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-editdoc.png" format="PNG" lang="en"/> - - </imageobject> - - <textobject> - - <phrase lang="en">Editing a Document</phrase> - - </textobject> - - </mediaobject> - - </figure> - - <para> - To add a field to the document: - </para> - - <orderedlist inheritnum="ignore" continuation="restarts"> - - <listitem> - <para> - Click <guibutton moreinfo="none">Add Field</guibutton>. - </para> - </listitem> - - <listitem> - <para> - In the fieldname box, enter the name of the field you want - to create. For example, <quote>company</quote>. - </para> - </listitem> - - <listitem> - <para> - Click the green tick next to the field name to confirm the - field name change. - </para> - </listitem> - - <listitem> - <para> - Double-click the corresponding <guilabel moreinfo="none">Value</guilabel> - cell. - </para> - </listitem> - - <listitem> - <para> - Enter a company name, for example <quote>Example</quote>. - </para> - </listitem> - - <listitem> - <para> - Click the green tick next to the field value to confirm the - field value. - </para> - </listitem> - - <listitem> - <para> - The document is still not saved as this point. You must - explicitly save the document by clicking the <guibutton moreinfo="none">Save - Document</guibutton> button at the top of the page. This - will save the document, and then display the new document - with the saved revision information (the - <literal moreinfo="none">_rev</literal> field). - </para> - - <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-finaldoc" float="0"> - - <title>Edited Document</title> - - <mediaobject> - - <imageobject> - - <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-editeddoc.png" format="PNG" lang="en"/> - - </imageobject> - - <textobject> - - <phrase lang="en">Edited Document</phrase> - - </textobject> - - </mediaobject> - - </figure> - </listitem> - - </orderedlist> - - <para> - The same basic interface is used for all editng operations - within Futon. You <emphasis>must</emphasis> rememmbr to save the - individual element (fieldname, value) using the green tick - button, before then saving the document. - </para> - - </section> - - <section id="couchdb-single-introduction-futon-replication"> - - <title>Configuring Replication</title> - - <para> - When you click the <guibutton moreinfo="none">Replicator</guibutton> option - within the <guilabel moreinfo="none">Tools</guilabel> menu you are presented - with the Replicator screen. This allows you to start replication - between two databases by filling in or select the appropriate - options within the form provided. - </para> - - <figure id="fig-ccouchdb-single-introduction-futon-replication-form" float="0"> - - <title>Replication Form</title> - - <mediaobject> - - <imageobject> - - <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-replform.png" format="PNG" lang="en"/> - - </imageobject> - - <textobject> - - <phrase lang="en">Replication Form</phrase> - - </textobject> - - </mediaobject> - - </figure> - - <para> - To start a replication process, either the select the local - database or enter a remote database name into the corresponding - areas of the form. Replication occurs from the database on the - left to the database on the right. - </para> - - <para> - If you are specifying a remote database name, you must specify - the full URL of the remote database (including the host, port - number and database name). If the remote instance requires - authentication, you can specify the username and password as - part of the URL, for example - <literal moreinfo="none">http://username:pass@remotehost:5984/demo</literal>. - </para> - - <para> - To enable continuous replication, click the - <guilabel moreinfo="none">Continuous</guilabel> checkbox. - </para> - - <para> - To start the replication process, click the - <guibutton moreinfo="none">Replicate</guibutton> button. The replication process - should start and will continue in the background. If the - replication process will take a long time, you can monitor the - status of the replication using the - <guibutton moreinfo="none">Status</guibutton> option under the - <guilabel moreinfo="none">Tools</guilabel> menu. - </para> - - <para> - Once replication has been completed, the page will show the - information returned when the replication process completes by - the API. - </para> - - <para> - The <guilabel moreinfo="none">Replicator</guilabel> tool is an interface to the - underlying replication API. For more information, see - <xref linkend="couchdb-api-misc_replicate_post"/>. - For more information on replication, see - <xref linkend="couchdb-single-replication"/>. - </para> - - </section> - - </section> - - <section id="couchdb-single-introduction-curl"> - - <title>Using <command moreinfo="none">curl</command></title> - - <para> - The <command moreinfo="none">curl</command> utility is a command line tool - available on Unix, Linux, Mac OS X and Windows and many other - platforms. <command moreinfo="none">curl</command> provides easy access to the - HTTP protocol (among others) directly from the command-line and is - therefore an ideal way of interacting with CouchDB - over the HTTP REST API. - </para> - - <para> - For simple <literal moreinfo="none">GET</literal> requests you can supply the URL - of the request. For example, to get the database information: - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">curl http://127.0.0.1:5984</userinput></programlisting> - - <para> - This returns the database information (formatted in the output - below for clarity): - </para> - -<programlisting format="linespecific">{ - "modules" : { - "geocouch" : "7fd793c10f3aa667a1088a937398bc5b51472b7f" - }, - "couchdb" : "Welcome", - "version" : "1.1.0", -}</programlisting> - - <note> - <para> - For some URLs, especially those that include special characters - such as ampersand, exclamation mark, or question mark, you - should quote the URL you are specifying on the command line. For - example: - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">curl 'http://couchdb:5984/_uuids?count=5'</userinput></programlisting> - </note> - - <para> - You can explicitly set the HTTP command using the - <option>-X</option> command line option. For example, when - creating a database, you set the name of the database in the URL - you send using a PUT request: - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -X PUT http://127.0.0.1:5984/demo</userinput> -{"ok":true}</programlisting> - - <para> - But to obtain the database information you use a - <literal moreinfo="none">GET</literal> request (with the return information - formatted for clarity): - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/demo</userinput> -{ - "compact_running" : false, - "doc_count" : 0, - "db_name" : "demo", - "purge_seq" : 0, - "committed_update_seq" : 0, - "doc_del_count" : 0, - "disk_format_version" : 5, - "update_seq" : 0, - "instance_start_time" : "1306421773496000", - "disk_size" : 79 -}</programlisting> - - <para> - For certain operations, you must specify the content type of - request, which you do by specifying the - <literal moreinfo="none">Content-Type</literal> header using the - <option>-H</option> command-line option: - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -H 'Content-type: application/json' http://127.0.0.1:5984/_uuids</userinput></programlisting> - - <para> - You can also submit 'payload' data, that is, data in the body of - the HTTP request using the <option>-d</option> option. This is - useful if you need to submit JSON structures, for example document - data, as part of the request. For example, to submit a simple - document to the <literal moreinfo="none">demo</literal> database: - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -H 'Content-type: application/json' \ - -X POST http://127.0.0.1:5984/demo \ - -d '{"company": "Example, Inc."}'</userinput> -{"ok":true,"id":"8843faaf0b831d364278331bc3001bd8", - "rev":"1-33b9fbce46930280dab37d672bbc8bb9"}</programlisting> - - <para> - In the above example, the argument after the <option>-d</option> - option is the JSON of the document we want to submit. - </para> - - <para> - The document can be accessed by using the automatically generated - document ID that was returned: - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8</userinput> -{"_id":"8843faaf0b831d364278331bc3001bd8", - "_rev":"1-33b9fbce46930280dab37d672bbc8bb9", - "company":"Example, Inc."}</programlisting> - - <para> - The API samples in the <xref linkend="couchdb-api-basics"/> show - the HTTP command, URL and any payload information that needs to be - submitted (and the expected return value). All of these examples - can be reproduced using <command moreinfo="none">curl</command> with the - command-line examples shown above. - </para> - - </section> - -</chapter> - - <chapter id="couchdb-single-features"> - - <title>Features and Functionality</title> - - <para> - - </para> - - <section id="couchdb-single-features-httprange"> - - <title>HTTP Range Requests</title> - - <para> - HTTP allows you to specify byte ranges for requests. This allows - the implementation of resumable downloads and skippable audio and - video streams alike. The following example uses a text file to - make the range request process easier. - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">cat file.txt</userinput> -My hovercraft is full of eels!</programlisting> - - <para> - Uploading this as an attachment to a <literal moreinfo="none">text</literal> - database using <command moreinfo="none">curl</command>: - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \ - -H "Content-Type: application/octet-stream" -d@file.txt</userinput> -{"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}</programlisting> - - <para> - Requesting the whole file works as normal: - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/test/doc/file.txt</userinput> -My hovercraft is full of eels!</programlisting> - - <para> - But to retrieve only the first 13 bytes using - <command moreinfo="none">curl</command>: - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/test/doc/file.txt -H "Range: bytes=0-12"</userinput> -My hovercraft</programlisting> - - <para> - HTTP supports many ways to specify single and even multiple byte - rangers. See - <ulink url="http://tools.ietf.org/html/rfc2616#section-14.27">RFC - 2616</ulink>. - </para> - - <note> - <para> - Databases that have been created with CouchDB 1.0.2 or earlier - will support range requests in 1.1.0, but they are using a - less-optimal algorithm. If you plan to make heavy use of this - feature, make sure to compact your database with CouchDB 1.1.0 - to take advantage of a better algorithm to find byte ranges. - </para> - </note> - - </section> - - <section id="couchdb-single-features-proxying"> - - <title>HTTP Proxying</title> - - <para> - The HTTP proxy feature makes it easy to map and redirect different - content through your CouchDB URL. The proxy works by mapping a - pathname and passing all content after that prefix through to the - configured proxy address. - </para> - - <para> - Configuration of the proxy redirect is handled through the - <literal moreinfo="none">[httpd_global_handlers]</literal> section of the CouchDB - configuration file (typically <filename moreinfo="none">local.ini</filename>). The - format is: - </para> - -<programlisting format="linespecific">[httpd_global_handlers] -PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>}</programlisting> - - <para> - Where: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal moreinfo="none">PREFIX</literal> - </para> - - <para> - Is the string that will be matched. The string can be any - valid qualifier, although to ensure that existing database - names are not overridden by a proxy configuration, you can use - an underscore prefix. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">DESTINATION</literal> - </para> - - <para> - The fully-qualified URL to which the request should be sent. - The destination must include the <literal moreinfo="none">http</literal> - prefix. The content is used verbatim in the original request, - so you can also forward to servers on different ports and to - specific paths on the target host. - </para> - </listitem> - - </itemizedlist> - - <para> - The proxy process then translates requests of the form: - </para> - -<programlisting format="linespecific">http://couchdb:5984/PREFIX/path</programlisting> - - <para> - To: - </para> - -<programlisting format="linespecific">DESTINATION/path</programlisting> - - <note> - <para> - Everything after <literal moreinfo="none">PREFIX</literal> including the - required forward slash will be appended to the - <literal moreinfo="none">DESTINATION</literal>. - </para> - </note> - - <para> - The response is then communicated back to the original client. - </para> - - <para> - For example, the following configuration: - </para> - -<programlisting format="linespecific">_google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>}</programlisting> - - <para> - Would forward all requests for - <literal moreinfo="none">http://couchdb:5984/_google</literal> to the Google - website. - </para> - - <para> - The service can also be used to forward to related CouchDB - services, such as Lucene: - </para> - -<programlisting format="linespecific">[httpd_global_handlers] -_fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}</programlisting> - - <note> - <para> - The proxy service is basic. If the request is not identified by - the <literal moreinfo="none">DESTINATION</literal>, or the remainder of the - <literal moreinfo="none">PATH</literal> specification is incomplete, the - original request URL is interpreted as if the - <literal moreinfo="none">PREFIX</literal> component of that URL does not exist. - </para> - - <para> - For example, requesting - <literal moreinfo="none">http://couchdb:5984/_intranet/media</literal> when - <filename moreinfo="none">/media</filename> on the proxy destination does not - exist, will cause the request URL to be interpreted as - <literal moreinfo="none">http://couchdb:5984/media</literal>. Care should be - taken to ensure that both requested URLs and destination URLs - are able to cope - </para> - </note> - - </section> - - <section id="couchdb-single-features-commonjs"> - - <title>CommonJS support for map functions</title> - - <para> - CommonJS support allows you to use CommonJS notation inside - <methodname>map</methodname> and <methodname>reduce</methodname> - functions, but only of libraries that are stored inside the views - part of the design doc. - </para> - - <para> - So you could continue to access CommonJS code in design_doc.foo, - from your list functions etc, but we'd add the ability to require - CommonJS modules within map and reduce, but only from - <filename moreinfo="none">design_doc.views.lib</filename>. - </para> - - <para> - There's no worry here about namespace collisions, as Couch just - plucks <literal moreinfo="none">views.*.map</literal> and - <literal moreinfo="none">views.*.reduce</literal> out of the design doc. So you - could have a view called <literal moreinfo="none">lib</literal> if you wanted, and - still have CommonJS stored in <literal moreinfo="none">views.lib.sha1</literal> - and <literal moreinfo="none">views.lib.stemmer</literal> if you wanted. - </para> - - <para> - The implementation is simplified by enforcing that CommonJS - modules to be used in <methodname>map</methodname> functions be - stored in views.lib. - </para> - - <para> - A sample design doc (taken from the test suite in Futon) is below: - </para> - -<programlisting format="linespecific">{ - "views" : { - "lib" : { - "baz" : "exports.baz = 'bam';", - "foo" : { - "zoom" : "exports.zoom = 'yeah';", - "boom" : "exports.boom = 'ok';", - "foo" : "exports.foo = 'bar';" - } - }, - "commonjs" : { - "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}" - } - }, - "_id" : "_design/test" -}</programlisting> - - <para> - The <literal moreinfo="none">require()</literal> statement is relative to the - design document, but anything loaded form outside of - <literal moreinfo="none">views/lib</literal> will fail. - </para> - - </section> - - <section id="couchdb-single-features-etag"> - - <title>Granular ETag support</title> - - <para> - ETags have been assigned to a map/reduce group (the collection of - views in a single design document). Any change to any of the - indexes for those views would generate a new ETag for all view - URL's in a single design doc, even if that specific view's results - had not changed. - </para> - - <para> - In CouchDB 1.1 each <literal moreinfo="none">_view</literal> URL has it's own ETag - which only gets updated when changes are made to the database that - effect that index. If the index for that specific view does not - change, that view keeps the original ETag head (therefore sending - back 304 Not Modified more often). - </para> - - </section> - -</chapter> - - <chapter id="couchdb-single-replication"> - - <title>Replication</title> - - <para> - - </para> - - <section id="couchdb-single-replication-replicatordb"> - - <title>Replicator Database</title> - - <para> - A database where you - <literal moreinfo="none">PUT</literal>/<literal moreinfo="none">POST</literal> documents to - trigger replications and you <literal moreinfo="none">DELETE</literal> to cancel - ongoing replications. These documents have exactly the same - content as the JSON objects we used to <literal moreinfo="none">POST</literal> to - <literal moreinfo="none">_replicate</literal> (fields <literal moreinfo="none">source</literal>, - <literal moreinfo="none">target</literal>, <literal moreinfo="none">create_target</literal>, - <literal moreinfo="none">continuous</literal>, <literal moreinfo="none">doc_ids</literal>, - <literal moreinfo="none">filter</literal>, <literal moreinfo="none">query_params</literal>. - </para> - - <para> - Replication documents can have a user defined - <literal moreinfo="none">_id</literal>. Design documents (and - <literal moreinfo="none">_local</literal> documents) added to the replicator - database are ignored. - </para> - - <para> - The default name of this database is - <literal moreinfo="none">_replicator</literal>. The name can be changed in the - <filename moreinfo="none">local.ini</filename> configuration, section - <literal moreinfo="none">[replicator]</literal>, parameter <literal moreinfo="none">db</literal>. - </para> - - <section id="couchdb-single-replication-replicatordb-basics"> - - <title>Basics</title> - - <para> - Let's say you PUT the following document into _replicator: - </para> - -<programlisting format="linespecific">{ - "_id": "my_rep", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "create_target": true -}</programlisting> - - <para> - In the couch log you'll see 2 entries like these: - </para> - -<programlisting format="linespecific">[Thu, 17 Feb 2011 19:43:59 GMT] [info] [<0.291.0>] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target` -[Thu, 17 Feb 2011 19:44:37 GMT] [info] [<0.124.0>] Replication `c0ebe9256695ff083347cbf95f93e280+create_target` finished (triggered by document `my_rep`)</programlisting> - - <para> - As soon as the replication is triggered, the document will be - updated by CouchDB with 3 new fields: - </para> - -<programlisting format="linespecific">{ - "_id": "my_rep", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "create_target": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -}</programlisting> - - <para> - Special fields set by the replicator start with the prefix - <literal moreinfo="none">_replication_</literal>. - </para> - - <itemizedlist> - - <listitem> - <para> - <literal moreinfo="none">_replication_id</literal> - </para> - - <para> - The ID internally assigned to the replication. This is also - the ID exposed by <literal moreinfo="none">/_active_tasks</literal>. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">_replication_state</literal> - </para> - - <para> - The current state of the replication. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">_replication_state_time</literal> - </para> - - <para> - A Unix timestamp (number of seconds since 1 Jan 1970) that - tells us when the current replication state (marked in - <literal moreinfo="none">_replication_state</literal>) was set. - </para> - </listitem> - - </itemizedlist> - - <para> - When the replication finishes, it will update the - <literal moreinfo="none">_replication_state</literal> field (and - <literal moreinfo="none">_replication_state_time</literal>) with the value - <literal moreinfo="none">completed</literal>, so the document will look like: - </para> - -<programlisting format="linespecific">{ - "_id": "my_rep", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "create_target": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "completed", - "_replication_state_time": 1297974122 -}</programlisting> - - <para> - When an error happens during replication, the - <literal moreinfo="none">_replication_state</literal> field is set to - <literal moreinfo="none">error</literal> (and - <literal moreinfo="none">_replication_state</literal> gets updated of course). - </para> - - <para> - When you PUT/POST a document to the - <literal moreinfo="none">_replicator</literal> database, CouchDB will attempt to - start the replication up to 10 times (configurable under - <literal moreinfo="none">[replicator]</literal>, parameter - <literal moreinfo="none">max_replication_retry_count</literal>). If it fails on - the first attempt, it waits 5 seconds before doing a second - attempt. If the second attempt fails, it waits 10 seconds before - doing a third attempt. If the third attempt fails, it waits 20 - seconds before doing a fourth attempt (each attempt doubles the - previous wait period). When an attempt fails, the Couch log will - show you something like: - </para> - -<programlisting format="linespecific">[error] [<0.149.0>] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,<<"could not open http://myserver:5986/foo/">></programlisting> - - <note> - <para> - The <literal moreinfo="none">_replication_state</literal> field is only set to - <literal moreinfo="none">error</literal> when all the attempts were - unsuccessful. - </para> - </note> - - <para> - There are only 3 possible values for the - <literal moreinfo="none">_replication_state</literal> field: - <literal moreinfo="none">triggered</literal>, <literal moreinfo="none">completed</literal> and - <literal moreinfo="none">error</literal>. Continuous replications never get - their state set to <literal moreinfo="none">completed</literal>. - </para> - - </section> - - <section id="couchdb-single-replication-replicatordb-docsame"> - - <title>Documents describing the same replication</title> - - <para> - Lets suppose 2 documents are added to the - <literal moreinfo="none">_replicator</literal> database in the following order: - </para> - -<programlisting format="linespecific">{ - "_id": "doc_A", - "source": "http://myserver.com:5984/foo", - "target": "bar" -}</programlisting> - - <para> - and - </para> - -<programlisting format="linespecific">{ - "_id": "doc_B", - "source": "http://myserver.com:5984/foo", - "target": "bar" -}</programlisting> - - <para> - Both describe exactly the same replication (only their - <literal moreinfo="none">_ids</literal> differ). In this case document - <literal moreinfo="none">doc_A</literal> triggers the replication, getting - updated by CouchDB with the fields - <literal moreinfo="none">_replication_state</literal>, - <literal moreinfo="none">_replication_state_time</literal> and - <literal moreinfo="none">_replication_id</literal>, just like it was described - before. Document <literal moreinfo="none">doc_B</literal> however, is only - updated with one field, the <literal moreinfo="none">_replication_id</literal> - so it will look like this: - </para> - -<programlisting format="linespecific">{ - "_id": "doc_B", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "_replication_id": "c0ebe9256695ff083347cbf95f93e280" -}</programlisting> - - <para> - While document <literal moreinfo="none">doc_A</literal> will look like this: - </para> - -<programlisting format="linespecific">{ - "_id": "doc_A", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -}</programlisting> - - <para> - Note that both document get exactly the same value for the - <literal moreinfo="none">_replication_id</literal> field. This way you can - identify which documents refer to the same replication - you can - for example define a view which maps replication IDs to document - IDs. - </para> - - </section> - - <section id="couchdb-single-replication-replicatordb-cancel"> - - <title>Canceling replications</title> - - <para> - To cancel a replication simply <literal moreinfo="none">DELETE</literal> the - document which triggered the replication. The Couch log will - show you an entry like the following: - </para> - -<programlisting format="linespecific">[Thu, 17 Feb 2011 20:16:29 GMT] [info] [<0.125.0>] Stopped replication `c0ebe9256695ff083347cbf95f93e280+continuous+create_target` because replication document `doc_A` was deleted</programlisting> - - <note> - <para> - You need to <literal moreinfo="none">DELETE</literal> the document that - triggered the replication. <literal moreinfo="none">DELETE</literal>ing - another document that describes the same replication but did - not trigger it, will not cancel the replication. - </para> - </note> - - </section> - - <section id="couchdb-single-replication-replicatordb-restart"> - - <title>Server restart</title> - - <para> - When CouchDB is restarted, it checks its - <literal moreinfo="none">_replicator</literal> database and restarts any - replication that is described by a document that either has its - <literal moreinfo="none">_replication_state</literal> field set to - <literal moreinfo="none">triggered</literal> or it doesn't have yet the - <literal moreinfo="none">_replication_state</literal> field set. - </para> - - <note> - <para> - Continuous replications always have a - <literal moreinfo="none">_replication_state</literal> field with the value - <literal moreinfo="none">triggered</literal>, therefore they're always - restarted when CouchDB is restarted. - </para> - </note> - - </section> - - <section id="couchdb-single-replication-replicatordb-changing"> - - <title>Changing the Replicator Database</title> - - <para> - Imagine your replicator database (default name is _replicator) - has the two following documents that represent pull replications - from servers A and B: - </para> - -<programlisting format="linespecific">{ - "_id": "rep_from_A", - "source": "http://aserver.com:5984/foo", - "target": "foo_a", - "continuous": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297971311 -} -{ - "_id": "rep_from_B", - "source": "http://bserver.com:5984/foo", - "target": "foo_b", - "continuous": true, - "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -}</programlisting> - - <para> - Now without stopping and restarting CouchDB, you change the name - of the replicator database to - <literal moreinfo="none">another_replicator_db</literal>: - </para> - -<programlisting format="linespecific">$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"' -"_replicator"</programlisting> - - <para> - As soon as this is done, both pull replications defined before, - are stopped. This is explicitly mentioned in CouchDB's log: - </para> - -<programlisting format="linespecific">[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.104.0>] Stopping all ongoing replications because the replicator database was deleted or changed -[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.127.0>] 127.0.0.1 - - PUT /_config/replicator/db 200</programlisting> - - <para> - Imagine now you add a replication document to the new replicator - database named <literal moreinfo="none">another_replicator_db</literal>: - </para> - -<programlisting format="linespecific">{ - "_id": "rep_from_X", - "source": "http://xserver.com:5984/foo", - "target": "foo_x", - "continuous": true -}</programlisting> - - <para> - From now own you have a single replication going on in your - system: a pull replication pulling from server X. Now you change - back the replicator database to the original one - <literal moreinfo="none">_replicator</literal>: - </para> - -<programlisting format="linespecific">$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"' -"another_replicator_db"</programlisting> - - <para> - Immediately after this operation, the replication pulling from - server X will be stopped and the replications defined in the - _replicator database (pulling from servers A and B) will be - resumed. - </para> - - <para> - Changing again the replicator database to - <literal moreinfo="none">another_replicator_db</literal> will stop the pull - replications pulling from servers A and B, and resume the pull - replication pulling from server X. - </para> - - </section> - - <section id="couchdb-single-replication-replicatordb-replicating"> - - <title>Replicating the replicator database</title> - - <para> - Imagine you have in server C a replicator database with the two - following pull replication documents in it: - </para> - -<programlisting format="linespecific">{ - "_id": "rep_from_A", - "source": "http://aserver.com:5984/foo", - "target": "foo_a", - "continuous": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297971311 -} -{ - "_id": "rep_from_B", - "source": "http://bserver.com:5984/foo", - "target": "foo_b", - "continuous": true, - "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -}</programlisting> - - <para> - Now you would like to have the same pull replications going on - in server D, that is, you would like to have server D pull - replicating from servers A and B. You have two options: - </para> - - <itemizedlist> - - <listitem> - <para> - Explicitly add two documents to server's D replicator - database - </para> - </listitem> - - <listitem> - <para> - Replicate server's C replicator database into server's D - replicator database - </para> - </listitem> - - </itemizedlist> - - <para> - Both alternatives accomplish exactly the same goal. - </para> - - </section> - - <section id="couchdb-single-replication-replicatordb-delegations"> - - <title>Delegations</title> - - <para> - Replication documents can have a custom - <literal moreinfo="none">user_ctx</literal> property. This property defines the - user context under which a replication runs. For the old way of - triggering replications (POSTing to - <literal moreinfo="none">/_replicate/</literal>), this property was not needed - (it didn't exist in fact) - this is because at the moment of - triggering the replication it has information about the - authenticated user. With the replicator database, since it's a - regular database, the information about the authenticated user - is only present at the moment the replication document is - written to the database - the replicator database implementation - is like a _changes feed consumer (with - <literal moreinfo="none">?include_docs=true</literal>) that reacts to what was - written to the replicator database - in fact this feature could - be implemented with an external script/program. This - implementation detail implies that for non admin users, a - <literal moreinfo="none">user_ctx</literal> property, containing the user's name - and a subset of his/her roles, must be defined in the - replication document. This is ensured by the document update - validation function present in the default design document of - the replicator database. This validation function also ensure - that a non admin user can set a user name property in the - <literal moreinfo="none">user_ctx</literal> property that doesn't match his/her - own name (same principle applies for the roles). - </para> - - <para> - For admins, the <literal moreinfo="none">user_ctx</literal> property is - optional, and if it's missing it defaults to a user context with - name null and an empty list of roles - this mean design - documents will not be written to local targets. If writing - design documents to local targets is desired, the a user context - with the roles <literal moreinfo="none">_admin</literal> must be set explicitly. - </para> - - <para> - Also, for admins the <literal moreinfo="none">user_ctx</literal> property can be - used to trigger a replication on behalf of another user. This is - the user context that will be passed to local target database - document validation functions. - </para> - - <note> - <para> - The <literal moreinfo="none">user_ctx</literal> property only has effect for - local endpoints. - </para> - </note> - - <para> - Example delegated replication document: - </para> - -<programlisting format="linespecific">{ - "_id": "my_rep", - "source": "http://bserver.com:5984/foo", - "target": "bar", - "continuous": true, - "user_ctx": { - "name": "joe", - "roles": ["erlanger", "researcher"] - } -}</programlisting> - - <para> - As stated before, for admins the user_ctx property is optional, - while for regular (non admin) users it's mandatory. When the - roles property of <literal moreinfo="none">user_ctx</literal> is missing, it - defaults to the empty list <literal moreinfo="none">[ ]</literal>. - </para> - - </section> - - </section> - -</chapter> - - - - <chapter id="couchdb-api-basics"> - - <title>CouchDB API</title> - - <para> - 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. - </para> - - <para> - 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 <literal moreinfo="none">GET</literal> operation, while updates are - handled by either a <literal moreinfo="none">POST</literal> or - <literal moreinfo="none">PUT</literal> 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 - <xref linkend="couchdb-api-introduction-requests"/>. - </para> - - <para> - 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 <xref linkend="couchdb-api-introduction-json"/>. - </para> - - <para> - 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 - <xref linkend="couchdb-api-introduction-returncodes"/>. - </para> - - <para> - 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 - <xref linkend="couchdb-api-overview"/>. - </para> - - <section id="couchdb-api-introduction-requests"> - - <title>Request Format and Responses</title> - - <para> - CouchDB supports the following HTTP request methods: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal moreinfo="none">GET</literal> - </para> - - <para> - 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. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">HEAD</literal> - </para> - - <para> - The <literal moreinfo="none">HEAD</literal> method is used to get the HTTP - header of a <literal moreinfo="none">GET</literal> request without the body of - the response. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">POST</literal> - </para> - - <para> - Upload data. Within CouchDB <literal moreinfo="none">POST</literal> is used to - set values, including uploading documents, setting document - values, and starting certain administration commands. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">PUT</literal> - </para> - - <para> - Used to put a specified resource. In CouchDB - <literal moreinfo="none">PUT</literal> is used to create new objects, - including databases, documents, views and design documents. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">DELETE</literal> - </para> - - <para> - Deletes the specified resource, including documents, views, - and design documents. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">COPY</literal> - </para> - - <para> - A special method that can be used to copy documents and - objects. - </para> - </listitem> - - </itemizedlist> - - <para> - 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: - </para> - -<programlisting format="linespecific">{ - "error":"method_not_allowed", - "reason":"Only GET,HEAD allowed" -}</programlisting> - - - - <para> - 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 <literal moreinfo="none">headers</literal> - block of the return object. For more information, see - <xref linkend="couchdb-api-functional"/>. - </para> - - </section> - - <section id="couchdb-api-introduction-request-header"> - - <title>HTTP Headers</title> - - <para> - 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. - </para> - - <section id="couchdb-api-introduction-request-header-request"> - - <title>Request Headers</title> - - <itemizedlist> - - <listitem> - <para> - <literal moreinfo="none">Content-type</literal> - </para> - - <para> - 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 (<literal moreinfo="none">application/json</literal>). 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 - (<literal moreinfo="none">application/octet-stream</literal>). - </para> - - <para> - The use of the <literal moreinfo="none">Content-type</literal> on a request - is highly recommended. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">Accept</literal> - </para> - - <para> - 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. - </para> - - <para> - For the majority of requests the definition should be for - JSON data (<literal moreinfo="none">application/json</literal>). For - attachments you can either specify the MIME type explicitly, - or use <literal moreinfo="none">*/*</literal> to specify that all file types - are supported. If the <literal moreinfo="none">Accept</literal> header is - not supplied, then the <literal moreinfo="none">*/*</literal> MIME type is - assumed (i.e. client accepts all formats). - </para> - - <para> - The use of <literal moreinfo="none">Accept</literal> 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. - </para> - - <para> - If you specify a data type using the - <literal moreinfo="none">Accept</literal> header, CouchDB will honor the - specified type in the <literal moreinfo="none">Content-type</literal> header - field returned. For example, if you explicitly request - <literal moreinfo="none">application/json</literal> in the - <literal moreinfo="none">Accept</literal> of a request, the returned HTTP - headers will use the value in the returned - <literal moreinfo="none">Content-type</literal> field. - </para> - - <para> - For example, when sending a request without an explicit - <literal moreinfo="none">Accept</literal> header, or when specifying - <literal moreinfo="none">*/*</literal>: - </para> - -<programlisting format="linespecific">GET /recipes HTTP/1.1 -Host: couchdb:5984 -Accept: */*</programlisting> - - <para> - The returned headers are: - </para> - -<programlisting format="linespecific">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</programlisting> - - <para> - Note that the returned content type is - <literal moreinfo="none">text/plain</literal> even though the information - returned by the request is in JSON format. - </para> - - <para> - Explicitly specifying the <literal moreinfo="none">Accept</literal> header: - </para> - -<programlisting format="linespecific">GET /recipes HTTP/1.1 -Host: couchdb:5984 -Accept: application/json</programlisting> - - <para> - The headers returned include the - <literal moreinfo="none">application/json</literal> content type: - </para> - -<programlisting format="linespecific">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</programlisting> - </listitem> - - </itemizedlist> - - </section> - - <section id="couchdb-api-introduction-request-header-response"> - - <title>Response Headers</title> - - <para> - 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. - </para> - - <itemizedlist> - - <listitem> - <para> - <literal moreinfo="none">Content-type</literal> - </para> - - <para> - Specifies the MIME type of the returned data. For most - request, the returned MIME type is - <literal moreinfo="none">text/plain</literal>. All text is encoded in - Unicode (UTF-8), and this is explicitly stated in the - returned <literal moreinfo="none">Content-type</literal>, as - <literal moreinfo="none">text/plain;charset=utf-8</literal>. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">Cache-control</literal> - </para> - - <para> - The cache control HTTP response header provides a suggestion - for client caching mechanisms on how to treat the returned - information. CouchDB typically returns the - <literal moreinfo="none">must-revalidate</literal>, 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. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">Content-length</literal> - </para> - - <para> - The length (in bytes) of the returned content. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">Etag</literal> - </para> - - <para> - The <literal moreinfo="none">Etag</literal> HTTP header field is used to - show the revision for a document. - </para> - </listitem> - - </itemizedlist> - - </section> - - </section> - - <section id="couchdb-api-introduction-json"> - - <title>JSON Basics</title> - - <para> - 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. - </para> - - <para> - 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. - </para> - - <para> - JSON supports the same basic types as supported by JavaScript, - these are: - </para> - - <itemizedlist> - - <listitem> - <para> - Number (either integer or floating-point). - </para> - </listitem> - - <listitem> - <para> - String; this should be enclosed by double-quotes and supports - Unicode characters and backslash escaping. For example: - </para> - -<programlisting format="linespecific">"A String"</programlisting> - </listitem> - - <listitem> - <para> - Boolean - a <literal moreinfo="none">true</literal> or - <literal moreinfo="none">false</literal> value. You can use these strings - directly. For example: - </para> - -<programlisting format="linespecific">{ "value": true}</programlisting> - </listitem> - - <listitem> - <para> - Array - a list of values enclosed in square brackets. For - example: - </para> - -<programlisting format="linespecific">["one", "two", "three"]</programlisting> - </listitem> - - <listitem> - <para> - Object - a set of key/value pairs (i.e. an associative array, - or hash). The key must be a string, but the value can be any - of the supported JSON values. For example: - </para> - -<programlisting format="linespecific">{ - "servings" : 4, - "subtitle" : "Easy to make in advance, and then cook when ready", - "cooktime" : 60, - "title" : "Chicken Coriander" -}</programlisting> - - <para> - In CouchDB, the JSON object is used to represent a variety of - structures, including the main CouchDB document. - </para> - </listitem> - - </itemizedlist> - - <para> - Parsing JSON into a JavaScript object is supported through the - <literal moreinfo="none">eval()</literal> function in JavaScript, or through - various libraries that will perform the parsing of the content - into a JavaScript object for you. Libraries for parsing and - generating JSON are available in many languages, including Perl, - Python, Ruby, Erlang and others. - </para> - - <warning> - <para> - Care should be taken to ensure that your JSON structures are - valid, invalid structures will cause CouchDB to return an HTTP - status code of 500 (server error). See - <xref linkend="couchdb-api-introduction-returncode-500"/> - . - </para> - </warning> - - </section> - - <section id="couchdb-api-introduction-returncodes"> - - <title>HTTP Status Codes</title> - - <para> - With the interface to CouchDB working through HTTP, error codes - and statuses are reported using a combination of the HTTP status - code number, and corresponding data in the body of the response - data. - </para> - - <para> - A list of the error codes returned by CouchDB, and generic - descriptions of the related errors are provided below. The meaning - of different status codes for specific request types are provided - in the corresponding API call reference. - </para> - - <itemizedlist> - - <listitem> - <para id="couchdb-api-introduction-returncode-200"> - <literal moreinfo="none">200 - OK</literal> - </para> - - <para> - Request completed successfully. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-201"> - <literal moreinfo="none">201 - Created</literal> - </para> - - <para> - Document created successfully. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-202"> - <literal moreinfo="none">202 - Accepted</literal> - </para> - - <para> - Request has been accepted, but the corresponding operation may - not have completed. This is used for background operations, - such as database compaction. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-304"> - <literal moreinfo="none">304 - Not Modified</literal> - </para> - - <para> - The additional content requested has not been modified. This - is used with the ETag system to identify the version of - information returned. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-400"> - <literal moreinfo="none">400 - Bad Request</literal> - </para> - - <para> - Bad request structure. The error can indicate an error with - the request URL, path or headers. Differences in the supplied - MD5 hash and content also trigger this error, as this may - indicate message corruption. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-401"> - <literal moreinfo="none">401 - Unauthorized</literal> - </para> - - <para> - The item requested was not available using the supplied - authorization, or authorization was not supplied. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-403"> - <literal moreinfo="none">403 - Forbidden</literal> - </para> - - <para> - The requested item or operation is forbidden. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-404"> - <literal moreinfo="none">404 - Not Found</literal> - </para> - - <para> - The requested content could not be found. The content will - include further information, as a JSON object, if available. - The structure will contain two keys, <literal moreinfo="none">error</literal> - and <literal moreinfo="none">reason</literal>. For example: - </para> - -<programlisting format="linespecific">{"error":"not_found","reason":"no_db_file"}</programlisting> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-405"> - <literal moreinfo="none">405 - Resource Not Allowed</literal> - </para> - - <para> - A request was made using an invalid HTTP request type for the - URL requested. For example, you have requested a - <literal moreinfo="none">PUT</literal> when a <literal moreinfo="none">POST</literal> is - required. Errors of this type can also triggered by invalid - URL strings. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-406"> - <literal moreinfo="none">406 - Not Acceptable</literal> - </para> - - <para> - The requested content type is not supported by the server. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-409"> - <literal moreinfo="none">409 - Conflict</literal> - </para> - - <para> - Request resulted in an update conflict. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-412"> - <literal moreinfo="none">412 - Precondition Failed</literal> - </para> - - <para> - The request headers from the client and the capabilities of - the server do not match. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-415"> - <literal moreinfo="none">415 - Bad Content Type</literal> - </para> - - <para> - The content types supported, and the content type of the - information being requested or submitted indicate that the - content type is not supported. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-416"> - <literal moreinfo="none">416 - Requested Range Not Satisfiable</literal> - </para> - - <para> - The range specified in the request header cannot be satisfied - by the server. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-417"> - <literal moreinfo="none">417 - Expectation Failed</literal> - </para> - - <para> - When sending documents in bulk, the bulk load operation - failed. - </para> - </listitem> - - <listitem> - <para id="couchdb-api-introduction-returncode-500" xreflabel="HTTP Status Code 500"> - <literal moreinfo="none">500 - Internal Server Error</literal> - </para> - - <para> - The request was invalid, either because the supplied JSON was - invalid, or invalid information was supplied as part of the - request. - </para> - </listitem> - - </itemizedlist> - - </section> - - <section id="couchdb-api-overview"> - - <title>CouchDB API Overview</title> - - <para> - The components of the API URL path help determine the part of the - CouchDB server that is being accessed. The result is the structure - of the URL request both identifies and effectively describes the - area of the database you are accessing. - </para> - - <para> - As with all URLs, the individual components are separated by a - forward slash. - </para> - - <para> - As a general rule, URL components and JSON fields starting with - the <literal moreinfo="none">_</literal> (underscore) character represent a - special component or entity within the server or returned object. - For example, the URL fragment <literal moreinfo="none">/_all_dbs</literal> gets a - list of all of the databases in a CouchDB instance. - </para> - - <para> - The remainder of the URL API structure can be divided up according - to the URL structure. The different sections are divided as - follows: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal moreinfo="none">/db</literal> - </para> - - <para> - Database methods, related to adding, updating or deleting - databases, and setting database parameters and operations. For - more detailed information, see - <xref linkend="couchdb-api-db"/> . - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">/db/doc</literal> - </para> - - <para> - Document methods, those that create, store, update or delete - CouchDB documents and their attachments. For more information, - see <xref linkend="couchdb-api-dbdoc"/>. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">/db/_local/local-doc</literal> - </para> - - <para> - Document methods, those that create, store, update or delete - CouchDB documents only within the local database. Local - documents are not synchronized with other databases. For more - information, see - <xref linkend="couchdb-api-localdb"/>. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">/db/_design/design-doc</literal> - </para> - - <para> - Design documents provide the methods and structure for - recovering information from a CouchDB database in the form of - views, shows and lists. For more information, see - <xref linkend="couchdb-api-design"/>. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">/_special</literal> - </para> - - <para> - Special methods that obtain or set information about the - CouchDB instance, including methods for configuring - replication, accessing the logs, and generate Universally - Unique IDs (UUIDs). For more information, see - <xref linkend="couchdb-api-misc"/>. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">/_config</literal> - </para> - - <para> - Methods for getting, and settings, CouchDB configuration - parameters. For more information, see - <xref linkend="couchdb-api-misc"/>. - </para> - </listitem> - - </itemizedlist> - - - - </section> - -</chapter> - - <chapter id="couchdb-api-db"> - - <title>CouchDB API Server Database Methods</title> - - <para> - The Database methods provide an interface to an entire database - withing CouchDB. These are database, rather than document, level - requests. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db-summary"><title>Database API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-db_db_get"> - Returns database information - </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-db_db_put"> - Create a new database - </link></entry></row><row><entry><literal moreinfo="none">DELETE</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-db_db_delete"> - Delete an existing database - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_all_docs</literal></entry><entry><link linkend="couchdb-api-db_db-all-docs_get"> - Returns a built-in view of all documents in this database - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_all_docs</literal></entry><entry><link linkend="couchdb-api-db_db-all-docs_post"> - Returns certain rows from the built-in view of all documents - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_bulk_docs</literal></entry><entry><link linkend="couchdb-api-db_db-bulk-docs_post"> - Insert multiple documents in to the database in a single request - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_changes</literal></entry><entry><link linkend="couchdb-api-db_db-changes_get"> - Returns changes for the given database - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_compact</literal></entry><entry><link linkend="couchdb-api-db_db-compact_post"> - Starts a compaction for the database - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_compact/design-doc</literal></entry><entry><link linkend="couchdb-api-db_db-compact-design-doc_post"> - Starts a compaction for all the views in the selected design - document - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_ensure_full_commit</literal></entry><entry><link linkend="couchdb-api-db_db-ensure-full-commit_post"> - Makes sure all uncommitted changes are written and synchronized - to the disk - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_missing_revs</literal></entry><entry><link linkend="couchdb-api-db_db-missing-revs_post"> - Given a list of document revisions, returns the document - revisions that do not exist in the database - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_purge</literal></entry><entry><link linkend="couchdb-api-db_db-purge_post"> - Purge some historical documents entirely from database history - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_revs_diff</literal></entry><entry><link linkend="couchdb-api-db_db-revs-diff_post"> - Given a list of document revisions, returns differences between - the given revisions and ones that are in the database - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_revs_limit</literal></entry><entry><link linkend="couchdb-api-db_db-revs-limit_get"> - Gets the limit of historical revisions to store for a single - document in the database - </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/_revs_limit</literal></entry><entry><link linkend="couchdb-api-db_db-revs-limit_put"> - Sets the limit of historical revisions to store for a single - document in the database - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_security</literal></entry><entry><link linkend="couchdb-api-db_db-security_get"> - Returns the special security object for the database - </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/_security</literal></entry><entry><link linkend="couchdb-api-db_db-security_put"> - Sets the special security object for the database - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_temp_view</literal></entry><entry><link linkend="couchdb-api-db_db-temp-view_post"> - Execute a given view function for all documents and return the - result - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_view_cleanup</literal></entry><entry><link linkend="couchdb-api-db_db-view-cleanup_post"> - Removes view files that are not used by any design document - </link></entry></row></tbody></tgroup></table> - - <para> - 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 - <literal moreinfo="none">recipes</literal>, you would use the HTTP request: - </para> - -<programlisting format="linespecific">GET /recipes</programlisting> - - <para> - For clarity, the form below is used in the URL paths: - </para> - -<programlisting format="linespecific">GET /db</programlisting> - - <para> - Where <literal moreinfo="none">db</literal> is the name of any database. - </para> - - <section id="couchdb-api-db_db_get"> - - <title><literal moreinfo="none">GET /db</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Information about the database in JSON format - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The requested content could not be found. The returned content - will include further information, as a JSON object, if available. - </entry></row></tbody></tgroup></informaltable> - - <para> - Gets information about the specified database. For example, to - retrieve the information for the database - <literal moreinfo="none">recipe</literal>: - </para> - -<programlisting role="httprequest" format="linespecific">GET http://couchdb:5984/recipes -Accept: application/json</programlisting> - - <para> - The JSON response contains meta information about the database. A - sample of the JSON returned for an empty database is provided - below: - </para> - -<programlisting role="httpresponse" format="linespecific">{ - "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 -}</programlisting> - - <para> - The elements of the returned structure are shown in the table - below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db-json-db-info" class="jsonstructure"><title> - CouchDB database information object - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">committed_update_seq</literal> </entry><entry> - The number of committed update. - </entry></row><row><entry><literal moreinfo="none">compact_running</literal> </entry><entry> - Set to true if the database compaction routine is operating on - this database. - </entry></row><row><entry><literal moreinfo="none">db_name</literal> </entry><entry> - The name of the database. - </entry></row><row><entry><literal moreinfo="none">disk_format_version</literal> </entry><entry> - The version of the physical format used for the data when it is - stored on disk. - </entry></row><row><entry><literal moreinfo="none">disk_size</literal> </entry><entry> - Size in bytes of the data as stored on the disk. Views indexes - are not included in the calculation. - </entry></row><row><entry><literal moreinfo="none">doc_count</literal> </entry><entry> - A count of the documents in the specified database. - </entry></row><row><entry><literal moreinfo="none">doc_del_count</literal> </entry><entry> - Number of deleted documents - </entry></row><row><entry><literal moreinfo="none">instance_start_time</literal> </entry><entry> - Timestamp of when the database was created, expressed in - milliseconds since the epoch. - </entry></row><row><entry><literal moreinfo="none">purge_seq</literal> </entry><entry> - The number of purge operations on the database. - </entry></row><row><entry><literal moreinfo="none">update_seq</literal> </entry><entry> - The current number of updates to the database. - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-api-db_db_put"> - - <title><literal moreinfo="none">PUT /db</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API PUT /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON success statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>400</entry><entry namest="info" nameend="addinfo"> - Invalid database name - </entry></row><row><entry>412</entry><entry namest="info" nameend="addinfo"> - Database already exists - </entry></row></tbody></tgroup></informaltable> - - <para> - Creates a new database. The database name must be composed of one - or more of the following characters: - </para> - - <itemizedlist> - - <listitem> - <para> - Lowercase characters (<literal moreinfo="none">a-z</literal>) - </para> - </listitem> - - <listitem> - <para> - Name must begin with a lowercase letter - </para> - </listitem> - - <listitem> - <para> - Digits (<literal moreinfo="none">0-9</literal>) - </para> - </listitem> - - <listitem> - <para> - Any of the characters <literal moreinfo="none">_</literal>, - <literal moreinfo="none">$</literal>, <literal moreinfo="none">(</literal>, - <literal moreinfo="none">)</literal>, <literal moreinfo="none">+</literal>, - <literal moreinfo="none">-</literal>, and <literal moreinfo="none">/</literal>. - </para> - </listitem> - - </itemizedlist> - - <para> - Trying to create a database that does not meet these requirements - will return an error quoting these restrictions. - </para> - - <para> - To create the database <literal moreinfo="none">recipes</literal>: - </para> - -<programlisting format="linespecific">PUT http://couchdb:5984/recipes -Content-Type: application/json</programlisting> - - <para> - The returned content contains the JSON status: - </para> - -<programlisting format="linespecific">{ - "ok" : true -}</programlisting> - - <para> - Anything should be treated as an error, and the problem should be - taken form the HTTP response code. - </para> - - </section> - - <section id="couchdb-api-db_db_delete"> - - <title><literal moreinfo="none">DELETE /db</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API DELETE /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">DELETE /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON success statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Database has been deleted - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The requested content could not be found. The returned content - will include further information, as a JSON object, if available. - </entry></row></tbody></tgroup></informaltable> - - <para> - Deletes the specified database, and all the documents and - attachments contained within it. - </para> - - <para> - To delete the database <literal moreinfo="none">recipes</literal> you would send - the request: - </para> - -<programlisting format="linespecific">DELETE http://couchdb:5984/recipes -Content-Type: application/json</programlisting> - - <para> - If successful, the returned JSON will indicate success - </para> - -<programlisting format="linespecific">{ - "ok" : true -}</programlisting> - - </section> - - <section id="couchdb-api-db_db-changes_get"> - - <title><literal moreinfo="none">GET /db/_changes</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_changes</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_changes</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the changes to the database - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">doc_ids</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the list of documents IDs to be filtered - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>json</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>none</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">feed</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Type of feed - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>normal</entry></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">continuous</literal></entry><entry>Continuous (non-polling) mode</entry></row><row><entry/><entry><literal moreinfo="none">longpoll</literal></entry><entry>Long polling mode</entry></row><row><entry/><entry><literal moreinfo="none">normal</literal></entry><entry>Normal mode</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">filter</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Filter function from a design document to get updates - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>none</entry></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">heartbeat</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Period after which an empty line is sent during longpoll or - continuous - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>60000</entry></row><row><entry/><entry><emphasis role="bold">Quantity</emphasis></entry><entry>milliseconds</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">include_docs</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the document with the result - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">limit</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Maximum number of rows rows to return - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>none</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">since</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Start the results from changes immediately after the - specified sequence number - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>0</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">timeout</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Maximum period to wait before the response is sent - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>60000</entry></row><row><entry/><entry><emphasis role="bold">Quantity</emphasis></entry><entry>milliseconds</entry></row></tbody></tgroup></informaltable> - - <para> - 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 <literal moreinfo="none">feed</literal> query argument. - </para> - - <para> - <itemizedlist> - - <listitem> - <para> - <emphasis role="bold">Poll</emphasis> - </para> - - <para> - 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 - </para> - -<programlisting format="linespecific">DELETE http://couchdb:5984/recipes/_changes -Content-Type: application/json</programlisting> - - <para> - Will get all of the changes in the database. You can request - a starting point using the <literal moreinfo="none">since</literal> 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 - <literal moreinfo="none">since</literal> parameter. - </para> - </listitem> - - <listitem> - <para> - <emphasis role="bold">Longpoll</emphasis> - </para> - - <para> - 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. - </para> - - <para> - Because the wait for a change can be significant you can set - a timeout before the connection is automatically closed (the - <literal moreinfo="none">timeout</literal> argument). You can also set a - heartbeat interval (using the <literal moreinfo="none">heartbeat</literal> - query argument), which sends a newline to keep the - connection open. - </para> - </listitem> - - <listitem> - <para> - <emphasis role="bold">Continuous</emphasis> - </para> - - <para> - 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. - </para> - - <para> - 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. - </para> - </listitem> - - </itemizedlist> - </para> - - <para> - The return structure for <literal moreinfo="none">normal</literal> and - <literal moreinfo="none">longpoll</literal> modes is a JSON array of changes - objects, and the last update sequence number. The structure is - described in the following table. - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db_db-json-changes" class="jsonstructure"><title> - Changes information for a database - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">last_seq</literal> </entry><entry> - Last change sequence number - </entry></row><row><entry><literal moreinfo="none">results</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Changes made to a database - </entry></row><row><entry> <literal moreinfo="none">changes</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - List of changes, field-by-field, for this document - </entry></row><row><entry> <literal moreinfo="none">id</literal> </entry><entry> - Document ID - </entry></row><row><entry> <literal moreinfo="none">seq</literal> </entry><entry> - Update sequence number - </entry></row></tbody></tgroup></table> - - <para> - The return format for <literal moreinfo="none">continuous</literal> mode the - server sends a CRLF (carriage-return, linefeed) delimited line for - each change. Each line contains the - <link linkend="table-couchdb-api-db_db-json-changes">JSON - object</link>. - </para> - - <para> - You can also request the full contents of each document change - (instead of just the change notification) by using the - <literal moreinfo="none">include_docs</literal> parameter. - </para> - - <section id="couchdb-api-db_db-changes_get-filters"> - - <title>Filtering</title> - - <para> - 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. - </para> - - <para> - You can also filter the <literal moreinfo="none">_changes</literal> 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 - <literal moreinfo="none">filter</literal> parameter, specifying the design - document name and filter name. For example: - </para> - -<programlisting format="linespecific">GET /db/_changes?filter=design_doc/filtername</programlisting> - - <para> - The <literal moreinfo="none">_changes</literal> feed can be used to watch - changes to specific document ID's or the list of - <literal moreinfo="none">_design</literal> documents in a database. If the - <literal moreinfo="none">filters</literal> parameter is set to - <literal moreinfo="none">_doc_ids</literal> a list of doc IDs can be passed in - the <option>doc_ids</option> parameter as a JSON array. - </para> - - <para> - For more information, see - <xref linkend="couchdb-single-changes-filters"/>. - </para> - - </section> - - </section> - - <section id="couchdb-api-db_db-compact_post"> - - <title><literal moreinfo="none">POST /db/_compact</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_compact</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_compact</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON success statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>202</entry><entry namest="info" nameend="addinfo"> - Compaction request has been accepted - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The requested content could not be found. The returned content - will include further information, as a JSON object, if available. - </entry></row></tbody></tgroup></informaltable> - - <para> - Request compaction of the specified database. Compaction - compresses the disk database file by performing the following - operations: - </para> - - <itemizedlist> - - <listitem> - <para> - 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. - </para> - </listitem> - - <listitem> - <para> - Removes old revisions of documents from the database, up to - the per-database limit specified by the - <literal moreinfo="none">_revs_limit</literal> database parameter. See - <xref linkend="couchdb-api-db_db_get"/> . - </para> - </listitem> - - </itemizedlist> - - <para> - 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. - </para> - - <para> - You can determine if the compaction process is operating on a - database by obtaining the database meta information, the - <literal moreinfo="none">compact_running</literal> value of the returned database - structure will be set to true. See - <xref linkend="couchdb-api-db_db_get"/> . - </para> - - <para> - You can also obtain a list of running processes to determine - whether compaction is currently running. See - <xref linkend="couchdb-api-misc_active-tasks_get"/>. - </para> - - </section> - - <section id="couchdb-api-db_db-compact-design-doc_post"> - - <title><literal moreinfo="none">POST /db/_compact/design-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_compact/design-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_compact/design-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON success statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">yes</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>202</entry><entry namest="info" nameend="addinfo"> - Compaction request has been accepted - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The requested content could not be found. The returned content - will include further information, as a JSON object, if available. - </entry></row></tbody></tgroup></informaltable> - - <para> - 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. - </para> - - <para> - For example, to compact the views associated with the - <literal moreinfo="none">recipes</literal> design document: - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/recipes/_compact/recipes -Content-Type: application/json</programlisting> - - <para> - CouchDB will immediately return with a status indicating that the - compaction request has been received (HTTP status code 202): - </para> - -<programlisting format="linespecific">{ - "ok" : true -}</programlisting> - - </section> - - <section id="couchdb-api-db_db-view-cleanup_post"> - - <title><literal moreinfo="none">POST /db/_view_cleanup</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_view_cleanup</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_view_cleanup</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON success statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">yes</entry></row></tbody></tgroup></informaltable> - - <para> - Cleans up the cached view output on disk for a given view. For - example: - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/recipes/_view_cleanup -Content-Type: application/json</programlisting> - - <para> - If the request is successful, a basic status message us returned: - </para> - -<programlisting format="linespecific">{ - "ok" : true -}</programlisting> - - </section> - - <section id="couchdb-api-db_db-ensure-full-commit_post"> - - <title><literal moreinfo="none">POST /db/_ensure_full_commit</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_ensure_full_commit</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_ensure_full_commit</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON success statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Commit completed successfully - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The requested content could not be found. The returned content - will include further information, as a JSON object, if available. - </entry></row></tbody></tgroup></informaltable> - - <para> - 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 <literal moreinfo="none">recipes</literal> you would use: - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/recipes/_ensure_full_commit -Content-Type: application/json</programlisting> - - <para> - This returns a status message, containing the success message and - the timestamp for when the CouchDB instance was started: - </para> - -<programlisting format="linespecific">{ - "ok" : true, - "instance_start_time" : "1288186189373361" -}</programlisting> - - - - </section> - - <section id="couchdb-api-db_db-bulk-docs_post"> - - <title><literal moreinfo="none">POST /db/_bulk_docs</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_bulk_docs</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_bulk_docs</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the docs and updates to be applied - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of updated documents - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document(s) have been created or updated - </entry></row></tbody></tgroup></informaltable> - - <para> - 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. - </para> - - <para> - For both inserts and updates the basic structure of the JSON is - the same: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db_db-bulk-docs-json" class="jsonstructure"><title> - Bulk Documents - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">all_or_nothing</literal> (optional) </entry><entry> - Sets the database commit mode to use all-or-nothing semantics - </entry></row><row><entry><literal moreinfo="none">docs</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Bulk Documents Document - </entry></row><row><entry> <literal moreinfo="none">_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry> <literal moreinfo="none">_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry> <literal moreinfo="none">_deleted</literal> (optional) </entry><entry> - Whether the document should be deleted - </entry></row></tbody></tgroup></table> - - <section id="couchdb-api-db_db-bulk-docs_post-insert"> - - <title>Inserting Documents in Bulk</title> - - <para> - 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. - </para> - - <para> - For example, the following inserts three new documents, two with - the supplied document IDs, and one which will have a document ID - generated: - </para> - -<programlisting format="linespecific">{ - "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" - }, - ] -}</programlisting> - - <para> - 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. - </para> - - <para> - The return structure from the example above contains a list of - the documents created, here with the combination and their - revision IDs: - </para> - -<programlisting format="linespecific">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", - } -]</programlisting> - - <para> - The content and structure of the returned JSON will depend on - the transaction semantics being used for the bulk update; see - <xref linkend="couchdb-api-db_db-bulk-docs_post-commit"/> - for more information. Conflicts and validation errors when - updating documents in bulk must be handled separately; see - <xref linkend="couchdb-api-db_db-bulk-docs_post-errors"/>. - </para> - - </section> - - <section id="couchdb-api-db_db-bulk-docs_post-update"> - - <title>Updating Documents in Bulk</title> - - <para> - 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. - </para> - - <para> - For example, you could send the following request: - </para> - -<programlisting format="linespecific">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" - } - ] -}</programlisting> - - <para> - The return structure is the JSON of the updated documents, with - the new revision and ID information: - </para> - -<programlisting format="linespecific">[ - { - "id" : "FishStew", - "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1" - }, - { - "id" : "LambStew", - "rev" : "2-0786321986194c92dd3b57dfbfc741ce" - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "rev" : "2-bdd3bf3563bee516b96885a66c743f8e" - } -]</programlisting> - - <para> - You can optionally delete documents during a bulk update by - adding the <literal moreinfo="none">_deleted</literal> field with a value of - <literal moreinfo="none">true</literal> to each docment ID/revision combination - within the submitted JSON structure. - </para> - - <para> - 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. - </para> - - <para> - The content and structure of the returned JSON will depend on - the transaction semantics being used for the bulk update; see - <xref linkend="couchdb-api-db_db-bulk-docs_post-commit"/> - for more information. Conflicts and validation errors when - updating documents in bulk must be handled separately; see - <xref linkend="couchdb-api-db_db-bulk-docs_post-errors"/>. - </para> - - </section> - - <section id="couchdb-api-db_db-bulk-docs_post-commit"> - - <title>Bulk Documents Transaction Semantics</title> - - <para> - 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: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal moreinfo="none">non-atomic</literal> - </para> - - <para> - 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. - </para> - - <para> - In this mode, the response structure will indicate whether - the document was updated by supplying the new - <literal moreinfo="none">_rev</literal> parameter indicating a new document - revision was created. If the update failed, then you will - get an <literal moreinfo="none">error</literal> of type - <literal moreinfo="none">conflict</literal>. For example: - </para> - -<programlisting format="linespecific">[ - { - "id" : "FishStew", - "error" : "conflict", - "reason" : "Document update conflict." - }, - { - "id" : "LambStew", - "error" : "conflict", - "reason" : "Document update conflict." - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "error" : "conflict", - "reason" : "Document update conflict." - } -]</programlisting> - - <para> - 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. - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">all-or-nothing</literal> - </para> - - <para> - 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. - </para> - - <para> - 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: - </para> - -<programlisting format="linespecific">[ - { - "id" : "FishStew", - "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1" - }, - { - "id" : "LambStew", - "rev" : "2-0786321986194c92dd3b57dfbfc741ce" - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "rev" : "2-bdd3bf3563bee516b96885a66c743f8e" - } -]</programlisting> - - <para> - 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 - <literal moreinfo="none">conflicts=true</literal> query argument when - accessing the view. Conflicts should be handled individually - to ensure the consistency of your database. - </para> - - - - <para> - To use this mode, you must include the - <literal moreinfo="none">all_or_nothing</literal> field (set to true) within - the main body of the JSON of the request. - </para> - </listitem> - - </itemizedlist> - - <para> - The effects of different database operations on the different - modes are summarized in the table below: - </para> - - <table id="table-couchdb-api-db_db-bulk-docs_post-commit"> - <title>Conflicts on Bulk Inserts</title> - <tgroup cols="4"> - <thead> - <row> - <entry> - Transaction Mode - </entry> - <entry> - Transaction - </entry> - <entry> - Cause - </entry> - <entry> - Resolution - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - Non-atomic - </entry> - <entry> - Insert - </entry> - <entry> - Requested document ID already exists - </entry> - <entry> - Resubmit with different document ID, or update the - existing document - </entry> - </row> - <row> - <entry> - Non-atomic - </entry> - <entry> - Update - </entry> - <entry> - Revision missing or incorrect - </entry> - <entry> - Resubmit with correct revision - </entry> - </row> - <row> - <entry> - All-or-nothing - </entry> - <entry> - Insert - </entry> - <entry> - Additional revision inserted - </entry> - <entry> - Resolve conflicted revisions - </entry> - </row> - <row> - <entry> - All-or-nothing - </entry> - <entry> - Update - </entry> - <entry> - Additional revision inserted - </entry> - <entry> - Resolve conflicted revisions - </entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - 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. - </para> - - </section> - - <section id="couchdb-api-db_db-bulk-docs_post-errors"> - - <title>Bulk Document Validation and Conflict Errors</title> - - <para> - The JSON returned by the <literal moreinfo="none">_bulk_docs</literal> 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. - </para> - - <para> - The exact structure of the returned information is shown in - <xref linkend="table-couchdb-api-db_db-bulk-docs-return-json"/>. - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db_db-bulk-docs-return-json" class="jsonstructure"><title> - Bulk Document Response - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">docs</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Bulk Docs Returned Documents - </entry></row><row><entry> <literal moreinfo="none">error</literal> </entry><entry> - Error type - </entry></row><row><entry> <literal moreinfo="none">id</literal> </entry><entry> - Document ID - </entry></row><row><entry> <literal moreinfo="none">reason</literal> </entry><entry> - Error string with extended reason - </entry></row></tbody></tgroup></table> - - <para> - When a document (or document revision) is not correctly comitted - to the database because of an error, you should check the - <literal moreinfo="none">error</literal> field to determine error type and - course of action. Errors will be one of the following type: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal moreinfo="none">conflict</literal> - </para> - - <para> - 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 - <literal moreinfo="none">all-or-nothing</literal> mode then you will need to - manually resolve the conflicted revisions of the document. - </para> - - <para> - Conflict resolution of documents added using the bulk docs - interface is identical to the resolution procedures used - when resolving conflict errors during replication. - </para> - - - </listitem> - - <listitem> - <para> - <literal moreinfo="none">forbidden</literal> - </para> - - <para> - Entries with this error type indicate that the validation - routine applied to the document during submission has - returned an error. - </para> - - <para> - For example, if your validation routine includes the - following: - </para> - -<programlisting format="linespecific">throw({forbidden: 'invalid recipe ingredient'});</programlisting> - - <para> - The error returned will be: - </para> - -<programlisting format="linespecific">{ - "id" : "7f7638c86173eb440b8890839ff35433", - "error" : "forbidden", - "reason" : "invalid recipe ingredient" -}</programlisting> - - <para> - For more information, see - <xref linkend="couchdb-api-functional-validation"/>. - </para> - </listitem> - - </itemizedlist> - - </section> - - </section> - - <section id="couchdb-api-db_db-temp-view_post"> - - <title><literal moreinfo="none">POST /db/_temp_view</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_temp_view</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_temp_view</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON with the temporary view definition - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Temporary view result set - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">yes</entry></row></tbody></tgroup></informaltable> - - <para> - Creates (and executes) a temporary view based on the view function - supplied in the JSON request. For example: - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/recipes/_temp_view -Content-Type: application/json - -{ - "map" : "function(doc) { if (doc.value > 9995) { emit(null, doc.value); } }" -}</programlisting> - - <para> - The resulting JSON response is the result from the execution of - the temporary view: - </para> - -<programlisting format="linespecific">{ - "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 -}</programlisting> - - <para> - 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. - </para> - - <para> - For more information, see - <xref linkend="couchdb-api-functional-views"/>. - </para> - - </section> - - <section id="couchdb-api-db_db-purge_post"> - - <title><literal moreinfo="none">POST /db/_purge</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_purge</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_purge</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the document IDs/revisions to be purged - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON structure with purged documents and purge sequence - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - 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. - </para> - - <para> - 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. - </para> - - <note> - <para> - Purging documents does not remove the space used by them on - disk. To reclaim disk space, you should run a database compact - (see <xref linkend="couchdb-api-db_db-compact_post"/>, and - compact views (see - <xref linkend="couchdb-api-db_db-compact-design-doc_post"/>). - </para> - </note> - - <para> - To perform a purge operation you must send a request including the - JSON of the document IDs that you want to purge. For example: - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/recipes/_purge -Content-Type: application/json - -{ - "FishStew" : [ - "17-b3eb5ac6fbaef4428d712e66483dcb79" - ] -}</programlisting> - - <para> - The format of the request must include the document ID and one or - more revisions that must be purged. - </para> - - <para> - The response will contain the purge sequence number, and a list of - the document IDs and revisions successfully purged. - </para> - -<programlisting format="linespecific">{ - "purged" : { - "FishStew" : [ - "17-b3eb5ac6fbaef4428d712e66483dcb79" - ] - }, - "purge_seq" : 11 -}</programlisting> - - <section id="couchdb-api-db_db-purge_post-indexrebuild"> - - <title>Updating Indexes</title> - - <para> - 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. - </para> - - <para> - 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. - </para> - - <para> - 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. - </para> - - </section> - - </section> - - <section id="couchdb-api-db_db-all-docs_get"> - - <title><literal moreinfo="none">GET /db/_all_docs</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_all_docs</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_all_docs</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON object containing document information, ordered by the - document ID - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">descending</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return the documents in descending by key order - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">endkey</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Stop returning records when the specified key is reached - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">endkey_docid</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Stop returning records when the specified document ID is - reached - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">group</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Group the results using the reduce function to a group or - single row - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">group_level</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the group level to be used - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">include_docs</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the full content of the documents in the return - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">inclusive_end</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specifies whether the specified end key should be included - in the result - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>true</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">key</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return only documents that match the specified key - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">limit</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Limit the number of the returned documents to the specified - number - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">reduce</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Use the reduction function - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>true</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">skip</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Skip this number of records before starting to return the - results - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>0</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">stale</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Allow the results from a stale view to be used - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry/></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">ok</literal></entry><entry>Allow stale views</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">startkey</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return records starting with the specified key - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">startkey_docid</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return records starting with the specified document ID - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">update_seq</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the update sequence in the generated results - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row></tbody></tgroup></informaltable> - - <para> - 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. - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db_db-all-docs" class="jsonstructure"><title> - All Database Documents - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">offset</literal> </entry><entry> - Offset where the document list started - </entry></row><row><entry><literal moreinfo="none">rows</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Array of document object - </entry></row><row><entry><literal moreinfo="none">total_rows</literal> </entry><entry> - Number of documents in the database/view - </entry></row><row><entry><literal moreinfo="none">update_seq</literal> (optional) </entry><entry> - Current update sequence for the database - </entry></row></tbody></tgroup></table> - - <para> - By default the information returned contains only the document ID - and revision. For example, the request: - </para> - -<programlisting role="httprequest" format="linespecific">GET http://couchdb:5984/recipes/_all_docs -Accept: application/json</programlisting> - - <para> - Returns the following structure: - </para> - -<programlisting role="httpresponse" format="linespecific">{ - "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 -}</programlisting> - - <para> - 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. - </para> - - - - </section> - - <section id="couchdb-api-db_db-all-docs_post"> - - <title><literal moreinfo="none">POST /db/_all_docs</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_all_docs</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_all_docs</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the document IDs you want included - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the returned view - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - The <literal moreinfo="none">POST</literal> to <literal moreinfo="none">_all_docs</literal> 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 - <xref linkend="couchdb-api-dbdoc_db-doc_get"/> requests. - </para> - - <para> - The request body should contain a list of the keys to be returned - as an array to a <literal moreinfo="none">keys</literal> object. For example: - </para> - -<programlisting role="httprequest" format="linespecific">POST http://couchdb:5984/recipes/_all_docs -User-Agent: MyApp/0.1 libwww-perl/5.837 - -{ - "keys" : [ - "Zingylemontart", - "Yogurtraita" - ] -}</programlisting> - - <para> - The return JSON is the all documents structure, but with only the - selected keys in the output: - </para> - -<programlisting role="httpresponse" format="linespecific">{ - "total_rows" : 2666, - "rows" : [ - { - "value" : { - "rev" : "1-a3544d296de19e6f5b932ea77d886942" - }, - "id" : "Zingylemontart", - "key" : "Zingylemontart" - }, - { - "value" : { - "rev" : "1-91635098bfe7d40197a1b98d7ee085fc" - }, - "id" : "Yogurtraita", - "key" : "Yogurtraita" - } - ], - "offset" : 0 -}</programlisting> - - - - </section> - - <section id="couchdb-api-db_db-missing-revs_post"> - - <title><literal moreinfo="none">POST /db/_missing_revs</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_missing_revs</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_missing_revs</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON list of document revisions - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of missing revisions - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-db_db-revs-diff_post"> - - <title><literal moreinfo="none">POST /db/_revs_diff</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_revs_diff</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_revs_diff</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON list of document and revisions - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON list of differences from supplied document/revision list - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-db_db-security_get"> - - <title><literal moreinfo="none">GET /db/_security</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_security</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_security</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the security object - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Gets the current secrity object from the specified database. The - security object consists of two compulsory elements, - <literal moreinfo="none">admins</literal> and <literal moreinfo="none">readers</literal>, 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. - </para> - - <para> - To get the existing security object you would send the following - request: - </para> - -<programlisting format="linespecific">{ - "admins" : { - "roles" : [], - "names" : [ - "mc", - "slp" - ] - }, - "readers" : { - "roles" : [], - "names" : [ - "tim", - "brian" - ] - } -}</programlisting> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db-json-security" class="jsonstructure"><title> - Security Object - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">admins</literal> </entry><entry> - Roles/Users with admin privileges - </entry></row><row><entry> <literal moreinfo="none">roles</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - List of roles with parent privilege - </entry></row><row><entry> <literal moreinfo="none">users</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - List of users with parent privilege - </entry></row><row><entry><literal moreinfo="none">readers</literal> </entry><entry> - Roles/Users with reader privileges - </entry></row><row><entry> <literal moreinfo="none">roles</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - List of roles with parent privilege - </entry></row><row><entry> <literal moreinfo="none">users</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - List of users with parent privilege - </entry></row></tbody></tgroup></table> - - <note> - <para> - If the security object for a database has never beent set, then - the value returned will be empty. - </para> - </note> - - </section> - - <section id="couchdb-api-db_db-security_put"> - - <title><literal moreinfo="none">PUT /db/_security</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/_security</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /db/_security</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON specifying the admin and user security for the database - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON status message - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Sets the security object for the given database.For example, to - set the security object for the <literal moreinfo="none">recipes</literal> - database: - </para> - -<programlisting format="linespecific">PUT http://couchdb:5984/recipes/_security -Content-Type: application/json - -{ - "admins" : { - "roles" : [], - "names" : [ - "mc", - "slp" - ] - }, - "readers" : { - "roles" : [], - "names" : [ - "tim", - "brian" - ] - } -}</programlisting> - - <para> - If the setting was successful, a JSON status object will be - returned: - </para> - -<programlisting format="linespecific">{ - "ok" : true -}</programlisting> - - </section> - - <section id="couchdb-api-db_db-revs-limit_get"> - - <title><literal moreinfo="none">GET /db/_revs_limit</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_revs_limit</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_revs_limit</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - The current revision limit setting - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Gets the current <literal moreinfo="none">revs_limit</literal> (revision limit) - setting. - </para> - - <para> - For example to get the current limit: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/recipes/_revs_limit -Content-Type: application/json</programlisting> - - <para> - The returned information is the current setting as a numerical - scalar: - </para> - -<programlisting format="linespecific">1000</programlisting> - - </section> - - <section id="couchdb-api-db_db-revs-limit_put"> - - <title><literal moreinfo="none">PUT /db/_revs_limit</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/_revs_limit</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /db/_revs_limit</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - A scalar integer of the revision limit setting - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Confirmation of setting of the revision limit - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - 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 <literal moreinfo="none">PUT</literal> with - a scalar integer of the limit that you want to set as the request - body. - </para> - - <para> - For example to set the revs limit to 100 for the - <literal moreinfo="none">recipes</literal> database: - </para> - -<programlisting format="linespecific">PUT http://couchdb:5984/recipes/_revs_limit -Content-Type: application/json - -100</programlisting> - - <para> - If the setting was successful, a JSON status object will be - returned: - </para> - -<programlisting format="linespecific">{ - "ok" : true -}</programlisting> - - </section> - -</chapter> - - <chapter id="couchdb-api-dbdoc"> - - <title>CouchDB API Server Document Methods</title> - - <para> - The CouchDB API Server Document methods detail how to create, read, - update and delete documents within a database. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-dbdoc-summary"><title>Document API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-dbdoc_db_post"> - Create a new document - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/doc</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc_get"> - Returns the latest revision of the document - </link></entry></row><row><entry><literal moreinfo="none">HEAD</literal></entry><entry><literal moreinfo="none">/db/doc</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc_head"> - Returns bare information in the HTTP Headers for the document - </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/doc</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc_put"> - Inserts a new document, or new version of an existing document - </link></entry></row><row><entry><literal moreinfo="none">DELETE</literal></entry><entry><literal moreinfo="none">/db/doc</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc_delete"> - Deletes the document - </link></entry></row><row><entry><literal moreinfo="none">COPY</literal></entry><entry><literal moreinfo="none">/db/doc</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc_copy"> - Copies the document - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/doc/attachment</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc-attachment_get"> - Gets the attachment of a document - </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/doc/attachment</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc-attachment_put"> - Adds an attachment of a document - </link></entry></row><row><entry><literal moreinfo="none">DELETE</literal></entry><entry><literal moreinfo="none">/db/doc/attachment</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc-attachment_delete"> - Deletes an attachment of a document - </link></entry></row></tbody></tgroup></table> - - <section id="couchdb-api-dbdoc_db_post"> - - <title><literal moreinfo="none">POST /db</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the new document - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON with the committed document information - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">batch</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Allow document store request to be batched with others - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">ok</literal></entry><entry>Enable</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document has been created successfully - </entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Conflict - a document with the specified document ID already - exists - </entry></row></tbody></tgroup></informaltable> - - <para> - Create a new document in the specified database, using the - supplied JSON document structure. If the JSON structure includes - the <literal moreinfo="none">_id</literal> field, then the document will be - created with the specified document ID. If the - <literal moreinfo="none">_id</literal> field is not specified, a new unique ID - will be generated. - </para> - - <para> - For example, you can generate a new document with a generated UUID - using the following request: - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/recipes/ -Content-Type: application/json - -{ - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" -}</programlisting> - - <para> - The return JSON will specify the automatically enerated ID and - revision information: - </para> - -<programlisting format="linespecific">{ - "id" : "64575eef70ab90a2b8d55fc09e00440d", - "ok" : true, - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -}</programlisting> - - <section id="couchdb-api-dbdoc_db_post-docid"> - - <title>Specifying the Document ID</title> - - <para> - The document ID can be specified by including the - <literal moreinfo="none">_id</literal> field in the JSON of the submitted - record. The following request will create the same document with - the ID <literal moreinfo="none">FishStew</literal>: - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/recipes/ -Content-Type: application/json - -{ - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" -}</programlisting> - - <para> - The structure of the submitted document is as shown in the table - below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-json-document" class="jsonstructure"><title> - CouchDB Document - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry><literal moreinfo="none">_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row></tbody></tgroup></table> - - <para> - In either case, the returned JSON will specify the document ID, - revision ID, and status message: - </para> - -<programlisting format="linespecific">{ - "id" : "FishStew", - "ok" : true, - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -}</programlisting> - - </section> - - <section id="couchdb-api-dbdoc_db_batchmode"> - - <title>Batch Mode Writes</title> - - <para> - You can write documents to the database at a higher rate by - using the batch option. This collects document writes together - in memory (on a user-by-user basis) before they are committed to - disk. This increases the risk of the documents not being stored - in the event of a failure, since the documents are not written - to disk immediately. - </para> - - <para> - To use the batched mode, append the <literal moreinfo="none">batch=ok</literal> - query argument to the URL of the <literal moreinfo="none">PUT</literal> or - <literal moreinfo="none">POST</literal> request. The CouchDB server will respond - with a 202 HTTP response code immediately. - </para> - - </section> - - <section id="couchdb-api-dbdoc_db-doc-attachments"> - - <title>Including Attachments</title> - - <para> - You can include one or more attachments with a given document by - incorporating the attachment information within the JSON of the - document. This provides a simpler alternative to loading - documents with attachments than making a separate call (see - <xref linkend="couchdb-api-dbdoc_db-doc-attachment_put"/>). - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-dbdoc-documentattachments" class="jsonstructure"><title> - Document with Attachments - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry><literal moreinfo="none">_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry><literal moreinfo="none">_attachments</literal> (optional) </entry><entry> - Document Attachment - </entry></row><row><entry> <literal moreinfo="none">filename</literal> </entry><entry> - Attachment information - </entry></row><row><entry> <literal moreinfo="none">content_type</literal> </entry><entry> - MIME Content type string - </entry></row><row><entry> <literal moreinfo="none">data</literal> </entry><entry> - File attachment content, Base64 encoded - </entry></row></tbody></tgroup></table> - - <para> - The <literal moreinfo="none">filename</literal> will be the attachment name. For - example, when sending the JSON structure below: - </para> - -<programlisting format="linespecific">{ - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" - "_attachments" : { - "styling.css" : { - "content-type" : "text/css", - "data" : "cCB7IGZvbnQtc2l6ZTogMTJwdDsgfQo=", - }, - }, -}</programlisting> - - <para> - The attachment <literal moreinfo="none">styling.css</literal> can be accessed - using <literal moreinfo="none">/recipes/FishStew/styling.css</literal>. For more - information on attachments, see - <xref linkend="couchdb-api-dbdoc_db-doc-attachment_get"/>. - </para> - - <para> - The document data embedded in to the structure must be encoded - using base64. - </para> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_get"> - - <title><literal moreinfo="none">GET /db/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Returns the JSON for the document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">conflicts</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Returns the conflict tree for the document. - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">true</literal></entry><entry>Includes the revisions</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the revision to return - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">true</literal></entry><entry>Includes the revisions</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">revs</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of the revisions for the document - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">revs_info</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of detailed revision information for the - document - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">true</literal></entry><entry>Includes the revisions</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document created - </entry></row><row><entry>400</entry><entry namest="info" nameend="addinfo"> - The format of the request or revision was invalid - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The specified document or revision cannot be found, or has been - deleted - </entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Conflict - a document with the specified document ID already - exists - </entry></row></tbody></tgroup></informaltable> - - <para> - Returns the specified <literal moreinfo="none">doc</literal> from the specified - <literal moreinfo="none">db</literal>. For example, to retrieve the document with - the id <literal moreinfo="none">FishStew</literal> you would send the following - request: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/recipes/FishStew -Content-Type: application/json -Accept: application/json</programlisting> - - <para> - The returned JSON is the JSON of the document, including the - document ID and revision number: - </para> - -<programlisting format="linespecific">{ - "_id" : "FishStew", - "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c", - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "title" : "Irish Fish Stew" -}</programlisting> - - <para> - Unless you request a specific revision, the latest revision of the - document will always be returned. - </para> - - <section id="couchdb-api-dbdoc_db-doc_get-attachments"> - - <title>Attachments</title> - - <para> - If the document includes attachments, then the returned - structure will contain a summary of the attachments associatd - with the document, but not the attachment data itself. - </para> - - <para> - The JSON for the returned document will include the - <literal moreinfo="none">_attachments</literal> field, with one or more - attachment definitions. For example: - </para> - -<programlisting format="linespecific">{ - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" - "_attachments" : { - "styling.css" : { - "stub" : true, - "content-type" : "text/css", - "length" : 783426, - }, - }, -}</programlisting> - - <para> - The format of the returned JSON is shown in the table below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-dbdoc-returneddocumentattachments" class="jsonstructure"><title> - Returned Document with Attachments - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry><literal moreinfo="none">_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry><literal moreinfo="none">_attachments</literal> (optional) </entry><entry> - Document Attachment - </entry></row><row><entry> <literal moreinfo="none">filename</literal> </entry><entry> - Attachment - </entry></row><row><entry> <literal moreinfo="none">content_type</literal> </entry><entry> - MIME Content type string - </entry></row><row><entry> <literal moreinfo="none">length</literal> </entry><entry> - Length (bytes) of the attachment data - </entry></row><row><entry> <literal moreinfo="none">revpos</literal> </entry><entry> - Revision where this attachment exists - </entry></row><row><entry> <literal moreinfo="none">stub</literal> </entry><entry> - Indicates whether the attachment is a stub - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_get-revs"> - - <title>Getting a List of Revisions</title> - - <para> - You can obtain a list of the revisions for a given document by - adding the <literal moreinfo="none">revs=true</literal> parameter to the request - URL. For example: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/recipes/FishStew?revs=true -Accept: application/json</programlisting> - - <para> - The returned JSON structure includes the original document, - including a <literal moreinfo="none">_revisions</literal> structure that - includes the revision information: - </para> - -<programlisting format="linespecific">{ - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "_id" : "FishStew", - "title" : "Irish Fish Stew", - "_revisions" : { - "ids" : [ - "a1a9b39ee3cc39181b796a69cb48521c", - "7c4740b4dcf26683e941d6641c00c39d", - "9c65296036141e575d32ba9c034dd3ee" - ], - "start" : 3 - }, - "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" -}</programlisting> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-dbdoc-document_with_revs" class="jsonstructure"><title> - Returned CouchDB Document with Revision Info - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry><literal moreinfo="none">_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry><literal moreinfo="none">_revisions</literal> </entry><entry> - CouchDB Document Revisions - </entry></row><row><entry> <literal moreinfo="none">ids</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Array of valid revision IDs, in reverse order (latest first) - </entry></row><row><entry> <literal moreinfo="none">start</literal> </entry><entry> - Prefix number for the latest revision - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_get-revsextended"> - - <title>Obtaining an Extended Revision History</title> - - <para> - You can get additional information about the revisions for a - given document by supplying the <literal moreinfo="none">revs_info</literal> - argument to the query: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/recipes/FishStew?revs_info=true -Accept: application/json</programlisting> - - <para> - This returns extended revision information, including the - availability and status of each revision: - </para> - -<programlisting format="linespecific">{ - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "_id" : "FishStew", - "_revs_info" : [ - { - "status" : "available", - "rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" - }, - { - "status" : "available", - "rev" : "2-7c4740b4dcf26683e941d6641c00c39d" - }, - { - "status" : "available", - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" - } - ], - "title" : "Irish Fish Stew", - "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" -}</programlisting> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-dbdoc-document_with_revs_info" class="jsonstructure"><title> - Returned CouchDB Document with Detailed Revision Info - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry><literal moreinfo="none">_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry><literal moreinfo="none">_revs_info</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - CouchDB Document Extended Revision Info - </entry></row><row><entry> <literal moreinfo="none">rev</literal> </entry><entry> - Full revision string - </entry></row><row><entry> <literal moreinfo="none">status</literal> </entry><entry> - Status of the revision - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_get-specrev"> - - <title>Obtaining a Specific Revision</title> - - <para> - To get a specific revision, use the <literal moreinfo="none">rev</literal> - argument to the request, and specify the full revision number: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d -Accept: application/json</programlisting> - - <para> - The specified revision of the document will be returned, - including a <literal moreinfo="none">_rev</literal> field specifying the - revision that was requested: - </para> - -<programlisting format="linespecific">{ - "_id" : "FishStew", - "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d", - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "title" : "Fish Stew" -}</programlisting> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_head"> - - <title><literal moreinfo="none">HEAD /db/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API HEAD /db/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">HEAD /db/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the revision to return - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">revs</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of the revisions for the document - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">revs_info</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of detailed revision information for the - document - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The specified document or revision cannot be found, or has been - deleted - </entry></row></tbody></tgroup></informaltable> - - <para> - Returns the HTTP Headers containing a minimal amount of - information about the specified document. The method supports the - same query arguments as the <literal moreinfo="none">GET</literal> method, but - only the header information (including document size, and the - revision as an ETag), is returned. For example, a simple - <literal moreinfo="none">HEAD</literal> request: - </para> - -<programlisting format="linespecific">HEAD http://couchdb:5984/recipes/FishStew -Content-Type: application/json</programlisting> - - <para> - Returns the following HTTP Headers: - </para> - -<programlisting format="linespecific">HTTP/1.1 200 OK -Server: CouchDB/1.0.1 (Erlang OTP/R13B) -Etag: "7-a19a1a5ecd946dad70e85233ba039ab2" -Date: Fri, 05 Nov 2010 14:54:43 GMT -Content-Type: text/plain;charset=utf-8 -Content-Length: 136 -Cache-Control: must-revalidate</programlisting> - - <para> - The <literal moreinfo="none">Etag</literal> header shows the current revision for - the requested document, and the <literal moreinfo="none">Content-Length</literal> - specifies the length of the data, if the document were requested - in full. - </para> - - <para> - Adding any of the query arguments (as supported by - <link linkend="couchdb-api-dbdoc_db-doc_get"><literal moreinfo="none">GET</literal></link> - method), then the resulting HTTP Headers will correspond to what - would be returned. Note that the current revision is not returned - when the <literal moreinfo="none">refs_info</literal> argument is used. For - example: - </para> - -<programlisting format="linespecific">HTTP/1.1 200 OK -Server: CouchDB/1.0.1 (Erlang OTP/R13B) -Date: Fri, 05 Nov 2010 14:57:16 GMT -Content-Type: text/plain;charset=utf-8 -Content-Length: 609 -Cache-Control: must-revalidate</programlisting> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_put"> - - <title><literal moreinfo="none">PUT /db/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /db/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the new document, or updated version of the existed - document - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the document ID and revision - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">batch</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Allow document store request to be batched with others - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">ok</literal></entry><entry>Enable</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">If-Match</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry/><entry/></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document has been created successfully - </entry></row><row><entry>202</entry><entry namest="info" nameend="addinfo"> - Document accepted for writing (batch mode) - </entry></row></tbody></tgroup></informaltable> - - <para> - The <literal moreinfo="none">PUT</literal> method creates a new named document, or - creates a new revision of the existing document. Unlike the - <link linkend="couchdb-api-dbdoc_db_post"><literal moreinfo="none">POST</literal></link> - method, you must specify the document ID in the request URL. - </para> - - <para> - For example, to create the docment <literal moreinfo="none">FishStew</literal>, - you would send the following request: - </para> - -<programlisting format="linespecific">PUT http://couchdb:5984/recipes/FishStew -Content-Type: application/json - -{ - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" -}</programlisting> - - <para> - The return type is JSON of the status, document ID,and revision - number: - </para> - -<programlisting format="linespecific">{ - "id" : "FishStew", - "ok" : true, - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -}</programlisting> - - <section id="couchdb-api-dbdoc_db-doc_put-update"> - - <title>Updating an Existing Document</title> - - <para> - To update an existing document you must specify the current - revision number within the <literal moreinfo="none">_rev</literal> parameter. - For example: - </para> - -<programlisting format="linespecific">PUT http://couchdb:5984/recipes/FishStew -Content-Type: application/json - -{ - "_rev" : "1-9c65296036141e575d32ba9c034dd3ee", - "servings" : 4, - "subtitle" : "Delicious with fresh salad", - "title" : "Fish Stew" -}</programlisting> - - <para> - Alternatively, you can supply the current revision number in the - <literal moreinfo="none">If-Match</literal> HTTP header of the request. For - example: - </para> - -<programlisting format="linespecific">PUT http://couchdb:5984/recipes/FishStew -If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea -Content-Type: application/json - -{ - "servings" : 4, - "subtitle" : "Delicious with fresh salad", - "title" : "Fish Stew" -}</programlisting> - - <para> - The JSON returned will include the updated revision number: - </para> - -<programlisting format="linespecific">{ - "id" : "FishStew99", - "ok" : true, - "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea" -}</programlisting> - - <para> - For information on batched writes, which can provide improved - performance, see - <xref linkend="couchdb-api-dbdoc_db_batchmode"/>. - </para> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_delete"> - - <title><literal moreinfo="none">DELETE /db/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API DELETE /db/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">DELETE /db/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the deleted revision - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current revision of the document for validation - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">If-Match</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry/><entry/></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Revision is missing, invalid or not the latest - </entry></row></tbody></tgroup></informaltable> - - <para> - Deletes the specified document from the database. You must supply - the current (latest) revision, either by using the - <literal moreinfo="none">rev</literal> parameter to specify the revision: - </para> - -<programlisting format="linespecific">DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c -Content-Type: application/json</programlisting> - - <para> - Alternatively, you can use ETags with the - <literal moreinfo="none">If-Match</literal> field: - </para> - -<programlisting format="linespecific">DELETE http://couchdb:5984/recipes/FishStew -If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c -Content-Type: application/json</programlisting> - - <para> - The returned JSON contains the document ID, revision and status: - </para> - -<programlisting format="linespecific">{ - "id" : "FishStew", - "ok" : true, - "rev" : "4-2719fd41187c60762ff584761b714cfb" -}</programlisting> - - <note> - <para> - Note that deletion of a record increments the revision number. - The use of a revision for deletion of the record allows - replication of the database to correctly track the deletion in - synchronized copies. - </para> - </note> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_copy"> - - <title><literal moreinfo="none">COPY /db/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API COPY /db/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">COPY /db/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the new document and revision - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Revision to copy from - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">Destination</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Destination document (and optional revision)</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry/><entry/><entry/></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document has been copied and created successfully - </entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Conflict (target document already exists) - </entry></row></tbody></tgroup></informaltable> - - <para> - The <literal moreinfo="none">COPY</literal> command (which is non-standard HTTP) - copies an existing document to a new or existing document. - </para> - - <para> - The source document is specified on the request line, with the - <literal moreinfo="none">Destination</literal> HTTP Header of the request - specifying the target document. - </para> - - <section id="couchdb-api-dbdoc_db-doc_copy-simple"> - - <title>Copying a Document</title> - - <para> - You can copy the latest version of a document to a new document - by specifying the current document and target document: - </para> - -<programlisting format="linespecific">COPY http://couchdb:5984/recipes/FishStew -Content-Type: application/json -Destination: IrishFishStew</programlisting> - - <para> - The above request copies the document - <literal moreinfo="none">FishStew</literal> to the new document - <literal moreinfo="none">IrishFishStew</literal>. The response is the ID and - revision of the new document. - </para> - -<programlisting format="linespecific">{ - "id" : "IrishFishStew", - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -}</programlisting> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_copy-specrev"> - - <title>Copying from a Specific Revision</title> - - <para> - To copy <emphasis>from</emphasis> a specific version, use the - <literal moreinfo="none">rev</literal> argument to the query string: - </para> - -<programlisting format="linespecific">COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082 -Content-Type: application/json -Destination: IrishFishStew</programlisting> - - <para> - The new document will be created using the information in the - specified revision of the source document. - </para> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_copy-existing"> - - <title>Copying to an Existing Document</title> - - <para> - To copy to an existing document, you must specify the current - revision string for the target document, using the - <literal moreinfo="none">rev</literal> parameter to the - <literal moreinfo="none">Destination</literal> HTTP Header string. For example: - </para> - -<programlisting format="linespecific">COPY http://couchdb:5984/recipes/FishStew -Content-Type: application/json -Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee</programlisting> - - <para> - The return value will be the new revision of the copied - document: - </para> - -<programlisting format="linespecific">{ - "id" : "IrishFishStew", - "rev" : "2-55b6a1b251902a2c249b667dab1c6692" -}</programlisting> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc-attachment_get"> - - <title><literal moreinfo="none">GET /db/doc/attachment</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/doc/attachment</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/doc/attachment</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Returns the document data - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Returns the file attachment <literal moreinfo="none">attachment</literal> - associated with the document <literal moreinfo="none">doc</literal>. The raw data - of the associated attachment is returned (just as if you were - accessing a static file. The returned HTTP - <literal moreinfo="none">Content-type</literal> will be the same as the content - type set when the document attachment was submitted into the - database. - </para> - - </section> - - <section id="couchdb-api-dbdoc_db-doc-attachment_put"> - - <title><literal moreinfo="none">PUT /db/doc/attachment</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/doc/attachment</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /db/doc/attachment</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - Raw document data - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON document status - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current document revision - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">Content-Length</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Length (bytes) of the attachment being uploaded</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">Content-Type</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>MIME type for the uploaded attachment</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">If-Match</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry/><entry/></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Attachment has been accepted - </entry></row></tbody></tgroup></informaltable> - - <para> - Upload the supplied content as an attachment to the specified - document (<literal moreinfo="none">doc</literal>). The - <literal moreinfo="none">attachment</literal> name provided must be a URL encoded - string. You must also supply either the <literal moreinfo="none">rev</literal> - query argument or the <literal moreinfo="none">If-Match</literal> HTTP header for - validation, and the HTTP headers (to set the attacment content - type). The content type is used when the attachment is requested - as the corresponding content-type in the returned document header. - </para> - - <para> - For example, you could upload a simple text document using the - following request: - </para> - -<programlisting format="linespecific">PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca -Content-Length: 10 -Content-Type: text/plain - -Roast it</programlisting> - - <para> - Or by using the <literal moreinfo="none">If-Match</literal> HTTP header: - </para> - -<programlisting format="linespecific">PUT http://couchdb:5984/recipes/FishStew/basic -If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca -Content-Length: 10 -Content-Type: text/plain - -Roast it</programlisting> - - <para> - The returned JSON contains the new document information: - </para> - -<programlisting format="linespecific">{ - "id" : "FishStew", - "ok" : true, - "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74" -}</programlisting> - - <note> - <para> - Uploading an attachment updates the corresponding document - revision. Revisions are tracked for the parent document, not - individual attachments. - </para> - </note> - - <section id="couchdb-api-dbdoc_db-doc-attachment_put-existing"> - - <title>Updating an Existing Attachment</title> - - <para> - Uploading an attachment using an existing attachment name will - update the corresponding stored content of the database. Since - you must supply the revision information to add an attachment to - a document, this serves as validation to update the existing - attachment. - </para> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc-attachment_delete"> - - <title><literal moreinfo="none">DELETE /db/doc/attachment</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API DELETE /db/doc/attachment</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">DELETE /db/doc/attachment</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON status - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Revision of the document to be deleted - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">If-Match</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry/><entry/></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Attachment deleted successfully - </entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Supplied revision is incorrect or missing - </entry></row></tbody></tgroup></informaltable> - - <para> - Deletes the attachment <literal moreinfo="none">attachment</literal> to the - specified <literal moreinfo="none">doc</literal>. You must supply the - <literal moreinfo="none">rev</literal> argument with the current revision to - delete the attachment. - </para> - - <para> - For example to delete the attachment <literal moreinfo="none">basic</literal> from - the recipe <literal moreinfo="none">FishStew</literal>: - </para> - -<programlisting format="linespecific">DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74 -Content-Type: application/json</programlisting> - - <para> - The returned JSON contains the updated revision information: - </para> - -<programlisting format="linespecific">{ - "id" : "FishStew", - "ok" : true, - "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e" -}</programlisting> - - </section> - -</chapter> - - <chapter id="couchdb-api-localdb"> - - <title>CouchDB API Server Local (non-replicating) Document Methods</title> - - <para> - The Local (non-replicating) document interface allows you to create - local documents that are not replicated to other databases. These - documents can be used to hold configuration or other information - that is required specifically on the local CouchDB instance. - </para> - - <para> - Local documents have the following limitations: - </para> - - <itemizedlist> - - <listitem> - <para> - Local documents are not replicated to other databases. - </para> - </listitem> - - <listitem> - <para> - The ID of the local document must be known for the document to - accessed. You cannot obtain a list of local documents from the - database. - </para> - </listitem> - - <listitem> - <para> - Local documents are not output by views, or the - <literal moreinfo="none">_all_docs</literal> view. - </para> - </listitem> - - </itemizedlist> - - <para> - Local documents can be used when you want to store configuration or - other information for the curent (local) instance of a given - database. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-api-localdb-summary"><title>Local (non-replicating) Document API - Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_local/local-doc</literal></entry><entry><link linkend="couchdb-api-localdb_db-local-localdoc_get"> - Returns the latest revision of the non-replicated document - </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/_local/local-doc</literal></entry><entry><link linkend="couchdb-api-localdb_db-local-localdoc_put"> - Inserts a new version of the non-replicated document - </link></entry></row><row><entry><literal moreinfo="none">DELETE</literal></entry><entry><literal moreinfo="none">/db/_local/local-doc</literal></entry><entry><link linkend="couchdb-api-localdb_db-local-localdoc_delete"> - Deletes the non-replicated document - </link></entry></row><row><entry><literal moreinfo="none">COPY</literal></entry><entry><literal moreinfo="none">/db/_local/local-doc</literal></entry><entry><link linkend="couchdb-api-localdb_db-local-localdoc_copy"> - Copies the non-replicated document - </link></entry></row></tbody></tgroup></table> - - <section id="couchdb-api-localdb_db-local-localdoc_get"> - - <title><literal moreinfo="none">GET /db/_local/local-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_local/local-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_local/local-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the returned document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the revision to return - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">true</literal></entry><entry>Includes the revisions</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">revs</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of the revisions for the document - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">revs_info</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of detailed revision information for the - document - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">true</literal></entry><entry>Includes the revisions</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>400</entry><entry namest="info" nameend="addinfo"> - The format of the request or revision was invalid - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The specified document or revision cannot be found, or has been - deleted - </entry></row></tbody></tgroup></informaltable> - - <para> - Gets the specified local document. The semantics are identical to - accessing a standard document in the specified database, except - that the document is not replicated. See - <xref linkend="couchdb-api-dbdoc_db-doc_get"/>. - </para> - - </section> - - <section id="couchdb-api-localdb_db-local-localdoc_put"> - - <title><literal moreinfo="none">PUT /db/_local/local-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/_local/local-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /db/_local/local-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the document - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON with the committed document information - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document has been created successfully - </entry></row></tbody></tgroup></informaltable> - - <para> - Stores the specified local document. The semantics are identical - to storing a standard document in the specified database, except - that the document is not replicated. See - <xref linkend="couchdb-api-dbdoc_db-doc_put"/>. - </para> - - </section> - - <section id="couchdb-api-localdb_db-local-localdoc_delete"> - - <title><literal moreinfo="none">DELETE /db/_local/local-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API DELETE /db/_local/local-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">DELETE /db/_local/local-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON with the deleted document information - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current revision of the document for validation - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">If-Match</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry/><entry/></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Supplied revision is incorrect or missing - </entry></row></tbody></tgroup></informaltable> - - <para> - Deletes the specified local document. The semantics are identical - to deleting a standard document in the specified database, except - that the document is not replicated. See - <xref linkend="couchdb-api-dbdoc_db-doc_delete"/>. - </para> - - </section> - - <section id="couchdb-api-localdb_db-local-localdoc_copy"> - - <title><literal moreinfo="none">COPY /db/_local/local-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API COPY /db/_local/local-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">COPY /db/_local/local-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the copied document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Revision to copy from - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">Destination</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Destination document (and optional revision)</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry/><entry/><entry/></row></tbody></tgroup></informaltable> - - <para> - Copies the specified local document. The semantics are identical - to copying a standard document in the specified database, except - that the document is not replicated. See - <xref linkend="couchdb-api-dbdoc_db-doc_copy"/>. - </para> - - </section> - -</chapter> - - <chapter id="couchdb-api-design"> - - <title>CouchDB API Server Design Document Methods</title> - - <para> - In CouchDB, design documents provide the main interface for building - a CouchDB application. The design document defines the views used to - extract information from CouchDB through one or more views. Design - documents are created within your CouchDB instance in the same way - as you create database documents, but the content and definition of - the documents is different. Design Documents are named using an ID - defined with the design document URL path, and this URL can then be - used to access the database contents. - </para> - - <para> - Views and lists operate together to provide automated (and - formatted) output from your database. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-design-summary"><title>Design Document API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc_get"> - Returns the latest revision of the design document - </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc_put"> - Creates or updates a design document - </link></entry></row><row><entry><literal moreinfo="none">DELETE</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc_delete"> - Deletes the design document - </link></entry></row><row><entry><literal moreinfo="none">COPY</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc_copy"> - Copies the design document - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/_info</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-info_get"> - Returns information about the design document - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-list-listname-otherdesigndoc-viewname_get"> - Invokes the list handler to translate the given view results - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-list-listname-otherdesigndoc-viewname_post"> - Invokes the list handler to translate the given view results for - certain documents - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/_list/list-name/view-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-list-listname-viewname_get"> - Invokes the list handler to translate the given view results - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/_list/list-name/view-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-list-listname-viewname_post"> - Invokes the list handler to translate the given view results for - certain documents - </link></entry></row><row><entry><literal moreinfo="none">ALL</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/_rewrite/rewrite-name/anything</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-rewrite-rewritename-anything_all"> - Invokes the URL rewrite handler and processes the request after - rewriting - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/_show/show-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-show-showname_get"> - Invokes the show handler without a document - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/_show/show-name/doc</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-show-showname-doc_get"> - Invokes the show handler for the given document - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/_update/update-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-update-updatename_post"> - Invokes the update handler without a document ID - </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/_update/update-name/doc</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-update-updatename-doc_put"> - Invokes the update handler with a specific document ID - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/_view/view-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-view-viewname_get"> - Returns results of the view - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/_view/view-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-view-viewname_post"> - Returns certain rows from the view - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/attachment</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-attachment_get"> - Gets an attachment of the design document - </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/attachment</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-attachment_put"> - Inserts an attachment to the design document - </link></entry></row><row><entry><literal moreinfo="none">DELETE</literal></entry><entry><literal moreinfo="none">/db/_design/design-doc/attachment</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-attachment_delete"> - Deletes an attachment from the design document - </link></entry></row></tbody></tgroup></table> - - <section id="couchdb-api-design_db-design-designdoc_get"> - - <title><literal moreinfo="none">GET /db/_design/design-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_design/design-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the existing design document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the revision to return - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">revs</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of the revisions for the document - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">true</literal></entry><entry>Includes the revisions</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">revs_info</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of detailed revision information for the - document - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">true</literal></entry><entry>Includes the revisions</entry></row></tbody></tgroup></informaltable> - - <para> - Returns the specified design document, - <literal moreinfo="none">design-doc</literal> from the specified - <literal moreinfo="none">db</literal>. For example, to retrieve the design - document <literal moreinfo="none">recipes</literal> you would send the following - request: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/recipes/_design/recipes -Content-Type: application/json</programlisting> - - <para> - The returned string will be the JSON of the design document: - </para> - -<programlisting format="linespecific">{ - "_id" : "_design/recipes", - "_rev" : "5-39f56a392b86bbee57e2138921346406" - "language" : "javascript", - "views" : { - "by_recipe" : { - "map" : "function(doc) { if (doc.title != null) emit(doc.title, doc) }" - }, - }, -}</programlisting> - - <para> - A list of the revisions can be obtained by using the - <literal moreinfo="none">revs</literal> query argument, or an extended list of - revisions using the <literal moreinfo="none">revs_info</literal> query argument. - This operates in the same way as for other documents. Fur further - examples, see - <xref linkend="couchdb-api-dbdoc_db-doc_get"/>. - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_put"> - - <title><literal moreinfo="none">PUT /db/_design/design-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/_design/design-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /db/_design/design-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the design document - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON status - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Upload the specified design document, - <literal moreinfo="none">design-doc</literal>, to the specified database. The - design document should follow the definition of a design document, - as summarised in the following table. - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-json-designdoc" class="jsonstructure"><title> - Design Document - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">_id</literal> </entry><entry> - Design Document ID - </entry></row><row><entry><literal moreinfo="none">_rev</literal> </entry><entry> - Design Document Revision - </entry></row><row><entry><literal moreinfo="none">views</literal> </entry><entry> - View - </entry></row><row><entry> <literal moreinfo="none">viewname</literal> </entry><entry> - View Definition - </entry></row><row><entry> <literal moreinfo="none">map</literal> </entry><entry> - Map Function for View - </entry></row><row><entry> <literal moreinfo="none">reduce</literal> (optional) </entry><entry> - Reduce Function for View - </entry></row></tbody></tgroup></table> - - <para> - For more information on writing views, see - <xref linkend="couchdb-api-functional-views"/>. - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_delete"> - - <title><literal moreinfo="none">DELETE /db/_design/design-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API DELETE /db/_design/design-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">DELETE /db/_design/design-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of deleted design document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current revision of the document for validation - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">If-Match</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry/><entry/></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Supplied revision is incorrect or missing - </entry></row></tbody></tgroup></informaltable> - - <para> - Delete an existing design document. Deleting a design document - also deletes all of the associated view indexes, and recovers the - corresponding space on disk for the indexes in question. - </para> - - <para> - To delete, you must specify the current revision of the design - document using the <literal moreinfo="none">rev</literal> query argument. - </para> - - <para> - For example: - </para> - -<programlisting format="linespecific">DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8 -Content-Type: application/json</programlisting> - - <para> - The response contains the delete document ID and revision: - </para> - -<programlisting format="linespecific">{ - "id" : "recipe/_design/recipes" - "ok" : true, - "rev" : "3-7a05370bff53186cb5d403f861aca154", -}</programlisting> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_copy"> - - <title><literal moreinfo="none">COPY /db/_design/design-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API COPY /db/_design/design-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">COPY /db/_design/design-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the copied document and revision - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Revision to copy from - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">Destination</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Destination document (and optional revision)</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry/><entry/><entry/></row></tbody></tgroup></informaltable> - - <para> - The <literal moreinfo="none">COPY</literal> command (non-standard HTTP) copies an - existing design document to a new or existing document. - </para> - - <para> - The source design document is specified on the request line, with - the <literal moreinfo="none">Destination</literal> HTTP Header of the request - specifying the target document. - </para> - - <section id="couchdb-api-design_db-design-designdoc_copy-simple"> - - <title>Copying a Design Document</title> - - <para> - To copy the latest version of a design document to a new - document you specify the base document and target document: - </para> - -<programlisting format="linespecific">COPY http://couchdb:5984/recipes/_design/recipes -Content-Type: application/json -Destination: /recipes/_design/recipelist</programlisting> - - <para> - The above request copies the design document - <literal moreinfo="none">recipes</literal> to the new design document - <literal moreinfo="none">recipelist</literal>. The response is the ID and - revision of the new document. - </para> - -<programlisting format="linespecific">{ - "id" : "recipes/_design/recipelist" - "rev" : "1-9c65296036141e575d32ba9c034dd3ee", -}</programlisting> - - <note> - <para> - Copying a design document does automatically reconstruct the - view indexes. These will be recreated, as with other views, - the first time the new view is accessed. - </para> - </note> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_copy-specrev"> - - <title>Copying from a Specific Revision</title> - - <para> - To copy <emphasis>from</emphasis> a specific version, use the - <literal moreinfo="none">rev</literal> argument to the query string: - </para> - -<programlisting format="linespecific">COPY http://couchdb:5984/recipes/_design/recipes?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5 -Content-Type: application/json -Destination: recipes/_design/recipelist</programlisting> - - <para> - The new design document will be created using the specified - revision of the source document. - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_copy-existing"> - - <title>Copying to an Existing Design Document</title> - - <para> - To copy to an existing document, you must specify the current - revision string for the target document, using the - <literal moreinfo="none">rev</literal> parameter to the - <literal moreinfo="none">Destination</literal> HTTP Header string. For example: - </para> - -<programlisting format="linespecific">COPY http://couchdb:5984/recipes/_design/recipes -Content-Type: application/json -Destination: recipes/_design/recipelist?rev=1-9c65296036141e575d32ba9c034dd3ee</programlisting> - - <para> - The return value will be the new revision of the copied - document: - </para> - -<programlisting format="linespecific">{ - "id" : "recipes/_design/recipes" - "rev" : "2-55b6a1b251902a2c249b667dab1c6692", -}</programlisting> - - </section> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-attachment_get"> - - <title><literal moreinfo="none">GET /db/_design/design-doc/attachment</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/attachment</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_design/design-doc/attachment</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Document content - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Returns the file attachment <literal moreinfo="none">attachment</literal> - associated with the design document - <literal moreinfo="none">/_design_/design-doc</literal>. The raw data of the - associated attachment is returned (just as if you were accessing a - static file. The returned HTTP <literal moreinfo="none">Content-type</literal> - will be the same as the content type set when the document - attachment was submitted into the database. - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-attachment_put"> - - <title><literal moreinfo="none">PUT /db/_design/design-doc/attachment</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/_design/design-doc/attachment</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /db/_design/design-doc/attachment</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the design document - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON status statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current revision of the document for validation - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">If-Match</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry/><entry/></row></tbody></tgroup></informaltable> - - <para> - Upload the supplied content as an attachment to the specified - design document (<literal moreinfo="none">/_design/design-doc</literal>). The - <literal moreinfo="none">attachment</literal> name provided must be a URL encoded - string. You must also supply either the <literal moreinfo="none">rev</literal> - query argument or the <literal moreinfo="none">If-Match</literal> HTTP header for - validation, and the HTTP headers (to set the attacment content - type). The content type is used when the attachment is requested - as the corresponding content-type in the returned document header. - </para> - - <para> - For example, you could upload a simple text document using the - following request: - </para> - -<programlisting format="linespecific">PUT http://couchdb:5984/recipes/_design/recipes/view.css?rev=7-f7114d4d81124b223283f3e89eee043e -Content-Length: 39 -Content-Type: text/plain - -div.recipetitle { -font-weight: bold; -}</programlisting> - - <para> - Or by using the <literal moreinfo="none">If-Match</literal> HTTP header: - </para> - -<programlisting format="linespecific">PUT http://couchdb:5984/recipes/FishStew/basic -If-Match: 7-f7114d4d81124b223283f3e89eee043e -Content-Length: 39 -Content-Type: text/plain - -div.recipetitle { -font-weight: bold; -}</programlisting> - - <para> - The returned JSON contains the new document information: - </para> - -<programlisting format="linespecific">{ - "id" : "_design/recipes" - "ok" : true, - "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5", -}</programlisting> - - <note> - <para> - Uploading an attachment updates the corresponding document - revision. Revisions are tracked for the parent document, not - individual attachments. - </para> - </note> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-attachment_delete"> - - <title><literal moreinfo="none">DELETE /db/_design/design-doc/attachment</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API DELETE /db/_design/design-doc/attachment</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">DELETE /db/_design/design-doc/attachment</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the deleted revision - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current revision of the document for validation - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">If-Match</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry/><entry/></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Supplied revision is incorrect or missing - </entry></row></tbody></tgroup></informaltable> - - <para> - Deletes the attachment <literal moreinfo="none">attachment</literal> to the - specified <literal moreinfo="none">_design/design-doc</literal>. You must supply - the <literal moreinfo="none">rev</literal> argument with the current revision to - delete the attachment. - </para> - - <para> - For example to delete the attachment <literal moreinfo="none">view.css</literal> - from the design document <literal moreinfo="none">recipes</literal>: - </para> - -<programlisting format="linespecific">DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a</programlisting> - - <para> - The returned JSON contains the updated revision information for - the parent document: - </para> - -<programlisting format="linespecific">{ - "id" : "_design/recipes" - "ok" : true, - "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c", -}</programlisting> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-info_get"> - - <title><literal moreinfo="none">GET /db/_design/design-doc/_info</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/_info</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_design/design-doc/_info</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the design document information - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Obtains information about a given design document, including the - index, index size and current status of the design document and - associated index information. - </para> - - <para> - For example, to get the information for the - <literal moreinfo="none">recipes</literal> design document: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/recipes/_design/recipes/_info -Content-Type: application/json</programlisting> - - <para> - This returns the following JSON structure: - </para> - -<programlisting format="linespecific">{ - "name" : "recipes" - "view_index" : { - "compact_running" : false, - "updater_running" : false, - "language" : "javascript", - "purge_seq" : 10, - "waiting_commit" : false, - "waiting_clients" : 0, - "signature" : "fc65594ee76087a3b8c726caf5b40687", - "update_seq" : 375031, - "disk_size" : 16491 - }, -}</programlisting> - - <para> - The individual fields in the returned JSON structure are detailed - in - <xref linkend="table-couchdb-api-design_db-designdoc-info-json"/>. - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-design_db-designdoc-info-json" class="jsonstructure"><title>Design Document Info JSON Contents</title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">name</literal> </entry><entry> - Name/ID of Design Document - </entry></row><row><entry><literal moreinfo="none">view_index</literal> </entry><entry> - View Index - </entry></row><row><entry> <literal moreinfo="none">compact_running</literal> </entry><entry> - Indicates whether a compaction routine is currently running on - the view - </entry></row><row><entry> <literal moreinfo="none">disk_size</literal> </entry><entry> - Size in bytes of the view as stored on disk - </entry></row><row><entry> <literal moreinfo="none">language</literal> </entry><entry> - Language for the defined views - </entry></row><row><entry> <literal moreinfo="none">purge_seq</literal> </entry><entry> - The purge sequence that has been processed - </entry></row><row><entry> <literal moreinfo="none">signature</literal> </entry><entry> - MD5 signature of the views for the design document - </entry></row><row><entry> <literal moreinfo="none">update_seq</literal> </entry><entry> - The update sequence of the corresponding database that has been - indexed - </entry></row><row><entry> <literal moreinfo="none">updater_running</literal> </entry><entry> - Indicates if the view is currently being updated - </entry></row><row><entry> <literal moreinfo="none">waiting_clients</literal> </entry><entry> - Number of clients waiting on views from this design document - </entry></row><row><entry> <literal moreinfo="none">waiting_commit</literal> </entry><entry> - Indicates if there are outstanding commits to the underlying - database that need to processed - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_get"> - - <title><literal moreinfo="none">GET /db/_design/design-doc/_view/view-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/_view/view-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_design/design-doc/_view/view-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the documents returned by the view - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">descending</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return the documents in descending by key order - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">endkey</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Stop returning records when the specified key is reached - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">endkey_docid</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Stop returning records when the specified document ID is - reached - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">group</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Group the results using the reduce function to a group or - single row - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">group_level</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the group level to be used - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">include_docs</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the full content of the documents in the return - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">inclusive_end</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specifies whether the specified end key should be included - in the result - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>true</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">key</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return only documents that match the specified key - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">limit</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Limit the number of the returned documents to the specified - number - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">reduce</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Use the reduction function - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>true</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">skip</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Skip this number of records before starting to return the - results - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>0</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">stale</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Allow the results from a stale view to be used - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry/></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">ok</literal></entry><entry>Allow stale views</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">startkey</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return records starting with the specified key - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">startkey_docid</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return records starting with the specified document ID - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">update_seq</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the update sequence in the generated results - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row></tbody></tgroup></informaltable> - - <para> - Executes the specified <literal moreinfo="none">view-name</literal> from the - specified <literal moreinfo="none">design-doc</literal> design document. - </para> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_get-indexes"> - - <title>Querying Views and Indexes</title> - - <para> - The definition of a view within a design document also creates - an index based on the key information defined within each view. - The production and use of the index significantly increases the - speed of access and searching or selecting documents from the - view. - </para> - - <para> - However, the index is not updated when new documents are added - or modified in the database. Instead, the index is generated or - updated, either when the view is first accessed, or when the - view is accessed after a document has been updated. In each - case, the index is updated before the view query is executed - against the database. - </para> - - <para> - View indexes are updated incrementally in the following - situations: - </para> - - <itemizedlist> - - <listitem> - <para> - A new document has been added to the database. - </para> - </listitem> - - <listitem> - <para> - A document has been deleted from the database. - </para> - </listitem> - - <listitem> - <para> - A document in the database has been updated. - </para> - </listitem> - - </itemizedlist> - - <para> - View indexes are rebuilt entirely when the view definition - changes. To achieve this, a 'fingerprint' of the view definition - is created when the design document is updated. If the - fingerprint changes, then the view indexes are entirely rebuilt. - This ensures that changes to the view definitions are reflected - in the view indexes. - </para> - - <note> - <para> - View index rebuilds occur when one view from the same the view - group (i.e. all the views defined within a single a design - document) has been determined as needing a rebuild. For - example, if if you have a design document with different - views, and you update the database, all three view indexes - within the design document will be updated. - </para> - </note> - - <para> - Because the view is updated when it has been queried, it can - result in a delay in returned information when the view is - accessed, especially if there are a large number of documents in - the database and the view index does not exist. There are a - number of ways to mitigate, but not completely eliminate, these - issues. These include: - </para> - - <itemizedlist> - - <listitem> - <para> - Create the view definition (and associated design documents) - on your database before allowing insertion or updates to the - documents. If this is allowed while the view is being - accessed, the index can be updated incrementally. - </para> - </listitem> - - <listitem> - <para> - Manually force a view request from the database. You can do - this either before users are allowed to use the view, or you - can access the view manually after documents are added or - updated. - </para> - </listitem> - - <listitem> - <para> - Use the <literal moreinfo="none">/db/_changes</literal> method to monitor - for changes to the database and then access the view to - force the corresponding view index to be updated. See - <xref linkend="couchdb-api-db_db-changes_get"/> - for more information. - </para> - </listitem> - - <listitem> - <para> - Use a monitor with the - <literal moreinfo="none">update_notification</literal> section of the - CouchDB configuration file to monitor for changes to your - database, and trigger a view query to force the view to be - updated. For more information, see - <xref linkend="couchdb-single-configuration-update_notification"/>. - </para> - </listitem> - - </itemizedlist> - - <para> - None of these can completely eliminate the need for the indexes - to be rebuilt or updated when the view is accessed, but they may - lessen the effects on end-users of the index update affecting - the user experience. - </para> - - <para> - Another alternative is to allow users to access a 'stale' - version of the view index, rather than forcing the index to be - updated and displaying the updated results. Using a stale view - may not return the latest information, but will return the - results of the view query using an existing version of the - index. - </para> - - <para> - For example, to access the existing stale view - <literal moreinfo="none">by_recipe</literal> in the <literal moreinfo="none">recipes</literal> - design document: - </para> - -<programlisting format="linespecific">http://couchdb:5984/recipes/_design/recipes/_view/by_recipe?stale=ok</programlisting> - - <para> - Accessing a stale view: - </para> - - <itemizedlist> - - <listitem> - <para> - Does not trigger a rebuild of the view indexes, even if - there have been changes since the last access. - </para> - </listitem> - - <listitem> - <para> - Returns the current version of the view index, if a current - version exists. - </para> - </listitem> - - <listitem> - <para> - Returns an empty result set if the given view index does - exist. - </para> - </listitem> - - </itemizedlist> - - <para> - As an alternative, you use the <literal moreinfo="none">update_after</literal> - value to the <option>stale</option> paramater. This causes the - view to be returned as a stale view, but for the update process - to be triggered after the view information has been returned to - the client. - </para> - - <para> - In addition to using stale views, you can also make use of the - <literal moreinfo="none">update_seq</literal> query argument. Using this query - argument generates the view information including the update - sequence of the database from which the view was generated. The - returned value can be compared this to the current update - sequence exposed in the database information (returned by - <xref linkend="couchdb-api-db_db_get"/>). - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_get-sorting"> - - <title>Sorting Returned Rows</title> - - <para> - Each element within the returned array is sorted using native - UTF-8 sorting according to the contents of the key portion of - the emitted content. The basic order of output is as follows: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal moreinfo="none">null</literal> - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">false</literal> - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">true</literal> - </para> - </listitem> - - <listitem> - <para> - Numbers - </para> - </listitem> - - <listitem> - <para> - Text (case sensitive, lowercase first) - </para> - </listitem> - - <listitem> - <para> - Arrays (according to the values of each element, in order) - </para> - </listitem> - - <listitem> - <para> - Objects (according to the values of keys, in key order) - </para> - </listitem> - - </itemizedlist> - - - - <para> - You can reverse the order of the returned view information by - using the <literal moreinfo="none">descending</literal> query value set to true. - For example, Retrieving the list of recipes using the - <literal moreinfo="none">by_title</literal> (limited to 5 records) view: - </para> - -<programlisting format="linespecific">{ - "offset" : 0, - "rows" : [ - { - "id" : "3-tiersalmonspinachandavocadoterrine", - "key" : "3-tier salmon, spinach and avocado terrine", - "value" : [ - null, - "3-tier salmon, spinach and avocado terrine" - ] - }, - { - "id" : "Aberffrawcake", - "key" : "Aberffraw cake", - "value" : [ - null, - "Aberffraw cake" - ] - }, - { - "id" : "Adukiandorangecasserole-microwave", - "key" : "Aduki and orange casserole - microwave", - "value" : [ - null, - "Aduki and orange casserole - microwave" - ] - }, - { - "id" : "Aioli-garlicmayonnaise", - "key" : "Aioli - garlic mayonnaise", - "value" : [ - null, - "Aioli - garlic mayonnaise" - ] - }, - { - "id" : "Alabamapeanutchicken", - "key" : "Alabama peanut chicken", - "value" : [ - null, - "Alabama peanut chicken" - ] - } - ], - "total_rows" : 2667 -}</programlisting> - - <para> - Requesting the same in descending order will reverse the entire - view content. For example the request - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/recipes/_design/recipes/_view/by_title?limit=5&descending=true -Accept: application/json -Content-Type: application/json</programlisting> - - <para> - Returns the last 5 records from the view: - </para> - -<programlisting format="linespecific">{ - "offset" : 0, - "rows" : [ - { - "id" : "Zucchiniinagrodolcesweet-sourcourgettes", - "key" : "Zucchini in agrodolce (sweet-sour courgettes)", - "value" : [ - null, - "Zucchini in agrodolce (sweet-sour courgettes)" - ] - }, - { - "id" : "Zingylemontart", - "key" : "Zingy lemon tart", - "value" : [ - null, - "Zingy lemon tart" - ] - }, - { - "id" : "Zestyseafoodavocado", - "key" : "Zesty seafood avocado", - "value" : [ - null, - "Zesty seafood avocado" - ] - }, - { - "id" : "Zabaglione", - "key" : "Zabaglione", - "value" : [ - null, - "Zabaglione" - ] - }, - { - "id" : "Yogurtraita", - "key" : "Yogurt raita", - "value" : [ - null, - "Yogurt raita" - ] - } - ], - "total_rows" : 2667 -}</programlisting> - - <para> - The sorting direction is applied before the filtering applied - using the <literal moreinfo="none">startkey</literal> and - <literal moreinfo="none">endkey</literal> query arguments. For example the - following query: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?startkey=%22carrots%22&endkey=%22egg%22 -Accept: application/json -Content-Type: application/json</programlisting> - - <para> - Will operate correctly when listing all the matching entries - between <quote>carrots</quote> and <literal moreinfo="none">egg</literal>. If - the order of output is reversed with the - <literal moreinfo="none">descending</literal> query argument, the view request - will return no entries: - </para> - -<programlisting format="linespecific">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</programlisting> - - <para> - The returned result is empty: - </para> - -<programlisting format="linespecific">{ - "total_rows" : 26453, - "rows" : [], - "offset" : 21882 -}</programlisting> - - <para> - The results will be empty because the entries in the view are - reversed before the key filter is applied, and therefore the - <literal moreinfo="none">endkey</literal> of <quote>egg</quote> will be seen - before the <literal moreinfo="none">startkey</literal> of - <quote>carrots</quote>, resulting in an empty list. - </para> - - <para> - Instead, you should reverse the values supplied to the - <literal moreinfo="none">startkey</literal> and <literal moreinfo="none">endkey</literal> - parameters to match the descending sorting applied to the keys. - Changing the previous example to: - </para> - -<programlisting format="linespecific">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</programlisting> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_get-ranges"> - - <title>Specifying Start and End Values</title> - - <para> - The <literal moreinfo="none">startkey</literal> and <literal moreinfo="none">endkey</literal> - query arguments can be used to specify the range of values to be - displayed when querying the view. - </para> - - <note> - <para> - The values - </para> - </note> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_get-limit"> - - <title>Using Limits and Skipping Rows</title> - - <para> - TBC - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_get-reduction"> - - <title>View Reduction and Grouping</title> - - <para> - TBC - </para> - - </section> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_post"> - - <title><literal moreinfo="none">POST /db/_design/design-doc/_view/view-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_design/design-doc/_view/view-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_design/design-doc/_view/view-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - List of keys to be returned from specified view - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the documents returned by the view - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">descending</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return the documents in descending by key order - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">endkey</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Stop returning records when the specified key is reached - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">endkey_docid</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Stop returning records when the specified document ID is - reached - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">group</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Group the results using the reduce function to a group or - single row - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">group_level</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the group level to be used - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">include_docs</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the full content of the documents in the return - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">inclusive_end</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specifies whether the specified end key should be included - in the result - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>true</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">key</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return only documents that match the specified key - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">limit</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Limit the number of the returned documents to the specified - number - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">reduce</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Use the reduction function - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>true</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">skip</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Skip this number of records before starting to return the - results - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>0</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">stale</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Allow the results from a stale view to be used - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry/></row><row><entry/><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry/><entry><literal moreinfo="none">ok</literal></entry><entry>Allow stale views</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">startkey</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return records starting with the specified key - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">startkey_docid</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return records starting with the specified document ID - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">update_seq</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the update sequence in the generated results - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row></tbody></tgroup></informaltable> - - <para> - Executes the specified <literal moreinfo="none">view-name</literal> from the - specified <literal moreinfo="none">design-doc</literal> design document. Unlike - the <literal moreinfo="none">GET</literal> method for accessing views, the - <literal moreinfo="none">POST</literal> method supports the specification of - explicit keys to be retrieved from the view results. The remainder - of the <literal moreinfo="none">POST</literal> view functionality is identical to - the - <xref linkend="couchdb-api-design_db-design-designdoc-view-viewname_get"/> - fun - </para> - - <para> - For example, the request below will return all the recipes where - the key for the view matches either <quote>claret</quote> or - <quote>clear apple cider</quote> : - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient -Content-Type: application/json - -{ - "keys" : [ - "claret", - "clear apple juice" - ] -}</programlisting> - - <para> - The returned view data contains the standard view information, but - only where the keys match. - </para> - -<programlisting format="linespecific">{ - "total_rows" : 26484, - "rows" : [ - { - "value" : [ - "Scotch collops" - ], - "id" : "Scotchcollops", - "key" : "claret" - }, - { - "value" : [ - "Stand pie" - ], - "id" : "Standpie", - "key" : "clear apple juice" - } - ], - "offset" : 6324 -}</programlisting> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_post-multidoc"> - - <title>Multi-document Fetching</title> - - <para> - By combining the <literal moreinfo="none">POST</literal> method to a given view - with the <literal moreinfo="none">include_docs=true</literal> query argument you - can obtain multiple documents from a database. The result is - more efficient than using multiple - <xref linkend="couchdb-api-dbdoc_db-doc_get"/> - requests. - </para> - - <para> - For example, sending the following request for ingredients - matching <quote>claret</quote> and <quote>clear apple - juice</quote>: - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?include_docs=true -Content-Type: application/json - -{ - "keys" : [ - "claret", - "clear apple juice" - ] -}</programlisting> - - <para> - Returns the full document for each recipe: - </para> - -<programlisting format="linespecific">{ - "offset" : 6324, - "rows" : [ - { - "doc" : { - "_id" : "Scotchcollops", - "_rev" : "1-bcbdf724f8544c89697a1cbc4b9f0178", - "cooktime" : "8", - "ingredients" : [ - { - "ingredient" : "onion", - "ingredtext" : "onion, peeled and chopped", - "meastext" : "1" - }, - ... - ], - "keywords" : [ - "cook method.hob, oven, grill@hob", - "diet@wheat-free", - "diet@peanut-free", - "special collections@classic recipe", - "cuisine@british traditional", - "diet@corn-free", - "diet@citrus-free", - "special collections@very easy", - "diet@shellfish-free", - "main ingredient@meat", - "occasion@christmas", - "meal type@main", - "diet@egg-free", - "diet@gluten-free" - ], - "preptime" : "10", - "servings" : "4", - "subtitle" : "This recipe comes from an old recipe book of 1683 called 'The Gentlewoman's Kitchen'. This is an excellent way of making a rich and full-flavoured meat dish in a very short time.", - "title" : "Scotch collops", - "totaltime" : "18" - }, - "id" : "Scotchcollops", - "key" : "claret", - "value" : [ - "Scotch collops" - ] - }, - { - "doc" : { - "_id" : "Standpie", - "_rev" : "1-bff6edf3ca2474a243023f2dad432a5a", - "cooktime" : "92", - "ingredients" : [ -... ], - "keywords" : [ - "diet@dairy-free", - "diet@peanut-free", - "special collections@classic recipe", - "cuisine@british traditional", - "diet@corn-free", - "diet@citrus-free", - "occasion@buffet party", - "diet@shellfish-free", - "occasion@picnic", - "special collections@lunchbox", - "main ingredient@meat", - "convenience@serve with salad for complete meal", - "meal type@main", - "cook method.hob, oven, grill@hob / oven", - "diet@cow dairy-free" - ], - "preptime" : "30", - "servings" : "6", - "subtitle" : "Serve this pie with pickled vegetables and potato salad.", - "title" : "Stand pie", - "totaltime" : "437" - }, - "id" : "Standpie", - "key" : "clear apple juice", - "value" : [ - "Stand pie" - ] - } - ], - "total_rows" : 26484 -}</programlisting> - - </section> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-show-showname_get"> - - <title><literal moreinfo="none">POST /db/_design/design-doc/_show/show-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/_show/show-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_design/design-doc/_show/show-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Returns the result of the show - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">details</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Indicates whether details should be included - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">format</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Format of the returned information - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row></tbody></tgroup></informaltable> - - <para/> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-show-showname-doc_get"> - - <title><literal moreinfo="none">POST /db/_design/design-doc/_show/show-name/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/_show/show-name/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_design/design-doc/_show/show-name/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Returns the show for the given document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para/> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-list-listname-otherdesigndoc-viewname_get"> - - <title><literal moreinfo="none">GET - /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-list-listname-otherdesigndoc-viewname_post"> - - <title><literal moreinfo="none">POST - /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-list-listname-viewname_get"> - - <title><literal moreinfo="none">GET /db/_design/design-doc/_list/list-name/view-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/_list/list-name/view-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db/_design/design-doc/_list/list-name/view-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-list-listname-viewname_post"> - - <title><literal moreinfo="none">POST /db/_design/design-doc/_list/list-name/view-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_design/design-doc/_list/list-name/view-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_design/design-doc/_list/list-name/view-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-update-updatename-doc_put"> - - <title><literal moreinfo="none">PUT /db/_design/design-doc/_update/updatename/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/_design/design-doc/_update/update-name/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /db/_design/design-doc/_update/update-name/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - Document update information - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Updated document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-update-updatename_post"> - - <title><literal moreinfo="none">POST /db/_design/design-doc/_update/updatename</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_design/design-doc/_update/update-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /db/_design/design-doc/_update/update-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - Document update information - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Updated document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-rewrite-rewritename-anything"> - - <title><literal moreinfo="none">ALL - /db/_design/design-doc/_rewrite/rewrite-name/anything</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API ALL /db/_design/design-doc/_rewrite/rewrite-name/anything</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">ALL /db/_design/design-doc/_rewrite/rewrite-name/anything</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - -</chapter> - - <chapter id="couchdb-api-misc"> - - <title>CouchDB API Server Miscellaneous Methods</title> - - <para> - The CouchDB Miscellaneous interface provides the basic interface to - a CouchDB server for obtaining CouchDB information and getting and - setting configuration information. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-misc-summary"><title>Miscellaneous API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/</literal></entry><entry><link linkend="couchdb-api-misc_root_get"> - Get the welcome message and version information - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_active_tasks</literal></entry><entry><link linkend="couchdb-api-misc_active-tasks_get"> - Obtain a list of the tasks running in the server - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_all_dbs</literal></entry><entry><link linkend="couchdb-api-misc_all-dbs_get"> - Get a list of all the DBs - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_log</literal></entry><entry><link linkend="couchdb-api-misc_log_get"> - Return the server log file - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/_replicate</literal></entry><entry><link linkend="couchdb-api-misc_replicate_post"> - Set or cancel replication - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/_restart</literal></entry><entry><link linkend="couchdb-api-misc_restart_post"> - Restart the server - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_stats</literal></entry><entry><link linkend="couchdb-api-misc_stats_get"> - Return server statistics - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_utils</literal></entry><entry><link linkend="couchdb-api-misc_utils_get"> - CouchDB administration interface (Futon) - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_uuids</literal></entry><entry><link linkend="couchdb-api-misc_uuids_get"> - Get generated UUIDs from the server - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/favicon.ico</literal></entry><entry><link linkend="couchdb-api-misc_favicon_get"> - Get the site icon - </link></entry></row></tbody></tgroup></table> - - <section id="couchdb-api-misc_root_get"> - - <title><literal moreinfo="none">GET /</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Welcome message and version - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - Accessing the root of a CouchDB instance returns meta information - about the instance. The response is a JSON structure containing - information about the server, including a welcome message and the - version of the server. - </para> - -<programlisting format="linespecific">{ - "couchdb" : "Welcome", - "version" : "1.0.1" -}</programlisting> - - </section> - - <section id="couchdb-api-misc_active-tasks_get"> - - <title><literal moreinfo="none">GET /_active_tasks</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /_active_tasks</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /_active_tasks</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - List of running tasks, including the task type, name, status and - process ID - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - You can obtain a list of active tasks by using the - <literal moreinfo="none">/_active_tasks</literal> URL. The result is a JSON array - of the currently running tasks, with each task being described - with a single object. For example: - </para> - -<programlisting format="linespecific">[ - { - "pid" : "<0.11599.0>", - "status" : "Copied 0 of 18369 changes (0%)", - "task" : "recipes", - "type" : "Database Compaction" - } -]</programlisting> - - <para> - The returned structure includes the following fields for each - task: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-misc-active-tasks-json" class="jsonstructure"><title> - List of Active Tasks - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">tasks</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Active Task - </entry></row><row><entry> <literal moreinfo="none">pid</literal> </entry><entry> - Process ID - </entry></row><row><entry> <literal moreinfo="none">status</literal> </entry><entry> - Task status message - </entry></row><row><entry> <literal moreinfo="none">task</literal> </entry><entry> - Task name - </entry></row><row><entry> <literal moreinfo="none">type</literal> </entry><entry> - Operation Type - </entry></row></tbody></tgroup></table> - - <para> - For operation type, valid values include: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal moreinfo="none">Database Compaction</literal> - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">Replication</literal> - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">View Group Compaction</literal> - </para> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">View Group Indexer</literal> - </para> - </listitem> - - </itemizedlist> - - </section> - - <section id="couchdb-api-misc_all-dbs_get"> - - <title><literal moreinfo="none">GET /_all_dbs</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /_all_dbs</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /_all_dbs</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON list of DBs - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - Returns a list of all the databases in the CouchDB instance. For - example: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/_all_dbs -Accept: application/json</programlisting> - - <para> - The return is a JSON array: - </para> - -<programlisting format="linespecific">[ - "_users", - "contacts", - "docs", - "invoices", - "locations" -]</programlisting> - - </section> - - <section id="couchdb-api-misc_log_get"> - - <title><literal moreinfo="none">GET /_log</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /_log</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /_log</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Log content - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">bytes</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Bytes to be returned - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>1000</entry></row><row><entry/><entry/><entry/></row><row><entry/><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">offset</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Offset in bytes where the log tail should be started - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry/><entry><emphasis role="bold">Default</emphasis></entry><entry>0</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - Gets the CouchDB log, equivalent to accessing the local log file - of the corresponding CouchDB instance. - </para> - - <para> - When you request the log, the response is returned as plain - (UTF-8) text, with an HTTP <literal moreinfo="none">Content-type</literal> header - as <literal moreinfo="none">text/plain</literal>. - </para> - - <para> - For example, the request: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/_log -Accept: */*</programlisting> - - <para> - The raw text is returned: - </para> - -<programlisting format="linespecific">[Wed, 27 Oct 2010 10:49:42 GMT] [info] [<0.23338.2>] 192.168.0.2 - - 'PUT' /authdb 401 - -[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /recipes/FishStew 200 - -[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /_session 200 - -[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.24199.2>] 192.168.0.116 - - 'GET' / 200 - -[Wed, 27 Oct 2010 13:03:38 GMT] [info] [<0.24207.2>] 192.168.0.116 - - 'GET' /_log?offset=5 200</programlisting> - - <para> - If you want to pick out specific parts of the log information you - can use the <literal moreinfo="none">bytes</literal> argument, which specifies the - number of bytes to be returned, and <literal moreinfo="none">offset</literal>, - which specifies where the reading of the log should start, counted - back from the end. For example, if you use the following request: - </para> - -<programlisting format="linespecific">GET /_log?bytes=500&offset=2000</programlisting> - - <para> - Reading of the log will start at 2000 bytes from the end of the - log, and 500 bytes will be shown. - </para> - - </section> - - <section id="couchdb-api-misc_replicate_post"> - - <title><literal moreinfo="none">POST /_replicate</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /_replicate</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /_replicate</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - Replication specification - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Welcome message and version - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Replication request successfully completed - </entry></row><row><entry>202</entry><entry namest="info" nameend="addinfo"> - Continuous replication request has been accepted - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - Either the source or target DB is not found - </entry></row><row><entry>500</entry><entry namest="info" nameend="addinfo"> - JSON specification was invalid - </entry></row></tbody></tgroup></informaltable> - - <para> - Request, configure, or stop, a replication operation. - </para> - - <para> - The specification of the replication request is controlled through - the JSON content of the request. The JSON should be an object with - the fields defining the source, target and other options. The - fields of the JSON request are shown in the table below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-misc-json-replication" class="jsonstructure"><title> - Replication Settings - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">cancel</literal> (optional) </entry><entry> - Cancels the replication - </entry></row><row><entry><literal moreinfo="none">continuous</literal> (optional) </entry><entry> - Configure the replication to be continuous - </entry></row><row><entry><literal moreinfo="none">create_target</literal> (optional) </entry><entry> - Creates the target database - </entry></row><row><entry><literal moreinfo="none">doc_ids</literal> (optional) </entry><entry> - Array of document IDs to be synchronized - </entry></row><row><entry><literal moreinfo="none">proxy</literal> (optional) </entry><entry> - Address of a proxy server through which replication should occur - </entry></row><row><entry><literal moreinfo="none">source</literal> </entry><entry> - Source database name or URL - </entry></row><row><entry><literal moreinfo="none">target</literal> </entry><entry> - Target database name or URL - </entry></row></tbody></tgroup></table> - - <section id="couchdb-api-misc_replicate_post-operation"> - - <title>Replication Operation</title> - - <para> - The aim of the replication is that at the end of the process, - all active documents on the source database are also in the - destination database and all documents that were deleted in the - source databases are also deleted (if they exist) on the - destination database. - </para> - - <para> - Replication can be described as either push or pull replication: - </para> - - <itemizedlist> - - <listitem> - <para> - <emphasis>Pull replication</emphasis> is where the - <literal moreinfo="none">source</literal> is the remote CouchDB instance, - and the <literal moreinfo="none">destination</literal> is the local - database. - </para> - - <para> - Pull replication is the most useful solution to use if your - source database has a permanent IP address, and your - destination (local) database may have a dynamically assigned - IP address (for example, through DHCP). This is particularly - important if you are replicating to a mobile or other device - from a central server. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Push replication</emphasis> is where the - <literal moreinfo="none">source</literal> is a local database, and - <literal moreinfo="none">destination</literal> is a remote database. - </para> - </listitem> - - </itemizedlist> - - </section> - - <section id="couchdb-api-misc_replicate_post-sourcetarget"> - - <title>Specifying the Source and Target Database</title> - - <para> - You must use the URL specification of the CouchDB database if - you want to perform replication in either of the following two - situations: - </para> - - <itemizedlist> - - <listitem> - <para> - Replication with a remote database (i.e. another instance of - CouchDB on the same host, or a different host) - </para> - </listitem> - - <listitem> - <para> - Replication with a database that requires authentication - </para> - </listitem> - - </itemizedlist> - - <para> - For example, to request replication between a database local to - the CouchDB instance to which you send the request, and a remote - database you might use the following request: - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "source" : "recipes", - "target" : "http://coucdb-remote:5984/recipes", -}</programlisting> - - <para> - In all cases, the requested databases in the - <literal moreinfo="none">source</literal> and <literal moreinfo="none">target</literal> - specification must exist. If they do not, an error will be - returned within the JSON object: - </para> - -<programlisting format="linespecific">{ - "error" : "db_not_found" - "reason" : "could not open http://couchdb-remote:5984/ol1ka/", -}</programlisting> - - <para> - You can create the target database (providing your user - credentials allow it) by adding the - <literal moreinfo="none">create_target</literal> field to the request object: - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "create_target" : true - "source" : "recipes", - "target" : "http://couchdb-remote:5984/recipes", -}</programlisting> - - <para> - The <literal moreinfo="none">create_target</literal> field is not destructive. - If the database already exists, the replication proceeds as - normal. - </para> - - </section> - - <section id="couchdb-api-misc_replicate_post-single"> - - <title>Single Replication</title> - - <para> - You can request replication of a database so that the two - databases can be synchronized. By default, the replication - process occurs one time and synchronizes the two databases - together. For example, you can request a single synchronization - between two databases by supplying the <literal moreinfo="none">source</literal> - and <literal moreinfo="none">target</literal> fields within the request JSON - content. - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "source" : "recipes", - "target" : "recipes-snapshot", -}</programlisting> - - <para> - In the above example, the databases <literal moreinfo="none">recipes</literal> - and <literal moreinfo="none">recipes-snapshot</literal> will be synchronized. - These databases are local to the CouchDB instance where the - request was made. The response will be a JSON structure - containing the success (or failure) of the synchronization - process, and statistics about the process: - </para> - -<programlisting format="linespecific">{ - "ok" : true, - "history" : [ - { - "docs_read" : 1000, - "session_id" : "52c2370f5027043d286daca4de247db0", - "recorded_seq" : 1000, - "end_last_seq" : 1000, - "doc_write_failures" : 0, - "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT", - "start_last_seq" : 0, - "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT", - "missing_checked" : 0, - "docs_written" : 1000, - "missing_found" : 1000 - } - ], - "session_id" : "52c2370f5027043d286daca4de247db0", - "source_last_seq" : 1000 -}</programlisting> - - <para> - The structure defines the replication status, as described in - the table below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-misc-json-replication-status" class="jsonstructure"><title> - Replication Status - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">history</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Replication History - </entry></row><row><entry> <literal moreinfo="none">doc_write_failures</literal> </entry><entry> - Number of document write failures - </entry></row><row><entry> <literal moreinfo="none">docs_read</literal> </entry><entry> - Number of documents read - </entry></row><row><entry> <literal moreinfo="none">docs_written</literal> </entry><entry> - Number of documents written to target - </entry></row><row><entry> <literal moreinfo="none">end_last_seq</literal> </entry><entry> - Last sequence number in changes stream - </entry></row><row><entry> <literal moreinfo="none">end_time</literal> </entry><entry> - Date/Time replication operation completed - </entry></row><row><entry> <literal moreinfo="none">missing_checked</literal> </entry><entry> - Number of missing documents checked - </entry></row><row><entry> <literal moreinfo="none">missing_found</literal> </entry><entry> - Number of missing documents found - </entry></row><row><entry> <literal moreinfo="none">recorded_seq</literal> </entry><entry> - Last recorded sequence number - </entry></row><row><entry> <literal moreinfo="none">session_id</literal> </entry><entry> - Session ID for this replication operation - </entry></row><row><entry> <literal moreinfo="none">start_last_seq</literal> </entry><entry> - First sequence number in changes stream - </entry></row><row><entry> <literal moreinfo="none">start_time</literal> </entry><entry> - Date/Time replication operation started - </entry></row><row><entry><literal moreinfo="none">ok</literal> </entry><entry> - Replication status - </entry></row><row><entry><literal moreinfo="none">session_id</literal> </entry><entry> - Unique session ID - </entry></row><row><entry><literal moreinfo="none">source_last_seq</literal> </entry><entry> - Last sequence number read from source database - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-api-misc_replicate_post-continuous"> - - <title>Continuous Replication</title> - - <para> - Synchronization of a database with the previously noted methods - happens only once, at the time the replicate request is made. To - have the target database permanently replicated from the source, - you must set the <literal moreinfo="none">continuous</literal> field of the JSON - object within the request to true. - </para> - - <para> - With continuous replication changes in the source database are - replicated to the target database in perpetuity until you - specifically request that replication ceases. - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "continuous" : true - "source" : "recipes", - "target" : "http://couchdb-remote:5984/recipes", -}</programlisting> - - <para> - Changes will be replicated between the two databases as long as - a network connection is available between the two instances. - </para> - - <note> - <para> - Two keep two databases synchronized with each other, you need - to set replication in both directions; that is, you must - replicate from <literal moreinfo="none">databasea</literal> to - <literal moreinfo="none">databaseb</literal>, and separately from - <literal moreinfo="none">databaseb</literal> to <literal moreinfo="none">databasea</literal>. - </para> - </note> - - </section> - - <section id="couchdb-api-misc_replicate_post-cancel"> - - <title>Canceling Continuous Replication</title> - - <para> - You can cancel continuous replication by adding the - <literal moreinfo="none">cancel</literal> field to the JSON request object and - setting the value to true. Note that the structure of the - request must be identical to the original for the cancelation - request to be honoured. For example, if you requested continuous - replication, the cancellation request must also contain the - <literal moreinfo="none">continuous</literal> field. - </para> - - <para> - For example, the replication request: - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "source" : "recipes", - "target" : "http://couchdb-remote:5984/recipes", - "create_target" : true, - "continuous" : true -}</programlisting> - - <para> - Must be canceled using the request: - </para> - -<programlisting format="linespecific">POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "cancel" : true, - "continuous" : true - "create_target" : true, - "source" : "recipes", - "target" : "http://couchdb-remote:5984/recipes", -}</programlisting> - - <para> - Requesting cancellation of a replication that does not exist - results in a 404 error. - </para> - - </section> - - </section> - - <section id="couchdb-api-misc_restart_post"> - - <title><literal moreinfo="none">POST /_restart</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API POST /_restart</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">POST /_restart</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON status message - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">yes</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document created successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - Restarts the CouchDB instance. You must be authenticated as a user - with administration privileges for this to work. - </para> - - <para> - For example: - </para> - -<programlisting format="linespecific">POST http://admin:password@couchdb:5984/_restart</programlisting> - - <para> - The return value (if the server has not already restarted) is a - JSON status object indicating that the request has been received: - </para> - -<programlisting format="linespecific">{ - "ok" : true, -}</programlisting> - - <para> - If the server has already restarted, the header may be returned, - but no actual data is contained in the response. - </para> - - </section> - - <section id="couchdb-api-misc_stats_get"> - - <title><literal moreinfo="none">GET /_stats</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /_stats</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /_stats</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Server statistics - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - The <literal moreinfo="none">_stats</literal> method returns a JSON object - containting the statistics for the running server. The object is - structured with top-level sections collating the statistics for a - range of entries, with each individual statistic being easily - identified, and the content of each statistic is self-describing. - For example, the request time statistics, within the - <literal moreinfo="none">couchdb</literal> section are structured as follows: - </para> - -<programlisting format="linespecific">{ - "couchdb" : { -... - "request_time" : { - "stddev" : "27.509", - "min" : "0.333333333333333", - "max" : "152", - "current" : "400.976", - "mean" : "10.837", - "sum" : "400.976", - "description" : "length of a request inside CouchDB without MochiWeb" - }, -... - } -}</programlisting> - - <para> - The fields provide the current, minimum and maximum, and a - collection of statistical means and quantities. The quantity in - each case is not defined, but the descriptions below provide - </para> - - <para> - The statistics are divided into the following top-level sections: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal moreinfo="none">couchdb</literal> - </para> - - <para> - Describes statistics specific to the internals of CouchDB. - </para> - - <table> - <title><literal moreinfo="none">couchdb</literal> statistics</title> - <tgroup cols="3"> - <colspec colname="stat"/> - <colspec colname="desc"/> - <colspec colname="unit"/> - <thead> - <row> - <entry> - Statistic ID - </entry> - <entry> - Description - </entry> - <entry> - Unit - </entry> - </row> - </thead> - <tbody> - <row> - <entry><literal moreinfo="none">auth_cache_hits</literal> - </entry> - <entry> - Number of authentication cache hits - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">auth_cache_misses</literal> - </entry> - <entry> - Number of authentication cache misses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">database_reads</literal> - </entry> - <entry> - Number of times a document was read from a database - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">database_writes</literal> - </entry> - <entry> - Number of times a database was changed - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">open_databases</literal> - </entry> - <entry> - Number of open databases - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">open_os_files</literal> - </entry> - <entry> - Number of file descriptors CouchDB has open - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">request_time</literal> - </entry> - <entry> - Length of a request inside CouchDB without MochiWeb - </entry> - <entry> - milliseconds - </entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">httpd_request_methods</literal> - </para> - - <table> - <title><literal moreinfo="none">httpd_request_methods</literal> statistics</title> - <tgroup cols="3"> - <colspec colname="stat"/> - <colspec colname="desc"/> - <colspec colname="unit"/> - <thead> - <row> - <entry> - Statistic ID - </entry> - <entry> - Description - </entry> - <entry> - Unit - </entry> - </row> - </thead> - <tbody> - <row> - <entry><literal moreinfo="none">COPY</literal> - </entry> - <entry> - Number of HTTP COPY requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">DELETE</literal> - </entry> - <entry> - Number of HTTP DELETE requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">GET</literal> - </entry> - <entry> - Number of HTTP GET requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">HEAD</literal> - </entry> - <entry> - Number of HTTP HEAD requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">POST</literal> - </entry> - <entry> - Number of HTTP POST requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">PUT</literal> - </entry> - <entry> - Number of HTTP PUT requests - </entry> - <entry> - number - </entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">httpd_status_codes</literal> - </para> - - <table> - <title><literal moreinfo="none">httpd_status_codes</literal> statistics</title> - <tgroup cols="3"> - <colspec colname="stat"/> - <colspec colname="desc"/> - <colspec colname="unit"/> - <thead> - <row> - <entry> - Statistic ID - </entry> - <entry> - Description - </entry> - <entry> - Unit - </entry> - </row> - </thead> - <tbody> - <row> - <entry><literal moreinfo="none">200</literal> - </entry> - <entry> - Number of HTTP 200 OK responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">201</literal> - </entry> - <entry> - Number of HTTP 201 Created responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">202</literal> - </entry> - <entry> - Number of HTTP 202 Accepted responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">301</literal> - </entry> - <entry> - Number of HTTP 301 Moved Permanently responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">304</literal> - </entry> - <entry> - Number of HTTP 304 Not Modified responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">400</literal> - </entry> - <entry> - Number of HTTP 400 Bad Request responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">401</literal> - </entry> - <entry> - Number of HTTP 401 Unauthorized responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">403</literal> - </entry> - <entry> - Number of HTTP 403 Forbidden responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">404</literal> - </entry> - <entry> - Number of HTTP 404 Not Found responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">405</literal> - </entry> - <entry> - Number of HTTP 405 Method Not Allowed responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">409</literal> - </entry> - <entry> - Number of HTTP 409 Conflict responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">412</literal> - </entry> - <entry> - Number of HTTP 412 Precondition Failed responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">500</literal> - </entry> - <entry> - Number of HTTP 500 Internal Server Error responses - </entry> - <entry> - number - </entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - - <listitem> - <para> - <literal moreinfo="none">httpd</literal> - </para> - - <table> - <title><literal moreinfo="none">httpd</literal> statistics</title> - <tgroup cols="3"> - <colspec colname="stat"/> - <colspec colname="desc"/> - <colspec colname="unit"/> - <thead> - <row> - <entry> - Statistic ID - </entry> - <entry> - Description - </entry> - <entry> - Unit - </entry> - </row> - </thead> - <tbody> - <row> - <entry><literal moreinfo="none">bulk_requests</literal> - </entry> - <entry> - Number of bulk requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">clients_requesting_changes</literal> - </entry> - <entry> - Number of clients for continuous _changes - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">requests</literal> - </entry> - <entry> - Number of HTTP requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">temporary_view_reads</literal> - </entry> - <entry> - Number of temporary view reads - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal moreinfo="none">view_reads</literal> - </entry> - <entry> - Number of view reads - </entry> - <entry> - number - </entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - - </itemizedlist> - - <para> - You can also access individual statistics by quoting the - statistics sections and statistic ID as part of the URL path. For - example, to get the <literal moreinfo="none">request_time</literal> statistics, - you can use: - </para> - -<programlisting format="linespecific">GET /_stats/couchdb/request_time</programlisting> - - <para> - This returns an entire statistics object, as with the full - request, but containining only the request individual statistic. - Hence, the returned structure is as follows: - </para> - -<programlisting format="linespecific">{ - "couchdb" : { - "request_time" : { - "stddev" : 7454.305, - "min" : 1, - "max" : 34185, - "current" : 34697.803, - "mean" : 1652.276, - "sum" : 34697.803, - "description" : "length of a request inside CouchDB without MochiWeb" - } - } -}</programlisting> - - </section> - - <section id="couchdb-api-misc_utils_get"> - - <title><literal moreinfo="none">GET /_utils</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /_utils</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /_utils</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Administration interface - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Accesses the built-in Futon administration interface for CouchDB. - </para> - - </section> - - <section id="couchdb-api-misc_uuids_get"> - - <title><literal moreinfo="none">GET /_uuids</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /_uuids</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /_uuids</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - List of UUIDs - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">count</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Number of UUIDs to return - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - Requests one or more Universally Unique Identifiers (UUIDs) from - the CouchDB instance. The response is a JSON object providing a - list of UUIDs. For example: - </para> - -<programlisting format="linespecific">{ - "uuids" : [ - "7e4b5a14b22ec1cf8e58b9cdd0000da3" - ] -}</programlisting> - - <para> - You can use the <literal moreinfo="none">count</literal> argument to specify the - number of UUIDs to be returned. For example: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/_uuids?count=5</programlisting> - - <para> - Returns: - </para> - -<programlisting format="linespecific">{ - "uuids" : [ - "c9df0cdf4442f993fc5570225b405a80", - "c9df0cdf4442f993fc5570225b405bd2", - "c9df0cdf4442f993fc5570225b405e42", - "c9df0cdf4442f993fc5570225b4061a0", - "c9df0cdf4442f993fc5570225b406a20" - ] -}</programlisting> - - <para> - The UUID type is determined by the UUID type setting in the - CouchDB configuration. See - <xref linkend="couchdb-api-config_config-section-key_put"/>. - </para> - - <para> - For example, changing the UUID type to <literal moreinfo="none">random</literal>: - </para> - -<programlisting format="linespecific">PUT http://couchdb:5984/_config/uuids/algorithm -Content-Type: application/json -Accept: */* - -"random"</programlisting> - - <para> - When obtaining a list of UUIDs: - </para> - -<programlisting format="linespecific">{ - "uuids" : [ - "031aad7b469956cf2826fcb2a9260492", - "6ec875e15e6b385120938df18ee8e496", - "cff9e881516483911aa2f0e98949092d", - "b89d37509d39dd712546f9510d4a9271", - "2e0dbf7f6c4ad716f21938a016e4e59f" - ] -}</programlisting> - - </section> - - <section id="couchdb-api-misc_favicon_get"> - - <title><literal moreinfo="none">GET /favicon.ico</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /favicon.ico</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /favicon.ico</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Binary content for the favicon.ico site icon - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The requested content could not be found. The returned content - will include further information, as a JSON object, if available. - </entry></row></tbody></tgroup></informaltable> - - <para> - Returns the site icon. The return <literal moreinfo="none">Content-type</literal> - header is <literal moreinfo="none">image/x-icon</literal>, and the content stream - is the image data. - </para> - - </section> - -</chapter> - - <chapter id="couchdb-api-config"> - - <title>CouchDB API Server Configuration Methods</title> - - <para> - The CouchDB API Server Configuration Methods provide an interface to - query and update the various configuration values within a running - CouchDB instance. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-api-config-summary"><title>Configuration API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_config</literal></entry><entry><link linkend="couchdb-api-config_config_get"> - Obtain a list of the entire server configuration - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_config/section</literal></entry><entry><link linkend="couchdb-api-config_config-section_get"> - Get all the configuration values for the specified section - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_config/section/key</literal></entry><entry><link linkend="couchdb-api-config_config-section-key_get"> - Get a specific section/configuration value - </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/_config/section/key</literal></entry><entry><link linkend="couchdb-api-config_config-section-key_put"> - Set the specified configuration value - </link></entry></row><row><entry><literal moreinfo="none">DELETE</literal></entry><entry><literal moreinfo="none">/_config/section/key</literal></entry><entry><link linkend="couchdb-api-config_config-section-key_delete"> - Delete the current setting - </link></entry></row></tbody></tgroup></table> - - <section id="couchdb-api-config_config_get"> - - <title><literal moreinfo="none">GET /_config</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /_config</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /_config</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Returns a structure configuration name and value pairs, - organized by section - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Returns the entire CouchDB server configuration as a JSON - structure. The structure is organized by different configuration - sections, with individual values. - </para> - - <para> - For example, to get the configuration for a server: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/_config -Accept: application/json</programlisting> - - <para> - The response is the JSON structure: - </para> - -<programlisting format="linespecific">{ - "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}" - } -}</programlisting> - - </section> - - <section id="couchdb-api-config_config-section_get"> - - <title><literal moreinfo="none">GET /_config/section</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /_config/section</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /_config/section</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - All the configuration values within a specified section - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Gets the configuration structure for a single section. For - example, to retrieve the CouchDB configuration section values: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/_config/couchdb -Accept: application/json</programlisting> - - <para> - The returned JSON contains just the configuration values for this - section: - </para> - -<programlisting format="linespecific">{ - "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" -}</programlisting> - - </section> - - <section id="couchdb-api-config_config-section-key_get"> - - <title><literal moreinfo="none">GET /_config/section/key</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /_config/section/key</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /_config/section/key</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Value of the specified key/section - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Gets a single configuration value from within a specific - configuration section. For example, to obtain the current log - level: - </para> - -<programlisting format="linespecific">GET http://couchdb:5984/_config/log/level -Accept: application/json</programlisting> - - <para> - Returns the string of the log level: - </para> - -<programlisting format="linespecific">"info"</programlisting> - - <note> - <para> - 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. - </para> - </note> - - </section> - - <section id="couchdb-api-config_config-section-key_put"> - - <title><literal moreinfo="none">PUT /_config/section/key</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /_config/section/key</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /_config/section/key</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - Value structure - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Previous value - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Configuration option updated successfully - </entry></row><row><entry>500</entry><entry namest="info" nameend="addinfo"> - Error setting configuration - </entry></row></tbody></tgroup></informaltable> - - <para> - 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. - </para> - - <para> - For example, to set the function used to generate UUIDs by the - <literal moreinfo="none">GET /_uuids</literal> API call to use the - <literal moreinfo="none">utc_random</literal> generator: - </para> - -<programlisting format="linespecific">PUT http://couchdb:5984/_config/uuids/algorithm -Content-Type: application/json - -"utc_random"</programlisting> - - <para> - The return value will be empty, with the response code indicating - the success or failure of the configuration setting. - </para> - - </section> - - <section id="couchdb-api-config_config-section-key_delete"> - - <title><literal moreinfo="none">DELETE /_config/section/key</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API DELETE /_config/section/key</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">DELETE /_config/section/key</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Previous value - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal moreinfo="none">rev</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current revision of the document for validation - </entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal moreinfo="none">If-Match</literal></entry></row><row><entry/><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry/><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry/><entry/><entry/></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Supplied revision is incorrect or missing - </entry></row></tbody></tgroup></informaltable> - - <para> - 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: - </para> - -<programlisting format="linespecific">DELETE http://couchdb:5984/_config/uuids/algorithm -Content-Type: application/json</programlisting> - - <para> - The returned value is the last configured UUID function: - </para> - -<programlisting format="linespecific">"random"</programlisting> - - </section> - -</chapter> - - <chapter id="couchdb-api-auth"> - - <title>CouchDB API Server Authentication Methods</title> - - <para> - The CouchDB Authentication methods provide an interface for - obtaining session and authorization data. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-api-auth-summary"><title>Authentication API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_oauth/access_token</literal></entry><entry><link linkend="couchdb-api-auth_access-token_get"> - TBC - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_oauth/authorize</literal></entry><entry><link linkend="couchdb-api-auth_authorize_get"> - TBC - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/_oauth/authorize</literal></entry><entry><link linkend="couchdb-api-auth_authorize_post"> - TBC - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_oauth/request_token</literal></entry><entry><link linkend="couchdb-api-auth_authorize_get"> - TBC - </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/_session</literal></entry><entry><link linkend="couchdb-api-auth_session_get"> - Returns cookie based login user information - </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/_session</literal></entry><entry><link linkend="couchdb-api-auth_session_post"> - Do cookie based user login - </link></entry></row><row><entry><literal moreinfo="none">DELETE</literal></entry><entry><literal moreinfo="none">/_session</literal></entry><entry><link linkend="couchdb-api-auth_session_delete"> - Logout cookie based user - </link></entry></row></tbody></tgroup></table> - -</chapter> - - <chapter id="couchdb-single-configuration"> - - <title>Configuring CouchDB</title> - - <para> - - </para> - - <section id="couchdb-single-configuration-files"> - - <title>CouchDB Configuration Files</title> - - <para> - - </para> - - </section> - - <section id="couchdb-single-configuration-files-locations"> - - <title>Configuration File Locations</title> - - <para> - CouchDB reads files from the following locations, in the following - order. - </para> - - <orderedlist inheritnum="ignore" continuation="restarts"> - - <listitem> - <para> - <filename moreinfo="none">PREFIX/default.ini</filename> - </para> - </listitem> - - <listitem> - <para> - <filename moreinfo="none">PREFIX/default.d/*</filename> - </para> - </listitem> - - <listitem> - <para> - <filename moreinfo="none">PREFIX/local.ini</filename> - </para> - </listitem> - - <listitem> - <para> - <filename moreinfo="none">PREFIX/local.d/*</filename> - </para> - </listitem> - - </orderedlist> - - <para> - Settings in successive documents override the settings in earlier - entries. For example, setting the <literal moreinfo="none">bind_address</literal> - parameter in <filename moreinfo="none">local.ini</filename> would override any - setting in <literal moreinfo="none">default.ini</literal>. - </para> - - <warning> - <para> - The <filename moreinfo="none">default.ini</filename> file may be overwritten - during an upgrade or re-installation, so localised changes - should be made to the <filename moreinfo="none">local.ini</filename> file or - files within the <filename moreinfo="none">local.d</filename> directory. - </para> - </warning> - - </section> - - <section id="couchdb-single-configuration-mochiweb"> - - <title>MochiWeb Server Options</title> - - <para> - Server options for the MochiWeb component of CouchDB can be added - to the configuration files. Settings should be added to the - <literal moreinfo="none">server_options</literal> option of the - <literal moreinfo="none">[httpd]</literal> section of - <filename moreinfo="none">local.ini</filename>. For example: - </para> - -<programlisting format="linespecific">[httpd] -server_options = [{backlog, 128}, {acceptor_pool_size, 16}]</programlisting> - - </section> - - <section id="couchdb-single-configuration-osprocess"> - - <title>OS Daemons</title> - - <para> - CouchDB now supports starting external processes. The support is - simple and enables CouchDB to start each configured OS daemon. If - the daemon stops at any point, CouchDB will restart it (with - protection to ensure regularly failing daemons are not repeatedly - restarted). - </para> - - <para> - The daemon starting process is one-to-one; for each each - configured daemon in the configuration file, CouchDB will start - exactly one instance. If you need to run multiple instances, then - you must create separate individual configurations. Daemons are - configured within the <literal moreinfo="none">[os_daemons]</literal> section of - your configuration file (<filename moreinfo="none">local.ini</filename>). The - format of each configured daemon is: - </para> - -<programlisting format="linespecific">NAME = PATH ARGS</programlisting> - - <para> - Where <literal moreinfo="none">NAME</literal> is an arbitrary (and unique) name to - identify the daemon; <literal moreinfo="none">PATH</literal> is the full path to - the daemon to be executed; <literal moreinfo="none">ARGS</literal> are any - required arguments to the daemon. - </para> - - <para> - For example: - </para> - -<programlisting format="linespecific">[os_daemons] -basic_responder = /usr/local/bin/responsder.js</programlisting> - - <para> - There is no interactivity between CouchDB and the running process, - but you can use the OS Daemons service to create new HTTP servers - and responders and then use the new proxy service to redirect - requests and output to the CouchDB managed service. For more - information on proxying, see - <xref linkend="couchdb-single-features-proxying"/>. For - further background on the OS Daemon service, see - <ulink url="http://davispj.com/2010/09/26/new-couchdb-externals-api.html">CouchDB - Externals API</ulink> - </para> - - </section> - - <section id="couchdb-single-configuration-update_notification"> - - <title>Update Notifications</title> - - <para> - - </para> - - </section> - - <section id="couchdb-single-configuration-socketoptions"> - - <title>Socket Options Configuration Setting</title> - - <para> - The socket options for the listening socket in CouchDB can now be - set within the CouchDB configuration file. The setting should be - added to the <literal moreinfo="none">[httpd]</literal> section of the file using - the option name <literal moreinfo="none">socket_options</literal>. The - specification is as a list of tuples. For example: - </para> - -<programlisting format="linespecific">[httpd] -socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}]</programlisting> - - <para> - The options supported are a subset of full options supported by - the TCP/IP stack. A list of the supported options are provided in - the - <ulink url="http://www.erlang.org/doc/man/inet.html#setopts-2">Erlang - inet</ulink> documentation. - </para> - - </section> - - <section id="couchdb-single-configuration-vhost"> - - <title><literal moreinfo="none">vhosts</literal> definitions</title> - - <para> - Similar to the rewrites section of a <literal moreinfo="none">_design</literal> - document, the <literal moreinfo="none">vhosts</literal> system uses variables in - the form of :varname or wildcards in the form of asterisks. The - variable results can be output into the resulting path as they are - in the rewriter. - </para> - - </section> - - <section id="couchdb-single-configuration-ssl"> - - <title>Configuring SSL Network Sockets</title> - - <para> - SSL configuration in CouchDB was designed to be as easy as - possible. All you need is two files; a certificate and a private - key. If you bought an official SSL certificate from a certificate - authority, both should be in your possession already. - </para> - - <para> - If you just want to try this out and don't want to pay anything - upfront, you can create a self-signed certificate. Everything will - work the same, but clients will get a warning about an insecure - certificate. - </para> - - <para> - You will need the OpenSSL command line tool installed. It probably - already is. - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">mkdir cert && cd cert</userinput> -shell> <userinput moreinfo="none">openssl genrsa > privkey.pem</userinput> -shell> <userinput moreinfo="none">openssl req -new -x509 -key privkey.pem -out mycert.pem -days 1095</userinput> -shell> <userinput moreinfo="none">ls</userinput> -mycert.pem privkey.pem</programlisting> - - <para> - Now, you need to edit CouchDB's configuration, either by editing - your <filename moreinfo="none">local.ini</filename> file or using the - <literal moreinfo="none">/_config</literal> API calls or the configuration screen - in Futon. Here is what you need to do in - <filename moreinfo="none">local.ini</filename>, you can infer what needs doing in - the other places. - </para> - - <para> - Be sure to make these edits. Under <literal moreinfo="none">[daemons]</literal> - you should see: - </para> - -<programlisting format="linespecific">; enable SSL support by uncommenting the following line and supply the PEM's below. -; the default ssl port CouchDB listens on is 6984 -;httpsd = {couch_httpd, start_link, [https]}</programlisting> - - <para> - Here uncomment the last line: - </para> - -<programlisting format="linespecific">httpsd = {couch_httpd, start_link, [https]}</programlisting> - - <para> - Next, under <literal moreinfo="none">[ssl]</literal> you will see: - </para> - -<programlisting format="linespecific">;cert_file = /full/path/to/server_cert.pem -;key_file = /full/path/to/server_key.pem</programlisting> - - <para> - Uncomment and adjust the paths so it matches your system's paths: - </para> - -<programlisting format="linespecific">cert_file = /home/jan/cert/mycert.pem -key_file = /home/jan/cert/privkey.pem</programlisting> - - <para> - For more information please read - <ulink url="http://www.openssl.org/docs/HOWTO/certificates.txt">http://www.openssl.org/docs/HOWTO/certificates.txt</ulink>. - </para> - - <para> - Now start (or restart) CouchDB. You should be able to connect to - it using HTTPS on port 6984: - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">curl https://127.0.0.1:6984/</userinput> -curl: (60) SSL certificate problem, verify that the CA cert is OK. Details: -error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed -More details here: http://curl.haxx.se/docs/sslcerts.html - -curl performs SSL certificate verification by default, using a "bundle" -of Certificate Authority (CA) public keys (CA certs). If the default -bundle file isn't adequate, you can specify an alternate file -using the --cacert option. -If this HTTPS server uses a certificate signed by a CA represented in -the bundle, the certificate verification probably failed due to a -problem with the certificate (it might be expired, or the name might -not match the domain name in the URL). -If you'd like to turn off curl's verification of the certificate, use -the -k (or --insecure) option.</programlisting> - - <para> - Oh no what happened?! — Remember, clients will notify their - users that your certificate is self signed. - <command moreinfo="none">curl</command> is the client in this case and it notifies - you. Luckily you trust yourself (don't you?) and you can specify - the <option>-k</option> option as the message reads: - </para> - -<programlisting format="linespecific">shell> <userinput moreinfo="none">curl -k https://127.0.0.1:6984/</userinput> -{"couchdb":"Welcome","version":"1.1.0"}</programlisting> - - </section> - - <section id="couchdb-single-config-options"> - - <title>CouchDB Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="section"/><colspec colname="desc"/><thead><row><entry>Section</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">attachments</literal></entry><entry> - Attachment options - </entry></row><row><entry><literal moreinfo="none">couchdb</literal></entry><entry> - CouchDB specific options - </entry></row><row><entry><literal moreinfo="none">daemons</literal></entry><entry> - Daemons and background processes - </entry></row><row><entry><literal moreinfo="none">httpd_db_handlers</literal></entry><entry> - Database Operation handlers - </entry></row><row><entry><literal moreinfo="none">couch_httpd_auth</literal></entry><entry> - HTTPD Authentication options - </entry></row><row><entry><literal moreinfo="none">httpd</literal></entry><entry> - HTTPD Server options - </entry></row><row><entry><literal moreinfo="none">httpd_design_handlers</literal></entry><entry> - Handlers for design document operations - </entry></row><row><entry><literal moreinfo="none">httpd_global_handlers</literal></entry><entry> - Handlers for global operations - </entry></row><row><entry><literal moreinfo="none">log</literal></entry><entry> - Logging options - </entry></row><row><entry><literal moreinfo="none">query_servers</literal></entry><entry> - Query Server options - </entry></row><row><entry><literal moreinfo="none">query_server_config</literal></entry><entry> - Query server options - </entry></row><row><entry><literal moreinfo="none">replicator</literal></entry><entry> - Replicator Options - </entry></row><row><entry><literal moreinfo="none">ssl</literal></entry><entry> - SSL (Secure Sockets Layer) Options - </entry></row><row><entry><literal moreinfo="none">stats</literal></entry><entry> - Statistics options - </entry></row><row><entry><literal moreinfo="none">uuids</literal></entry><entry> - UUID generation options - </entry></row></tbody></tgroup></table> - - <section id="couchdb-single-config-options_attachments"> - - <title><literal moreinfo="none">attachments</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-attachments-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">compressible_types</literal></entry><entry> - compressible_types - </entry></row><row><entry><literal moreinfo="none">compression_level</literal></entry><entry> - compression_level - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_couchdb"> - - <title><literal moreinfo="none">couchdb</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-couchdb-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">database_dir</literal></entry><entry> - database_dir - </entry></row><row><entry><literal moreinfo="none">delayed_commits</literal></entry><entry> - delayed_commits - </entry></row><row><entry><literal moreinfo="none">max_attachment_chunk_size</literal></entry><entry> - max_attachment_chunk_size - </entry></row><row><entry><literal moreinfo="none">max_dbs_open</literal></entry><entry> - max_dbs_open - </entry></row><row><entry><literal moreinfo="none">max_document_size</literal></entry><entry> - max_document_size - </entry></row><row><entry><literal moreinfo="none">os_process_timeout</literal></entry><entry> - os_process_timeout - </entry></row><row><entry><literal moreinfo="none">uri_file</literal></entry><entry> - uri_file - </entry></row><row><entry><literal moreinfo="none">util_driver_dir</literal></entry><entry> - util_driver_dir - </entry></row><row><entry><literal moreinfo="none">view_index_dir</literal></entry><entry> - view_index_dir - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_daemons"> - - <title><literal moreinfo="none">daemons</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-daemons-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">httpsd</literal></entry><entry> - Enabled HTTPS service - </entry></row><row><entry><literal moreinfo="none">auth_cache</literal></entry><entry> - auth_cache - </entry></row><row><entry><literal moreinfo="none">db_update_notifier</literal></entry><entry> - db_update_notifier - </entry></row><row><entry><literal moreinfo="none">external_manager</literal></entry><entry> - external_manager - </entry></row><row><entry><literal moreinfo="none">httpd</literal></entry><entry> - httpd - </entry></row><row><entry><literal moreinfo="none">query_servers</literal></entry><entry> - query_servers - </entry></row><row><entry><literal moreinfo="none">stats_aggregator</literal></entry><entry> - stats_aggregator - </entry></row><row><entry><literal moreinfo="none">stats_collector</literal></entry><entry> - stats_collector - </entry></row><row><entry><literal moreinfo="none">uuids</literal></entry><entry> - uuids - </entry></row><row><entry><literal moreinfo="none">view_manager</literal></entry><entry> - view_manager - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_httpd_db_handlers"> - - <title><literal moreinfo="none">httpd_db_handlers</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-httpd_db_handlers-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">_changes</literal></entry><entry> - _changes - </entry></row><row><entry><literal moreinfo="none">_compact</literal></entry><entry> - _compact - </entry></row><row><entry><literal moreinfo="none">_design</literal></entry><entry> - _design - </entry></row><row><entry><literal moreinfo="none">_temp_view</literal></entry><entry> - _temp_view - </entry></row><row><entry><literal moreinfo="none">_view_cleanup</literal></entry><entry> - _view_cleanup - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_couch_httpd_auth"> - - <title><literal moreinfo="none">couch_httpd_auth</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-couch_httpd_auth-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">auth_cache_size</literal></entry><entry> - auth_cache_size - </entry></row><row><entry><literal moreinfo="none">authentication_db</literal></entry><entry> - authentication_db - </entry></row><row><entry><literal moreinfo="none">authentication_redirect</literal></entry><entry> - authentication_redirect - </entry></row><row><entry><literal moreinfo="none">require_valid_user</literal></entry><entry> - require_valid_user - </entry></row><row><entry><literal moreinfo="none">timeout</literal></entry><entry> - timeout - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_httpd"> - - <title><literal moreinfo="none">httpd</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-httpd-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">nodelay</literal></entry><entry> - Enable TCP_NODELAY - </entry></row><row><entry><literal moreinfo="none">allow_jsonp</literal></entry><entry> - allow_jsonp - </entry></row><row><entry><literal moreinfo="none">authentication_handlers</literal></entry><entry> - authentication_handlers - </entry></row><row><entry><literal moreinfo="none">bind_address</literal></entry><entry> - bind_address - </entry></row><row><entry><literal moreinfo="none">default_handler</literal></entry><entry> - default_handler - </entry></row><row><entry><literal moreinfo="none">max_connections</literal></entry><entry> - max_connections - </entry></row><row><entry><literal moreinfo="none">port</literal></entry><entry> - port - </entry></row><row><entry><literal moreinfo="none">secure_rewrites</literal></entry><entry> - secure_rewrites - </entry></row><row><entry><literal moreinfo="none">vhost_global_handlers</literal></entry><entry> - vhost_global_handlers - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_httpd_design_handlers"> - - <title><literal moreinfo="none">httpd_design_handlers</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-httpd_design_handlers-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">_info</literal></entry><entry> - _info - </entry></row><row><entry><literal moreinfo="none">_list</literal></entry><entry> - _list - </entry></row><row><entry><literal moreinfo="none">_rewrite</literal></entry><entry> - _rewrite - </entry></row><row><entry><literal moreinfo="none">_show</literal></entry><entry> - _show - </entry></row><row><entry><literal moreinfo="none">_update</literal></entry><entry> - _update - </entry></row><row><entry><literal moreinfo="none">_view</literal></entry><entry> - _view - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_httpd_global_handlers"> - - <title><literal moreinfo="none">httpd_global_handlers</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-httpd_global_handlers-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">/</literal></entry><entry> - / - </entry></row><row><entry><literal moreinfo="none">_active_tasks</literal></entry><entry> - _active_tasks - </entry></row><row><entry><literal moreinfo="none">_all_dbs</literal></entry><entry> - _all_dbs - </entry></row><row><entry><literal moreinfo="none">_config</literal></entry><entry> - _config - </entry></row><row><entry><literal moreinfo="none">_log</literal></entry><entry> - _log - </entry></row><row><entry><literal moreinfo="none">_oauth</literal></entry><entry> - _oauth - </entry></row><row><entry><literal moreinfo="none">_replicate</literal></entry><entry> - _replicate - </entry></row><row><entry><literal moreinfo="none">_restart</literal></entry><entry> - _restart - </entry></row><row><entry><literal moreinfo="none">_session</literal></entry><entry> - _session - </entry></row><row><entry><literal moreinfo="none">_stats</literal></entry><entry> - _stats - </entry></row><row><entry><literal moreinfo="none">_utils</literal></entry><entry> - _utils - </entry></row><row><entry><literal moreinfo="none">_uuids</literal></entry><entry> - _uuids - </entry></row><row><entry><literal moreinfo="none">favicon.ico</literal></entry><entry> - favicon.ico - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_log"> - - <title><literal moreinfo="none">log</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-log-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">file</literal></entry><entry> - file - </entry></row><row><entry><literal moreinfo="none">include_sasl</literal></entry><entry> - include_sasl - </entry></row><row><entry><literal moreinfo="none">level</literal></entry><entry> - level - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_query_servers"> - - <title><literal moreinfo="none">query_servers</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-query_servers-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">javascript</literal></entry><entry> - javascript - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_query_server_config"> - - <title><literal moreinfo="none">query_server_config</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-query_server_config-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">reduce_limit</literal></entry><entry> - reduce_limit - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_replicator"> - - <title><literal moreinfo="none">replicator</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-replicator-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">max_http_pipeline_size</literal></entry><entry> - max_http_pipeline_size - </entry></row><row><entry><literal moreinfo="none">max_http_sessions</literal></entry><entry> - max_http_sessions - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_stats"> - - <title><literal moreinfo="none">stats</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-stats-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">rate</literal></entry><entry> - rate - </entry></row><row><entry><literal moreinfo="none">samples</literal></entry><entry> - samples - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_uuids"> - - <title><literal moreinfo="none">uuids</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-uuids-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">algorithm</literal></entry><entry> - algorithm - </entry></row></tbody></tgroup></table> - - </section> - -</section> - -</chapter> - - - - <appendix id="couchdb-api-json"> - - <title>JSON Structure Reference</title> - - <para> - The following appendix provides a quick reference to all the JSON - structures that you can supply to CouchDB, or get in return to - requests. - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-json-summary"><title>JSON Structures</title><tgroup cols="1"><colspec colname="desc"/><thead><row><entry>Description</entry></row></thead><tbody><row><entry><link linkend="table-couchdb-api-json_all-docs"> - All Database Documents - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_bulkdocsreturn"> - Bulk Document Response - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_bulkdocs"> - Bulk Documents - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_changes"> - Changes information for a database - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_document"> - CouchDB Document - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_jsonerror"> - CouchDB Error Status - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_db-info"> - CouchDB database information object - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_design-doc"> - Design Document - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_design-doc_info"> - Design Document Information - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_design-doc_info-spatial"> - Design Document spatial index Information - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_document_with_attachments"> - Document with Attachments - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_activetasks"> - List of Active Tasks - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_replication"> - Replication Settings - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_replication-status"> - Replication Status - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_document_with_revs_info"> - Returned CouchDB Document with Detailed Revision Info - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_document_with_revs"> - Returned CouchDB Document with Revision Info - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_returneddocument_with_attachments"> - Returned Document with Attachments - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_security"> - Security Object - </link></entry></row></tbody></tgroup></table> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-json_all-docs" class="jsonstructure"><title> - All Database Documents - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">offset</literal> </entry><entry> - Offset where the document list started - </entry></row><row><entry><literal moreinfo="none">rows</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Array of document object - </entry></row><row><entry><literal moreinfo="none">total_rows</literal> </entry><entry> - Number of documents in the database/view - </entry></row><row><entry><literal moreinfo="none">update_seq</literal> (optional) </entry><entry> - Current update sequence for the database - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_bulkdocsreturn" class="jsonstructure"><title> - Bulk Document Response - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">docs</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Bulk Docs Returned Documents - </entry></row><row><entry> <literal moreinfo="none">error</literal> </entry><entry> - Error type - </entry></row><row><entry> <literal moreinfo="none">id</literal> </entry><entry> - Document ID - </entry></row><row><entry> <literal moreinfo="none">reason</literal> </entry><entry> - Error string with extended reason - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_bulkdocs" class="jsonstructure"><title> - Bulk Documents - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">all_or_nothing</literal> (optional) </entry><entry> - Sets the database commit mode to use all-or-nothing semantics - </entry></row><row><entry><literal moreinfo="none">docs</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Bulk Documents Document - </entry></row><row><entry> <literal moreinfo="none">_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry> <literal moreinfo="none">_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry> <literal moreinfo="none">_deleted</literal> (optional) </entry><entry> - Whether the document should be deleted - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_changes" class="jsonstructure"><title> - Changes information for a database - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">last_seq</literal> </entry><entry> - Last change sequence number - </entry></row><row><entry><literal moreinfo="none">results</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Changes made to a database - </entry></row><row><entry> <literal moreinfo="none">changes</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - List of changes, field-by-field, for this document - </entry></row><row><entry> <literal moreinfo="none">id</literal> </entry><entry> - Document ID - </entry></row><row><entry> <literal moreinfo="none">seq</literal> </entry><entry> - Update sequence number - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_document" class="jsonstructure"><title> - CouchDB Document - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry><literal moreinfo="none">_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_jsonerror" class="jsonstructure"><title> - CouchDB Error Status - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">error</literal> </entry><entry> - Error type - </entry></row><row><entry><literal moreinfo="none">id</literal> </entry><entry> - Document ID - </entry></row><row><entry><literal moreinfo="none">reason</literal> </entry><entry> - Error string with extended reason - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_db-info" class="jsonstructure"><title> - CouchDB database information object - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">committed_update_seq</literal> </entry><entry> - The number of committed update. - </entry></row><row><entry><literal moreinfo="none">compact_running</literal> </entry><entry> - Set to true if the database compaction routine is operating on - this database. - </entry></row><row><entry><literal moreinfo="none">db_name</literal> </entry><entry> - The name of the database. - </entry></row><row><entry><literal moreinfo="none">disk_format_version</literal> </entry><entry> - The version of the physical format used for the data when it is - stored on disk. - </entry></row><row><entry><literal moreinfo="none">disk_size</literal> </entry><entry> - Size in bytes of the data as stored on the disk. Views indexes - are not included in the calculation. - </entry></row><row><entry><literal moreinfo="none">doc_count</literal> </entry><entry> - A count of the documents in the specified database. - </entry></row><row><entry><literal moreinfo="none">doc_del_count</literal> </entry><entry> - Number of deleted documents - </entry></row><row><entry><literal moreinfo="none">instance_start_time</literal> </entry><entry> - Timestamp of when the database was created, expressed in - milliseconds since the epoch. - </entry></row><row><entry><literal moreinfo="none">purge_seq</literal> </entry><entry> - The number of purge operations on the database. - </entry></row><row><entry><literal moreinfo="none">update_seq</literal> </entry><entry> - The current number of updates to the database. - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_design-doc" class="jsonstructure"><title> - Design Document - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">_id</literal> </entry><entry> - Design Document ID - </entry></row><row><entry><literal moreinfo="none">_rev</literal> </entry><entry> - Design Document Revision - </entry></row><row><entry><literal moreinfo="none">views</literal> </entry><entry> - View - </entry></row><row><entry> <literal moreinfo="none">viewname</literal> </entry><entry> - View Definition - </entry></row><row><entry> <literal moreinfo="none">map</literal> </entry><entry> - Map Function for View - </entry></row><row><entry> <literal moreinfo="none">reduce</literal> (optional) </entry><entry> - Reduce Function for View - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_design-doc_info" class="jsonstructure"><title> - Design Document Information - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">name</literal> </entry><entry> - Name/ID of Design Document - </entry></row><row><entry><literal moreinfo="none">view_index</literal> </entry><entry> - View Index - </entry></row><row><entry> <literal moreinfo="none">compact_running</literal> </entry><entry> - Indicates whether a compaction routine is currently running on - the view - </entry></row><row><entry> <literal moreinfo="none">disk_size</literal> </entry><entry> - Size in bytes of the view as stored on disk - </entry></row><row><entry> <literal moreinfo="none">language</literal> </entry><entry> - Language for the defined views - </entry></row><row><entry> <literal moreinfo="none">purge_seq</literal> </entry><entry> - The purge sequence that has been processed - </entry></row><row><entry> <literal moreinfo="none">signature</literal> </entry><entry> - MD5 signature of the views for the design document - </entry></row><row><entry> <literal moreinfo="none">update_seq</literal> </entry><entry> - The update sequence of the corresponding database that has been - indexed - </entry></row><row><entry> <literal moreinfo="none">updater_running</literal> </entry><entry> - Indicates if the view is currently being updated - </entry></row><row><entry> <literal moreinfo="none">waiting_clients</literal> </entry><entry> - Number of clients waiting on views from this design document - </entry></row><row><entry> <literal moreinfo="none">waiting_commit</literal> </entry><entry> - Indicates if there are outstanding commits to the underlying - database that need to processed - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_design-doc_info-spatial" class="jsonstructure"><title> - Design Document spatial index Information - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">name</literal> </entry><entry> - Name/ID of Design Document - </entry></row><row><entry><literal moreinfo="none">spatial_index</literal> </entry><entry> - View Index - </entry></row><row><entry> <literal moreinfo="none">compact_running</literal> </entry><entry> - Indicates whether a compaction routine is currently running on - the view - </entry></row><row><entry> <literal moreinfo="none">disk_size</literal> </entry><entry> - Size in bytes of the view as stored on disk - </entry></row><row><entry> <literal moreinfo="none">language</literal> </entry><entry> - Language for the defined views - </entry></row><row><entry> <literal moreinfo="none">purge_seq</literal> </entry><entry> - The purge sequence that has been processed - </entry></row><row><entry> <literal moreinfo="none">signature</literal> </entry><entry> - MD5 signature of the views for the design document - </entry></row><row><entry> <literal moreinfo="none">update_seq</literal> </entry><entry> - The update sequence of the corresponding database that has been - indexed - </entry></row><row><entry> <literal moreinfo="none">updater_running</literal> </entry><entry> - Indicates if the view is currently being updated - </entry></row><row><entry> <literal moreinfo="none">waiting_clients</literal> </entry><entry> - Number of clients waiting on views from this design document - </entry></row><row><entry> <literal moreinfo="none">waiting_commit</literal> </entry><entry> - Indicates if there are outstanding commits to the underlying - database that need to processed - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_document_with_attachments" class="jsonstructure"><title> - Document with Attachments - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry><literal moreinfo="none">_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry><literal moreinfo="none">_attachments</literal> (optional) </entry><entry> - Document Attachment - </entry></row><row><entry> <literal moreinfo="none">filename</literal> </entry><entry> - Attachment information - </entry></row><row><entry> <literal moreinfo="none">content_type</literal> </entry><entry> - MIME Content type string - </entry></row><row><entry> <literal moreinfo="none">data</literal> </entry><entry> - File attachment content, Base64 encoded - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_activetasks" class="jsonstructure"><title> - List of Active Tasks - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">tasks</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Active Task - </entry></row><row><entry> <literal moreinfo="none">pid</literal> </entry><entry> - Process ID - </entry></row><row><entry> <literal moreinfo="none">status</literal> </entry><entry> - Task status message - </entry></row><row><entry> <literal moreinfo="none">task</literal> </entry><entry> - Task name - </entry></row><row><entry> <literal moreinfo="none">type</literal> </entry><entry> - Operation Type - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_replication" class="jsonstructure"><title> - Replication Settings - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">cancel</literal> (optional) </entry><entry> - Cancels the replication - </entry></row><row><entry><literal moreinfo="none">continuous</literal> (optional) </entry><entry> - Configure the replication to be continuous - </entry></row><row><entry><literal moreinfo="none">create_target</literal> (optional) </entry><entry> - Creates the target database - </entry></row><row><entry><literal moreinfo="none">doc_ids</literal> (optional) </entry><entry> - Array of document IDs to be synchronized - </entry></row><row><entry><literal moreinfo="none">proxy</literal> (optional) </entry><entry> - Address of a proxy server through which replication should occur - </entry></row><row><entry><literal moreinfo="none">source</literal> </entry><entry> - Source database name or URL - </entry></row><row><entry><literal moreinfo="none">target</literal> </entry><entry> - Target database name or URL - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_replication-status" class="jsonstructure"><title> - Replication Status - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">history</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Replication History - </entry></row><row><entry> <literal moreinfo="none">doc_write_failures</literal> </entry><entry> - Number of document write failures - </entry></row><row><entry> <literal moreinfo="none">docs_read</literal> </entry><entry> - Number of documents read - </entry></row><row><entry> <literal moreinfo="none">docs_written</literal> </entry><entry> - Number of documents written to target - </entry></row><row><entry> <literal moreinfo="none">end_last_seq</literal> </entry><entry> - Last sequence number in changes stream - </entry></row><row><entry> <literal moreinfo="none">end_time</literal> </entry><entry> - Date/Time replication operation completed - </entry></row><row><entry> <literal moreinfo="none">missing_checked</literal> </entry><entry> - Number of missing documents checked - </entry></row><row><entry> <literal moreinfo="none">missing_found</literal> </entry><entry> - Number of missing documents found - </entry></row><row><entry> <literal moreinfo="none">recorded_seq</literal> </entry><entry> - Last recorded sequence number - </entry></row><row><entry> <literal moreinfo="none">session_id</literal> </entry><entry> - Session ID for this replication operation - </entry></row><row><entry> <literal moreinfo="none">start_last_seq</literal> </entry><entry> - First sequence number in changes stream - </entry></row><row><entry> <literal moreinfo="none">start_time</literal> </entry><entry> - Date/Time replication operation started - </entry></row><row><entry><literal moreinfo="none">ok</literal> </entry><entry> - Replication status - </entry></row><row><entry><literal moreinfo="none">session_id</literal> </entry><entry> - Unique session ID - </entry></row><row><entry><literal moreinfo="none">source_last_seq</literal> </entry><entry> - Last sequence number read from source database - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_document_with_revs_info" class="jsonstructure"><title> - Returned CouchDB Document with Detailed Revision Info - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry><literal moreinfo="none">_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry><literal moreinfo="none">_revs_info</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - CouchDB Document Extended Revision Info - </entry></row><row><entry> <literal moreinfo="none">rev</literal> </entry><entry> - Full revision string - </entry></row><row><entry> <literal moreinfo="none">status</literal> </entry><entry> - Status of the revision - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_document_with_revs" class="jsonstructure"><title> - Returned CouchDB Document with Revision Info - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry><literal moreinfo="none">_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry><literal moreinfo="none">_revisions</literal> </entry><entry> - CouchDB Document Revisions - </entry></row><row><entry> <literal moreinfo="none">ids</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - Array of valid revision IDs, in reverse order (latest first) - </entry></row><row><entry> <literal moreinfo="none">start</literal> </entry><entry> - Prefix number for the latest revision - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_returneddocument_with_attachments" class="jsonstructure"><title> - Returned Document with Attachments - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry><literal moreinfo="none">_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry><literal moreinfo="none">_attachments</literal> (optional) </entry><entry> - Document Attachment - </entry></row><row><entry> <literal moreinfo="none">filename</literal> </entry><entry> - Attachment - </entry></row><row><entry> <literal moreinfo="none">content_type</literal> </entry><entry> - MIME Content type string - </entry></row><row><entry> <literal moreinfo="none">length</literal> </entry><entry> - Length (bytes) of the attachment data - </entry></row><row><entry> <literal moreinfo="none">revpos</literal> </entry><entry> - Revision where this attachment exists - </entry></row><row><entry> <literal moreinfo="none">stub</literal> </entry><entry> - Indicates whether the attachment is a stub - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_security" class="jsonstructure"><title> - Security Object - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">admins</literal> </entry><entry> - Roles/Users with admin privileges - </entry></row><row><entry> <literal moreinfo="none">roles</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - List of roles with parent privilege - </entry></row><row><entry> <literal moreinfo="none">users</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - List of users with parent privilege - </entry></row><row><entry><literal moreinfo="none">readers</literal> </entry><entry> - Roles/Users with reader privileges - </entry></row><row><entry> <literal moreinfo="none">roles</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - List of roles with parent privilege - </entry></row><row><entry> <literal moreinfo="none">users</literal> <literal moreinfo="none">[array]</literal> </entry><entry> - List of users with parent privilege - </entry></row></tbody></tgroup></table> - -</appendix> - -</book> diff --git a/share/docs/couchdb-manual-1.1/couchdb-manual.xml b/share/docs/couchdb-manual-1.1/couchdb-manual.xml deleted file mode 100644 index 3404b9270..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-manual.xml +++ /dev/null @@ -1,65 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<book id="couchdb-__meta_version_id__"> - - <title>CouchDB __meta_version__ Manual</title> - - <bookinfo> - - <abstract> - - <para> - This manual documents the CouchDB - __meta_version__ database system, including the installation, - functionality, and CouchDB API. - </para> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../common/docbuilddate.xml"/> - - </abstract> - - </bookinfo> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="couchdb-introduction.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="couchdb-features.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="couchdb-replication.xml"/> - -<!-- - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="metadoc-couchdb-changes.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="couchdb-dbmaint.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="couchdb-views.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="couchdb-backuprestore.xml"/> ---> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="couchdb-api-introduction.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="metadoc-couchdb-api-db.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="metadoc-couchdb-api-dbdoc.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="metadoc-couchdb-api-localdb.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="metadoc-couchdb-api-design.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="metadoc-couchdb-api-misc.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="metadoc-couchdb-api-config.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="metadoc-couchdb-api-auth.xml"/> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="couchdb-configuration.xml"/> - -<!-- Appendices --> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="metadoc-couchdb-api-json.xml"/> - -</book> diff --git a/share/docs/couchdb-manual-1.1/couchdb-replication.xml b/share/docs/couchdb-manual-1.1/couchdb-replication.xml deleted file mode 100644 index a62a88434..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-replication.xml +++ /dev/null @@ -1,554 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-single-replication"> - - <title>Replication</title> - - <para> - - </para> - - <section id="couchdb-single-replication-replicatordb"> - - <title>Replicator Database</title> - - <para> - A database where you - <literal>PUT</literal>/<literal>POST</literal> documents to - trigger replications and you <literal>DELETE</literal> to cancel - ongoing replications. These documents have exactly the same - content as the JSON objects we used to <literal>POST</literal> to - <literal>_replicate</literal> (fields <literal>source</literal>, - <literal>target</literal>, <literal>create_target</literal>, - <literal>continuous</literal>, <literal>doc_ids</literal>, - <literal>filter</literal>, <literal>query_params</literal>. - </para> - - <para> - Replication documents can have a user defined - <literal>_id</literal>. Design documents (and - <literal>_local</literal> documents) added to the replicator - database are ignored. - </para> - - <para> - The default name of this database is - <literal>_replicator</literal>. The name can be changed in the - <filename>local.ini</filename> configuration, section - <literal>[replicator]</literal>, parameter <literal>db</literal>. - </para> - - <section id="couchdb-single-replication-replicatordb-basics"> - - <title>Basics</title> - - <para> - Let's say you PUT the following document into _replicator: - </para> - -<programlisting> -{ - "_id": "my_rep", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "create_target": true -} -</programlisting> - - <para> - In the couch log you'll see 2 entries like these: - </para> - -<programlisting> -[Thu, 17 Feb 2011 19:43:59 GMT] [info] [<0.291.0>] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target` -[Thu, 17 Feb 2011 19:44:37 GMT] [info] [<0.124.0>] Replication `c0ebe9256695ff083347cbf95f93e280+create_target` finished (triggered by document `my_rep`) -</programlisting> - - <para> - As soon as the replication is triggered, the document will be - updated by CouchDB with 3 new fields: - </para> - -<programlisting> -{ - "_id": "my_rep", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "create_target": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -} -</programlisting> - - <para> - Special fields set by the replicator start with the prefix - <literal>_replication_</literal>. - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>_replication_id</literal> - </para> - - <para> - The ID internally assigned to the replication. This is also - the ID exposed by <literal>/_active_tasks</literal>. - </para> - </listitem> - - <listitem> - <para> - <literal>_replication_state</literal> - </para> - - <para> - The current state of the replication. - </para> - </listitem> - - <listitem> - <para> - <literal>_replication_state_time</literal> - </para> - - <para> - A Unix timestamp (number of seconds since 1 Jan 1970) that - tells us when the current replication state (marked in - <literal>_replication_state</literal>) was set. - </para> - </listitem> - - </itemizedlist> - - <para> - When the replication finishes, it will update the - <literal>_replication_state</literal> field (and - <literal>_replication_state_time</literal>) with the value - <literal>completed</literal>, so the document will look like: - </para> - -<programlisting> -{ - "_id": "my_rep", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "create_target": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "completed", - "_replication_state_time": 1297974122 -} -</programlisting> - - <para> - When an error happens during replication, the - <literal>_replication_state</literal> field is set to - <literal>error</literal> (and - <literal>_replication_state</literal> gets updated of course). - </para> - - <para> - When you PUT/POST a document to the - <literal>_replicator</literal> database, CouchDB will attempt to - start the replication up to 10 times (configurable under - <literal>[replicator]</literal>, parameter - <literal>max_replication_retry_count</literal>). If it fails on - the first attempt, it waits 5 seconds before doing a second - attempt. If the second attempt fails, it waits 10 seconds before - doing a third attempt. If the third attempt fails, it waits 20 - seconds before doing a fourth attempt (each attempt doubles the - previous wait period). When an attempt fails, the Couch log will - show you something like: - </para> - -<programlisting> -[error] [<0.149.0>] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,<<"could not open http://myserver:5986/foo/">> -</programlisting> - - <note> - <para> - The <literal>_replication_state</literal> field is only set to - <literal>error</literal> when all the attempts were - unsuccessful. - </para> - </note> - - <para> - There are only 3 possible values for the - <literal>_replication_state</literal> field: - <literal>triggered</literal>, <literal>completed</literal> and - <literal>error</literal>. Continuous replications never get - their state set to <literal>completed</literal>. - </para> - - </section> - - <section id="couchdb-single-replication-replicatordb-docsame"> - - <title>Documents describing the same replication</title> - - <para> - Lets suppose 2 documents are added to the - <literal>_replicator</literal> database in the following order: - </para> - -<programlisting> -{ - "_id": "doc_A", - "source": "http://myserver.com:5984/foo", - "target": "bar" -} -</programlisting> - - <para> - and - </para> - -<programlisting> -{ - "_id": "doc_B", - "source": "http://myserver.com:5984/foo", - "target": "bar" -} -</programlisting> - - <para> - Both describe exactly the same replication (only their - <literal>_ids</literal> differ). In this case document - <literal>doc_A</literal> triggers the replication, getting - updated by CouchDB with the fields - <literal>_replication_state</literal>, - <literal>_replication_state_time</literal> and - <literal>_replication_id</literal>, just like it was described - before. Document <literal>doc_B</literal> however, is only - updated with one field, the <literal>_replication_id</literal> - so it will look like this: - </para> - -<programlisting> -{ - "_id": "doc_B", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "_replication_id": "c0ebe9256695ff083347cbf95f93e280" -} -</programlisting> - - <para> - While document <literal>doc_A</literal> will look like this: - </para> - -<programlisting> -{ - "_id": "doc_A", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -} -</programlisting> - - <para> - Note that both document get exactly the same value for the - <literal>_replication_id</literal> field. This way you can - identify which documents refer to the same replication - you can - for example define a view which maps replication IDs to document - IDs. - </para> - - </section> - - <section id="couchdb-single-replication-replicatordb-cancel"> - - <title>Canceling replications</title> - - <para> - To cancel a replication simply <literal>DELETE</literal> the - document which triggered the replication. The Couch log will - show you an entry like the following: - </para> - -<programlisting> -[Thu, 17 Feb 2011 20:16:29 GMT] [info] [<0.125.0>] Stopped replication `c0ebe9256695ff083347cbf95f93e280+continuous+create_target` because replication document `doc_A` was deleted -</programlisting> - - <note> - <para> - You need to <literal>DELETE</literal> the document that - triggered the replication. <literal>DELETE</literal>ing - another document that describes the same replication but did - not trigger it, will not cancel the replication. - </para> - </note> - - </section> - - <section id="couchdb-single-replication-replicatordb-restart"> - - <title>Server restart</title> - - <para> - When CouchDB is restarted, it checks its - <literal>_replicator</literal> database and restarts any - replication that is described by a document that either has its - <literal>_replication_state</literal> field set to - <literal>triggered</literal> or it doesn't have yet the - <literal>_replication_state</literal> field set. - </para> - - <note> - <para> - Continuous replications always have a - <literal>_replication_state</literal> field with the value - <literal>triggered</literal>, therefore they're always - restarted when CouchDB is restarted. - </para> - </note> - - </section> - - <section id="couchdb-single-replication-replicatordb-changing"> - - <title>Changing the Replicator Database</title> - - <para> - Imagine your replicator database (default name is _replicator) - has the two following documents that represent pull replications - from servers A and B: - </para> - -<programlisting> -{ - "_id": "rep_from_A", - "source": "http://aserver.com:5984/foo", - "target": "foo_a", - "continuous": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297971311 -} -{ - "_id": "rep_from_B", - "source": "http://bserver.com:5984/foo", - "target": "foo_b", - "continuous": true, - "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -} -</programlisting> - - <para> - Now without stopping and restarting CouchDB, you change the name - of the replicator database to - <literal>another_replicator_db</literal>: - </para> - -<programlisting> -$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"' -"_replicator" -</programlisting> - - <para> - As soon as this is done, both pull replications defined before, - are stopped. This is explicitly mentioned in CouchDB's log: - </para> - -<programlisting><![CDATA[ -[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.104.0>] Stopping all ongoing replications because the replicator database was deleted or changed -[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.127.0>] 127.0.0.1 - - PUT /_config/replicator/db 200 -]]> -</programlisting> - - <para> - Imagine now you add a replication document to the new replicator - database named <literal>another_replicator_db</literal>: - </para> - -<programlisting> -{ - "_id": "rep_from_X", - "source": "http://xserver.com:5984/foo", - "target": "foo_x", - "continuous": true -} -</programlisting> - - <para> - From now own you have a single replication going on in your - system: a pull replication pulling from server X. Now you change - back the replicator database to the original one - <literal>_replicator</literal>: - </para> - -<programlisting> -$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"' -"another_replicator_db" -</programlisting> - - <para> - Immediately after this operation, the replication pulling from - server X will be stopped and the replications defined in the - _replicator database (pulling from servers A and B) will be - resumed. - </para> - - <para> - Changing again the replicator database to - <literal>another_replicator_db</literal> will stop the pull - replications pulling from servers A and B, and resume the pull - replication pulling from server X. - </para> - - </section> - - <section id="couchdb-single-replication-replicatordb-replicating"> - - <title>Replicating the replicator database</title> - - <para> - Imagine you have in server C a replicator database with the two - following pull replication documents in it: - </para> - -<programlisting> -{ - "_id": "rep_from_A", - "source": "http://aserver.com:5984/foo", - "target": "foo_a", - "continuous": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297971311 -} -{ - "_id": "rep_from_B", - "source": "http://bserver.com:5984/foo", - "target": "foo_b", - "continuous": true, - "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -} -</programlisting> - - <para> - Now you would like to have the same pull replications going on - in server D, that is, you would like to have server D pull - replicating from servers A and B. You have two options: - </para> - - <itemizedlist> - - <listitem> - <para> - Explicitly add two documents to server's D replicator - database - </para> - </listitem> - - <listitem> - <para> - Replicate server's C replicator database into server's D - replicator database - </para> - </listitem> - - </itemizedlist> - - <para> - Both alternatives accomplish exactly the same goal. - </para> - - </section> - - <section id="couchdb-single-replication-replicatordb-delegations"> - - <title>Delegations</title> - - <para> - Replication documents can have a custom - <literal>user_ctx</literal> property. This property defines the - user context under which a replication runs. For the old way of - triggering replications (POSTing to - <literal>/_replicate/</literal>), this property was not needed - (it didn't exist in fact) - this is because at the moment of - triggering the replication it has information about the - authenticated user. With the replicator database, since it's a - regular database, the information about the authenticated user - is only present at the moment the replication document is - written to the database - the replicator database implementation - is like a _changes feed consumer (with - <literal>?include_docs=true</literal>) that reacts to what was - written to the replicator database - in fact this feature could - be implemented with an external script/program. This - implementation detail implies that for non admin users, a - <literal>user_ctx</literal> property, containing the user's name - and a subset of his/her roles, must be defined in the - replication document. This is ensured by the document update - validation function present in the default design document of - the replicator database. This validation function also ensure - that a non admin user can set a user name property in the - <literal>user_ctx</literal> property that doesn't match his/her - own name (same principle applies for the roles). - </para> - - <para> - For admins, the <literal>user_ctx</literal> property is - optional, and if it's missing it defaults to a user context with - name null and an empty list of roles - this mean design - documents will not be written to local targets. If writing - design documents to local targets is desired, the a user context - with the roles <literal>_admin</literal> must be set explicitly. - </para> - - <para> - Also, for admins the <literal>user_ctx</literal> property can be - used to trigger a replication on behalf of another user. This is - the user context that will be passed to local target database - document validation functions. - </para> - - <note> - <para> - The <literal>user_ctx</literal> property only has effect for - local endpoints. - </para> - </note> - - <para> - Example delegated replication document: - </para> - -<programlisting> -{ - "_id": "my_rep", - "source": "http://bserver.com:5984/foo", - "target": "bar", - "continuous": true, - "user_ctx": { - "name": "joe", - "roles": ["erlanger", "researcher"] - } -} -</programlisting> - - <para> - As stated before, for admins the user_ctx property is optional, - while for regular (non admin) users it's mandatory. When the - roles property of <literal>user_ctx</literal> is missing, it - defaults to the empty list <literal>[ ]</literal>. - </para> - - </section> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/couchdb-single-troubleshooting.xml b/share/docs/couchdb-manual-1.1/couchdb-single-troubleshooting.xml deleted file mode 100644 index 5d72456f7..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-single-troubleshooting.xml +++ /dev/null @@ -1,35 +0,0 @@ - <section id="couchdb-single-features-errormessages"> - - <title>Error Messages</title> - - <para> - The errors reported when CouchDB is unable to read a required file - have been updated so that explicit information about the files and - problem can now be identified from the error message. The errors - report file permission access either when reading or writing to - configuration and database files. - </para> - - <para> - The error is raised both through the log file and the error - message returned through the API call as a JSON error message. For - example, when setting configuration values: - </para> - -<programlisting> -shell> <userinput>curl -H 'X-Couch-Persist: true' -X PUT http://couchdb:5984/_config/couchdb/delayed_commits -d '"false"'</userinput> -{"error":"file_permission_error","reason":"/etc/couchdb/local.ini"} - </programlisting> - - <para> - Errors will always be reported using the - <literal>file_permission_error</literal> error type. - </para> - - <para> - During startup permissions errors on key files are also reported - in the log with a descriptive error message and file location so - that permissions can be fixed before restart. - </para> - - </section> diff --git a/share/docs/couchdb-manual-1.1/couchdb-views.xml b/share/docs/couchdb-manual-1.1/couchdb-views.xml deleted file mode 100644 index 2056d2995..000000000 --- a/share/docs/couchdb-manual-1.1/couchdb-views.xml +++ /dev/null @@ -1,15 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-single-views"> - - <title>Views</title> - - <para> - - </para> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-auth.xml b/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-auth.xml deleted file mode 100644 index 3c4762b7d..000000000 --- a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-auth.xml +++ /dev/null @@ -1,40 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-auth"> - - <title>CouchDB API Server Authentication Methods</title> - - <para> - The CouchDB Authentication methods provide an interface for - obtaining session and authorization data. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-api-auth-summary"><title>Authentication API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>GET</literal></entry><entry><literal>/_oauth/access_token</literal></entry><entry><link linkend="couchdb-api-auth_access-token_get"> - TBC - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_oauth/authorize</literal></entry><entry><link linkend="couchdb-api-auth_authorize_get"> - TBC - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/_oauth/authorize</literal></entry><entry><link linkend="couchdb-api-auth_authorize_post"> - TBC - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_oauth/request_token</literal></entry><entry><link linkend="couchdb-api-auth_authorize_get"> - TBC - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_session</literal></entry><entry><link linkend="couchdb-api-auth_session_get"> - Returns cookie based login user information - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/_session</literal></entry><entry><link linkend="couchdb-api-auth_session_post"> - Do cookie based user login - </link></entry></row><row><entry><literal>DELETE</literal></entry><entry><literal>/_session</literal></entry><entry><link linkend="couchdb-api-auth_session_delete"> - Logout cookie based user - </link></entry></row></tbody></tgroup></table> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-config.xml b/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-config.xml deleted file mode 100644 index d7af03370..000000000 --- a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-config.xml +++ /dev/null @@ -1,348 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-config"> - - <title>CouchDB API Server Configuration Methods</title> - - <para> - The CouchDB API Server Configuration Methods provide an interface to - query and update the various configuration values within a running - CouchDB instance. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-api-config-summary"><title>Configuration API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>GET</literal></entry><entry><literal>/_config</literal></entry><entry><link linkend="couchdb-api-config_config_get"> - Obtain a list of the entire server configuration - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_config/section</literal></entry><entry><link linkend="couchdb-api-config_config-section_get"> - Get all the configuration values for the specified section - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_config/section/key</literal></entry><entry><link linkend="couchdb-api-config_config-section-key_get"> - Get a specific section/configuration value - </link></entry></row><row><entry><literal>PUT</literal></entry><entry><literal>/_config/section/key</literal></entry><entry><link linkend="couchdb-api-config_config-section-key_put"> - Set the specified configuration value - </link></entry></row><row><entry><literal>DELETE</literal></entry><entry><literal>/_config/section/key</literal></entry><entry><link linkend="couchdb-api-config_config-section-key_delete"> - Delete the current setting - </link></entry></row></tbody></tgroup></table> - - <section id="couchdb-api-config_config_get"> - - <title><literal>GET /_config</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /_config</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /_config</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Returns a structure configuration name and value pairs, - organized by section - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Returns the entire CouchDB server configuration as a JSON - structure. The structure is organized by different configuration - sections, with individual values. - </para> - - <para> - For example, to get the configuration for a server: - </para> - -<programlisting> -GET http://couchdb:5984/_config -Accept: application/json -</programlisting> - - <para> - The response is the JSON structure: - </para> - -<programlisting> -<![CDATA[{ - "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}" - } -}]]> - </programlisting> - - </section> - - <section id="couchdb-api-config_config-section_get"> - - <title><literal>GET /_config/section</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /_config/section</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /_config/section</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - All the configuration values within a specified section - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Gets the configuration structure for a single section. For - example, to retrieve the CouchDB configuration section values: - </para> - -<programlisting> -GET http://couchdb:5984/_config/couchdb -Accept: application/json -</programlisting> - - <para> - The returned JSON contains just the configuration values for this - section: - </para> - -<programlisting> -{ - "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" -} -</programlisting> - - </section> - - <section id="couchdb-api-config_config-section-key_get"> - - <title><literal>GET /_config/section/key</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /_config/section/key</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /_config/section/key</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Value of the specified key/section - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Gets a single configuration value from within a specific - configuration section. For example, to obtain the current log - level: - </para> - -<programlisting> -GET http://couchdb:5984/_config/log/level -Accept: application/json -</programlisting> - - <para> - Returns the string of the log level: - </para> - -<programlisting> -"info" -</programlisting> - - <note> - <para> - 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. - </para> - </note> - - </section> - - <section id="couchdb-api-config_config-section-key_put"> - - <title><literal>PUT /_config/section/key</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /_config/section/key</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>PUT /_config/section/key</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - Value structure - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Previous value - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Configuration option updated successfully - </entry></row><row><entry>500</entry><entry namest="info" nameend="addinfo"> - Error setting configuration - </entry></row></tbody></tgroup></informaltable> - - <para> - 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. - </para> - - <para> - For example, to set the function used to generate UUIDs by the - <literal>GET /_uuids</literal> API call to use the - <literal>utc_random</literal> generator: - </para> - -<programlisting> -PUT http://couchdb:5984/_config/uuids/algorithm -Content-Type: application/json - -"utc_random" -</programlisting> - - <para> - The return value will be empty, with the response code indicating - the success or failure of the configuration setting. - </para> - - </section> - - <section id="couchdb-api-config_config-section-key_delete"> - - <title><literal>DELETE /_config/section/key</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API DELETE /_config/section/key</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>DELETE /_config/section/key</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Previous value - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current revision of the document for validation - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>If-Match</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Supplied revision is incorrect or missing - </entry></row></tbody></tgroup></informaltable> - - <para> - 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: - </para> - -<programlisting> -DELETE http://couchdb:5984/_config/uuids/algorithm -Content-Type: application/json -</programlisting> - - <para> - The returned value is the last configured UUID function: - </para> - -<programlisting> -"random" -</programlisting> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-db.xml b/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-db.xml deleted file mode 100644 index 16fde4f85..000000000 --- a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-db.xml +++ /dev/null @@ -1,1937 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-db"> - - <title>CouchDB API Server Database Methods</title> - - <para> - The Database methods provide an interface to an entire database - withing CouchDB. These are database, rather than document, level - requests. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db-summary"><title>Database API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>GET</literal></entry><entry><literal>/db</literal></entry><entry><link linkend="couchdb-api-db_db_get"> - Returns database information - </link></entry></row><row><entry><literal>PUT</literal></entry><entry><literal>/db</literal></entry><entry><link linkend="couchdb-api-db_db_put"> - Create a new database - </link></entry></row><row><entry><literal>DELETE</literal></entry><entry><literal>/db</literal></entry><entry><link linkend="couchdb-api-db_db_delete"> - Delete an existing database - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/_all_docs</literal></entry><entry><link linkend="couchdb-api-db_db-all-docs_get"> - Returns a built-in view of all documents in this database - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_all_docs</literal></entry><entry><link linkend="couchdb-api-db_db-all-docs_post"> - Returns certain rows from the built-in view of all documents - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_bulk_docs</literal></entry><entry><link linkend="couchdb-api-db_db-bulk-docs_post"> - Insert multiple documents in to the database in a single request - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/_changes</literal></entry><entry><link linkend="couchdb-api-db_db-changes_get"> - Returns changes for the given database - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_compact</literal></entry><entry><link linkend="couchdb-api-db_db-compact_post"> - Starts a compaction for the database - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_compact/design-doc</literal></entry><entry><link linkend="couchdb-api-db_db-compact-design-doc_post"> - Starts a compaction for all the views in the selected design - document - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_ensure_full_commit</literal></entry><entry><link linkend="couchdb-api-db_db-ensure-full-commit_post"> - Makes sure all uncommitted changes are written and synchronized - to the disk - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_missing_revs</literal></entry><entry><link linkend="couchdb-api-db_db-missing-revs_post"> - Given a list of document revisions, returns the document - revisions that do not exist in the database - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_purge</literal></entry><entry><link linkend="couchdb-api-db_db-purge_post"> - Purge some historical documents entirely from database history - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_revs_diff</literal></entry><entry><link linkend="couchdb-api-db_db-revs-diff_post"> - Given a list of document revisions, returns differences between - the given revisions and ones that are in the database - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/_revs_limit</literal></entry><entry><link linkend="couchdb-api-db_db-revs-limit_get"> - Gets the limit of historical revisions to store for a single - document in the database - </link></entry></row><row><entry><literal>PUT</literal></entry><entry><literal>/db/_revs_limit</literal></entry><entry><link linkend="couchdb-api-db_db-revs-limit_put"> - Sets the limit of historical revisions to store for a single - document in the database - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/_security</literal></entry><entry><link linkend="couchdb-api-db_db-security_get"> - Returns the special security object for the database - </link></entry></row><row><entry><literal>PUT</literal></entry><entry><literal>/db/_security</literal></entry><entry><link linkend="couchdb-api-db_db-security_put"> - Sets the special security object for the database - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_temp_view</literal></entry><entry><link linkend="couchdb-api-db_db-temp-view_post"> - Execute a given view function for all documents and return the - result - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_view_cleanup</literal></entry><entry><link linkend="couchdb-api-db_db-view-cleanup_post"> - Removes view files that are not used by any design document - </link></entry></row></tbody></tgroup></table> - - <para> - 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 - <literal>recipes</literal>, you would use the HTTP request: - </para> - -<programlisting> -GET /recipes -</programlisting> - - <para> - For clarity, the form below is used in the URL paths: - </para> - -<programlisting> -GET /db -</programlisting> - - <para> - Where <literal>db</literal> is the name of any database. - </para> - - <section id="couchdb-api-db_db_get"> - - <title><literal>GET /db</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Information about the database in JSON format - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The requested content could not be found. The returned content - will include further information, as a JSON object, if available. - </entry></row></tbody></tgroup></informaltable> - - <para> - Gets information about the specified database. For example, to - retrieve the information for the database - <literal>recipe</literal>: - </para> - -<programlisting role="httprequest"> -GET http://couchdb:5984/recipes -Accept: application/json -</programlisting> - - <para> - The JSON response contains meta information about the database. A - sample of the JSON returned for an empty database is provided - below: - </para> - -<programlisting role="httpresponse"> -{ - "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 -} - </programlisting> - - <para> - The elements of the returned structure are shown in the table - below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db-json-db-info" class="jsonstructure"><title> - CouchDB database information object - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>committed_update_seq</literal> </entry><entry> - The number of committed update. - </entry></row><row><entry ><literal>compact_running</literal> </entry><entry> - Set to true if the database compaction routine is operating on - this database. - </entry></row><row><entry ><literal>db_name</literal> </entry><entry> - The name of the database. - </entry></row><row><entry ><literal>disk_format_version</literal> </entry><entry> - The version of the physical format used for the data when it is - stored on disk. - </entry></row><row><entry ><literal>disk_size</literal> </entry><entry> - Size in bytes of the data as stored on the disk. Views indexes - are not included in the calculation. - </entry></row><row><entry ><literal>doc_count</literal> </entry><entry> - A count of the documents in the specified database. - </entry></row><row><entry ><literal>doc_del_count</literal> </entry><entry> - Number of deleted documents - </entry></row><row><entry ><literal>instance_start_time</literal> </entry><entry> - Timestamp of when the database was created, expressed in - milliseconds since the epoch. - </entry></row><row><entry ><literal>purge_seq</literal> </entry><entry> - The number of purge operations on the database. - </entry></row><row><entry ><literal>update_seq</literal> </entry><entry> - The current number of updates to the database. - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-api-db_db_put"> - - <title><literal>PUT /db</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API PUT /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>PUT /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON success statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>400</entry><entry namest="info" nameend="addinfo"> - Invalid database name - </entry></row><row><entry>412</entry><entry namest="info" nameend="addinfo"> - Database already exists - </entry></row></tbody></tgroup></informaltable> - - <para> - Creates a new database. The database name must be composed of one - or more of the following characters: - </para> - - <itemizedlist> - - <listitem> - <para> - Lowercase characters (<literal>a-z</literal>) - </para> - </listitem> - - <listitem> - <para> - Name must begin with a lowercase letter - </para> - </listitem> - - <listitem> - <para> - Digits (<literal>0-9</literal>) - </para> - </listitem> - - <listitem> - <para> - Any of the characters <literal>_</literal>, - <literal>$</literal>, <literal>(</literal>, - <literal>)</literal>, <literal>+</literal>, - <literal>-</literal>, and <literal>/</literal>. - </para> - </listitem> - - </itemizedlist> - - <para> - Trying to create a database that does not meet these requirements - will return an error quoting these restrictions. - </para> - - <para> - To create the database <literal>recipes</literal>: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes -Content-Type: application/json -</programlisting> - - <para> - The returned content contains the JSON status: - </para> - -<programlisting> -{ - "ok" : true -} -</programlisting> - - <para> - Anything should be treated as an error, and the problem should be - taken form the HTTP response code. - </para> - - </section> - - <section id="couchdb-api-db_db_delete"> - - <title><literal>DELETE /db</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API DELETE /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>DELETE /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON success statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Database has been deleted - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The requested content could not be found. The returned content - will include further information, as a JSON object, if available. - </entry></row></tbody></tgroup></informaltable> - - <para> - Deletes the specified database, and all the documents and - attachments contained within it. - </para> - - <para> - To delete the database <literal>recipes</literal> you would send - the request: - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes -Content-Type: application/json -</programlisting> - - <para> - If successful, the returned JSON will indicate success - </para> - -<programlisting> -{ - "ok" : true -} -</programlisting> - - </section> - - <section id="couchdb-api-db_db-changes_get"> - - <title><literal>GET /db/_changes</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_changes</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_changes</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the changes to the database - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>doc_ids</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the list of documents IDs to be filtered - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>json</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>none</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>feed</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Type of feed - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>normal</entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>continuous</literal></entry><entry>Continuous (non-polling) mode</entry></row><row><entry></entry><entry><literal>longpoll</literal></entry><entry>Long polling mode</entry></row><row><entry></entry><entry><literal>normal</literal></entry><entry>Normal mode</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>filter</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Filter function from a design document to get updates - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>none</entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>heartbeat</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Period after which an empty line is sent during longpoll or - continuous - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>60000</entry></row><row><entry></entry><entry><emphasis role="bold">Quantity</emphasis></entry><entry>milliseconds</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>include_docs</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the document with the result - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>limit</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Maximum number of rows rows to return - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>none</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>since</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Start the results from changes immediately after the - specified sequence number - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>0</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>timeout</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Maximum period to wait before the response is sent - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>60000</entry></row><row><entry></entry><entry><emphasis role="bold">Quantity</emphasis></entry><entry>milliseconds</entry></row></tbody></tgroup></informaltable> - - <para> - 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 <literal>feed</literal> query argument. - </para> - - <para> - <itemizedlist> - - <listitem> - <para> - <emphasis role="bold">Poll</emphasis> - </para> - - <para> - 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 - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes/_changes -Content-Type: application/json -</programlisting> - - <para> - Will get all of the changes in the database. You can request - a starting point using the <literal>since</literal> 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 - <literal>since</literal> parameter. - </para> - </listitem> - - <listitem> - <para> - <emphasis role="bold">Longpoll</emphasis> - </para> - - <para> - 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. - </para> - - <para> - Because the wait for a change can be significant you can set - a timeout before the connection is automatically closed (the - <literal>timeout</literal> argument). You can also set a - heartbeat interval (using the <literal>heartbeat</literal> - query argument), which sends a newline to keep the - connection open. - </para> - </listitem> - - <listitem> - <para> - <emphasis role="bold">Continuous</emphasis> - </para> - - <para> - 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. - </para> - - <para> - 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. - </para> - </listitem> - - </itemizedlist> - </para> - - <para> - The return structure for <literal>normal</literal> and - <literal>longpoll</literal> modes is a JSON array of changes - objects, and the last update sequence number. The structure is - described in the following table. - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db_db-json-changes" class="jsonstructure"><title> - Changes information for a database - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>last_seq</literal> </entry><entry> - Last change sequence number - </entry></row><row><entry ><literal>results</literal> <literal>[array]</literal> </entry><entry> - Changes made to a database - </entry></row><row><entry > <literal>changes</literal> <literal>[array]</literal> </entry><entry> - List of changes, field-by-field, for this document - </entry></row><row><entry > <literal>id</literal> </entry><entry> - Document ID - </entry></row><row><entry > <literal>seq</literal> </entry><entry> - Update sequence number - </entry></row></tbody></tgroup></table> - - <para> - The return format for <literal>continuous</literal> mode the - server sends a CRLF (carriage-return, linefeed) delimited line for - each change. Each line contains the - <link linkend="table-couchdb-api-db_db-json-changes">JSON - object</link>. - </para> - - <para> - You can also request the full contents of each document change - (instead of just the change notification) by using the - <literal>include_docs</literal> parameter. - </para> - - <section id="couchdb-api-db_db-changes_get-filters"> - - <title>Filtering</title> - - <para> - 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. - </para> - - <para> - You can also filter the <literal>_changes</literal> 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 - <literal>filter</literal> parameter, specifying the design - document name and filter name. For example: - </para> - -<programlisting> -GET /db/_changes?filter=design_doc/filtername -</programlisting> - - <para> - The <literal>_changes</literal> feed can be used to watch - changes to specific document ID's or the list of - <literal>_design</literal> documents in a database. If the - <literal>filters</literal> parameter is set to - <literal>_doc_ids</literal> a list of doc IDs can be passed in - the <option>doc_ids</option> parameter as a JSON array. - </para> - - <para> - For more information, see - <xref linkend="couchdb-single-changes-filters"/>. - </para> - - </section> - - </section> - - <section id="couchdb-api-db_db-compact_post"> - - <title><literal>POST /db/_compact</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_compact</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_compact</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON success statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>202</entry><entry namest="info" nameend="addinfo"> - Compaction request has been accepted - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The requested content could not be found. The returned content - will include further information, as a JSON object, if available. - </entry></row></tbody></tgroup></informaltable> - - <para> - Request compaction of the specified database. Compaction - compresses the disk database file by performing the following - operations: - </para> - - <itemizedlist> - - <listitem> - <para> - 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. - </para> - </listitem> - - <listitem> - <para> - Removes old revisions of documents from the database, up to - the per-database limit specified by the - <literal>_revs_limit</literal> database parameter. See - <xref linkend="couchdb-api-db_db_get"/> . - </para> - </listitem> - - </itemizedlist> - - <para> - 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. - </para> - - <para> - You can determine if the compaction process is operating on a - database by obtaining the database meta information, the - <literal>compact_running</literal> value of the returned database - structure will be set to true. See - <xref linkend="couchdb-api-db_db_get"/> . - </para> - - <para> - You can also obtain a list of running processes to determine - whether compaction is currently running. See - <xref linkend="couchdb-api-misc_active-tasks_get"/>. - </para> - - </section> - - <section id="couchdb-api-db_db-compact-design-doc_post"> - - <title><literal>POST /db/_compact/design-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_compact/design-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_compact/design-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON success statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">yes</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>202</entry><entry namest="info" nameend="addinfo"> - Compaction request has been accepted - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The requested content could not be found. The returned content - will include further information, as a JSON object, if available. - </entry></row></tbody></tgroup></informaltable> - - <para> - 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. - </para> - - <para> - For example, to compact the views associated with the - <literal>recipes</literal> design document: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_compact/recipes -Content-Type: application/json -</programlisting> - - <para> - CouchDB will immediately return with a status indicating that the - compaction request has been received (HTTP status code 202): - </para> - -<programlisting> -{ - "ok" : true -} - </programlisting> - - </section> - - <section id="couchdb-api-db_db-view-cleanup_post"> - - <title><literal>POST /db/_view_cleanup</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_view_cleanup</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_view_cleanup</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON success statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">yes</entry></row></tbody></tgroup></informaltable> - - <para> - Cleans up the cached view output on disk for a given view. For - example: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_view_cleanup -Content-Type: application/json -</programlisting> - - <para> - If the request is successful, a basic status message us returned: - </para> - -<programlisting> -{ - "ok" : true -} - </programlisting> - - </section> - - <section id="couchdb-api-db_db-ensure-full-commit_post"> - - <title><literal>POST /db/_ensure_full_commit</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_ensure_full_commit</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_ensure_full_commit</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON success statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Commit completed successfully - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The requested content could not be found. The returned content - will include further information, as a JSON object, if available. - </entry></row></tbody></tgroup></informaltable> - - <para> - 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 <literal>recipes</literal> you would use: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_ensure_full_commit -Content-Type: application/json -</programlisting> - - <para> - This returns a status message, containing the success message and - the timestamp for when the CouchDB instance was started: - </para> - -<programlisting> -{ - "ok" : true, - "instance_start_time" : "1288186189373361" -} -</programlisting> - - - - </section> - - <section id="couchdb-api-db_db-bulk-docs_post"> - - <title><literal>POST /db/_bulk_docs</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_bulk_docs</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_bulk_docs</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the docs and updates to be applied - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of updated documents - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document(s) have been created or updated - </entry></row></tbody></tgroup></informaltable> - - <para> - 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. - </para> - - <para> - For both inserts and updates the basic structure of the JSON is - the same: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db_db-bulk-docs-json" class="jsonstructure"><title> - Bulk Documents - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>all_or_nothing</literal> (optional) </entry><entry> - Sets the database commit mode to use all-or-nothing semantics - </entry></row><row><entry ><literal>docs</literal> <literal>[array]</literal> </entry><entry> - Bulk Documents Document - </entry></row><row><entry > <literal>_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry > <literal>_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry > <literal>_deleted</literal> (optional) </entry><entry> - Whether the document should be deleted - </entry></row></tbody></tgroup></table> - - <section id="couchdb-api-db_db-bulk-docs_post-insert"> - - <title>Inserting Documents in Bulk</title> - - <para> - 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. - </para> - - <para> - For example, the following inserts three new documents, two with - the supplied document IDs, and one which will have a document ID - generated: - </para> - -<programlisting> -{ - "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" - }, - ] -} - </programlisting> - - <para> - 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. - </para> - - <para> - The return structure from the example above contains a list of - the documents created, here with the combination and their - revision IDs: - </para> - -<programlisting> -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", - } -] - </programlisting> - - <para> - The content and structure of the returned JSON will depend on - the transaction semantics being used for the bulk update; see - <xref - linkend="couchdb-api-db_db-bulk-docs_post-commit"/> - for more information. Conflicts and validation errors when - updating documents in bulk must be handled separately; see - <xref - linkend="couchdb-api-db_db-bulk-docs_post-errors"/>. - </para> - - </section> - - <section id="couchdb-api-db_db-bulk-docs_post-update"> - - <title>Updating Documents in Bulk</title> - - <para> - 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. - </para> - - <para> - For example, you could send the following request: - </para> - -<programlisting> -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" - } - ] -} -</programlisting> - - <para> - The return structure is the JSON of the updated documents, with - the new revision and ID information: - </para> - -<programlisting> -[ - { - "id" : "FishStew", - "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1" - }, - { - "id" : "LambStew", - "rev" : "2-0786321986194c92dd3b57dfbfc741ce" - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "rev" : "2-bdd3bf3563bee516b96885a66c743f8e" - } -] -</programlisting> - - <para> - You can optionally delete documents during a bulk update by - adding the <literal>_deleted</literal> field with a value of - <literal>true</literal> to each docment ID/revision combination - within the submitted JSON structure. - </para> - - <para> - 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. - </para> - - <para> - The content and structure of the returned JSON will depend on - the transaction semantics being used for the bulk update; see - <xref - linkend="couchdb-api-db_db-bulk-docs_post-commit"/> - for more information. Conflicts and validation errors when - updating documents in bulk must be handled separately; see - <xref - linkend="couchdb-api-db_db-bulk-docs_post-errors"/>. - </para> - - </section> - - <section id="couchdb-api-db_db-bulk-docs_post-commit"> - - <title>Bulk Documents Transaction Semantics</title> - - <para> - 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: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>non-atomic</literal> - </para> - - <para> - 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. - </para> - - <para> - In this mode, the response structure will indicate whether - the document was updated by supplying the new - <literal>_rev</literal> parameter indicating a new document - revision was created. If the update failed, then you will - get an <literal>error</literal> of type - <literal>conflict</literal>. For example: - </para> - -<programlisting> -[ - { - "id" : "FishStew", - "error" : "conflict", - "reason" : "Document update conflict." - }, - { - "id" : "LambStew", - "error" : "conflict", - "reason" : "Document update conflict." - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "error" : "conflict", - "reason" : "Document update conflict." - } -] - </programlisting> - - <para> - 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. - </para> - </listitem> - - <listitem> - <para> - <literal>all-or-nothing</literal> - </para> - - <para> - 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. - </para> - - <para> - 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: - </para> - -<programlisting> -[ - { - "id" : "FishStew", - "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1" - }, - { - "id" : "LambStew", - "rev" : "2-0786321986194c92dd3b57dfbfc741ce" - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "rev" : "2-bdd3bf3563bee516b96885a66c743f8e" - } -] -</programlisting> - - <para> - 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 - <literal>conflicts=true</literal> query argument when - accessing the view. Conflicts should be handled individually - to ensure the consistency of your database. - </para> - - - - <para> - To use this mode, you must include the - <literal>all_or_nothing</literal> field (set to true) within - the main body of the JSON of the request. - </para> - </listitem> - - </itemizedlist> - - <para> - The effects of different database operations on the different - modes are summarized in the table below: - </para> - - <table id="table-couchdb-api-db_db-bulk-docs_post-commit"> - <title>Conflicts on Bulk Inserts</title> - <tgroup cols="4"> - <thead> - <row> - <entry> - Transaction Mode - </entry> - <entry> - Transaction - </entry> - <entry> - Cause - </entry> - <entry> - Resolution - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - Non-atomic - </entry> - <entry> - Insert - </entry> - <entry> - Requested document ID already exists - </entry> - <entry> - Resubmit with different document ID, or update the - existing document - </entry> - </row> - <row> - <entry> - Non-atomic - </entry> - <entry> - Update - </entry> - <entry> - Revision missing or incorrect - </entry> - <entry> - Resubmit with correct revision - </entry> - </row> - <row> - <entry> - All-or-nothing - </entry> - <entry> - Insert - </entry> - <entry> - Additional revision inserted - </entry> - <entry> - Resolve conflicted revisions - </entry> - </row> - <row> - <entry> - All-or-nothing - </entry> - <entry> - Update - </entry> - <entry> - Additional revision inserted - </entry> - <entry> - Resolve conflicted revisions - </entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - 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. - </para> - - </section> - - <section id="couchdb-api-db_db-bulk-docs_post-errors"> - - <title>Bulk Document Validation and Conflict Errors</title> - - <para> - The JSON returned by the <literal>_bulk_docs</literal> 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. - </para> - - <para> - The exact structure of the returned information is shown in - <xref - linkend="table-couchdb-api-db_db-bulk-docs-return-json"/>. - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db_db-bulk-docs-return-json" class="jsonstructure"><title> - Bulk Document Response - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>docs</literal> <literal>[array]</literal> </entry><entry> - Bulk Docs Returned Documents - </entry></row><row><entry > <literal>error</literal> </entry><entry> - Error type - </entry></row><row><entry > <literal>id</literal> </entry><entry> - Document ID - </entry></row><row><entry > <literal>reason</literal> </entry><entry> - Error string with extended reason - </entry></row></tbody></tgroup></table> - - <para> - When a document (or document revision) is not correctly comitted - to the database because of an error, you should check the - <literal>error</literal> field to determine error type and - course of action. Errors will be one of the following type: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>conflict</literal> - </para> - - <para> - 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 - <literal>all-or-nothing</literal> mode then you will need to - manually resolve the conflicted revisions of the document. - </para> - - <para> - Conflict resolution of documents added using the bulk docs - interface is identical to the resolution procedures used - when resolving conflict errors during replication. - </para> - - - </listitem> - - <listitem> - <para> - <literal>forbidden</literal> - </para> - - <para> - Entries with this error type indicate that the validation - routine applied to the document during submission has - returned an error. - </para> - - <para> - For example, if your validation routine includes the - following: - </para> - -<programlisting> throw({forbidden: 'invalid recipe ingredient'});</programlisting> - - <para> - The error returned will be: - </para> - -<programlisting> -{ - "id" : "7f7638c86173eb440b8890839ff35433", - "error" : "forbidden", - "reason" : "invalid recipe ingredient" -} - </programlisting> - - <para> - For more information, see - <xref linkend="couchdb-api-functional-validation"/>. - </para> - </listitem> - - </itemizedlist> - - </section> - - </section> - - <section id="couchdb-api-db_db-temp-view_post"> - - <title><literal>POST /db/_temp_view</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_temp_view</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_temp_view</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON with the temporary view definition - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Temporary view result set - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">yes</entry></row></tbody></tgroup></informaltable> - - <para> - Creates (and executes) a temporary view based on the view function - supplied in the JSON request. For example: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_temp_view -Content-Type: application/json - -{ - "map" : "function(doc) { if (doc.value > 9995) { emit(null, doc.value); } }" -} -</programlisting> - - <para> - The resulting JSON response is the result from the execution of - the temporary view: - </para> - -<programlisting> -{ - "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 -} -</programlisting> - - <para> - 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. - </para> - - <para> - For more information, see - <xref linkend="couchdb-api-functional-views"/>. - </para> - - </section> - - <section id="couchdb-api-db_db-purge_post"> - - <title><literal>POST /db/_purge</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_purge</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_purge</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the document IDs/revisions to be purged - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON structure with purged documents and purge sequence - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - 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. - </para> - - <para> - 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. - </para> - - <note> - <para> - Purging documents does not remove the space used by them on - disk. To reclaim disk space, you should run a database compact - (see <xref - linkend="couchdb-api-db_db-compact_post"/>, and - compact views (see - <xref - linkend="couchdb-api-db_db-compact-design-doc_post"/>). - </para> - </note> - - <para> - To perform a purge operation you must send a request including the - JSON of the document IDs that you want to purge. For example: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_purge -Content-Type: application/json - -{ - "FishStew" : [ - "17-b3eb5ac6fbaef4428d712e66483dcb79" - ] -} -</programlisting> - - <para> - The format of the request must include the document ID and one or - more revisions that must be purged. - </para> - - <para> - The response will contain the purge sequence number, and a list of - the document IDs and revisions successfully purged. - </para> - -<programlisting> -{ - "purged" : { - "FishStew" : [ - "17-b3eb5ac6fbaef4428d712e66483dcb79" - ] - }, - "purge_seq" : 11 -} -</programlisting> - - <section id="couchdb-api-db_db-purge_post-indexrebuild"> - - <title>Updating Indexes</title> - - <para> - 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. - </para> - - <para> - 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. - </para> - - <para> - 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. - </para> - - </section> - - </section> - - <section id="couchdb-api-db_db-all-docs_get"> - - <title><literal>GET /db/_all_docs</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_all_docs</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_all_docs</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON object containing document information, ordered by the - document ID - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>descending</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return the documents in descending by key order - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>endkey</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Stop returning records when the specified key is reached - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>endkey_docid</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Stop returning records when the specified document ID is - reached - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>group</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Group the results using the reduce function to a group or - single row - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>group_level</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the group level to be used - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>include_docs</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the full content of the documents in the return - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>inclusive_end</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specifies whether the specified end key should be included - in the result - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>true</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>key</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return only documents that match the specified key - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>limit</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Limit the number of the returned documents to the specified - number - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>reduce</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Use the reduction function - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>true</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>skip</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Skip this number of records before starting to return the - results - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>0</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>stale</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Allow the results from a stale view to be used - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>ok</literal></entry><entry>Allow stale views</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>startkey</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return records starting with the specified key - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>startkey_docid</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return records starting with the specified document ID - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>update_seq</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the update sequence in the generated results - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row></tbody></tgroup></informaltable> - - <para> - 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. - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db_db-all-docs" class="jsonstructure"><title> - All Database Documents - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>offset</literal> </entry><entry> - Offset where the document list started - </entry></row><row><entry ><literal>rows</literal> <literal>[array]</literal> </entry><entry> - Array of document object - </entry></row><row><entry ><literal>total_rows</literal> </entry><entry> - Number of documents in the database/view - </entry></row><row><entry ><literal>update_seq</literal> (optional) </entry><entry> - Current update sequence for the database - </entry></row></tbody></tgroup></table> - - <para> - By default the information returned contains only the document ID - and revision. For example, the request: - </para> - -<programlisting role="httprequest"> -GET http://couchdb:5984/recipes/_all_docs -Accept: application/json -</programlisting> - - <para> - Returns the following structure: - </para> - -<programlisting role="httpresponse"> -{ - "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 -} -</programlisting> - - <para> - 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. - </para> - - - - </section> - - <section id="couchdb-api-db_db-all-docs_post"> - - <title><literal>POST /db/_all_docs</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_all_docs</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_all_docs</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the document IDs you want included - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the returned view - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - The <literal>POST</literal> to <literal>_all_docs</literal> 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 - <xref - linkend="couchdb-api-dbdoc_db-doc_get"/> requests. - </para> - - <para> - The request body should contain a list of the keys to be returned - as an array to a <literal>keys</literal> object. For example: - </para> - -<programlisting role="httprequest"> -POST http://couchdb:5984/recipes/_all_docs -User-Agent: MyApp/0.1 libwww-perl/5.837 - -{ - "keys" : [ - "Zingylemontart", - "Yogurtraita" - ] -} -</programlisting> - - <para> - The return JSON is the all documents structure, but with only the - selected keys in the output: - </para> - -<programlisting role="httpresponse"> -{ - "total_rows" : 2666, - "rows" : [ - { - "value" : { - "rev" : "1-a3544d296de19e6f5b932ea77d886942" - }, - "id" : "Zingylemontart", - "key" : "Zingylemontart" - }, - { - "value" : { - "rev" : "1-91635098bfe7d40197a1b98d7ee085fc" - }, - "id" : "Yogurtraita", - "key" : "Yogurtraita" - } - ], - "offset" : 0 -} -</programlisting> - - - - </section> - - <section id="couchdb-api-db_db-missing-revs_post"> - - <title><literal>POST /db/_missing_revs</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_missing_revs</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_missing_revs</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON list of document revisions - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of missing revisions - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-db_db-revs-diff_post"> - - <title><literal>POST /db/_revs_diff</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_revs_diff</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_revs_diff</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON list of document and revisions - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON list of differences from supplied document/revision list - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-db_db-security_get"> - - <title><literal>GET /db/_security</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_security</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_security</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the security object - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Gets the current secrity object from the specified database. The - security object consists of two compulsory elements, - <literal>admins</literal> and <literal>readers</literal>, 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. - </para> - - <para> - To get the existing security object you would send the following - request: - </para> - -<programlisting> -{ - "admins" : { - "roles" : [], - "names" : [ - "mc", - "slp" - ] - }, - "readers" : { - "roles" : [], - "names" : [ - "tim", - "brian" - ] - } -} -</programlisting> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-db-json-security" class="jsonstructure"><title> - Security Object - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>admins</literal> </entry><entry> - Roles/Users with admin privileges - </entry></row><row><entry > <literal>roles</literal> <literal>[array]</literal> </entry><entry> - List of roles with parent privilege - </entry></row><row><entry > <literal>users</literal> <literal>[array]</literal> </entry><entry> - List of users with parent privilege - </entry></row><row><entry ><literal>readers</literal> </entry><entry> - Roles/Users with reader privileges - </entry></row><row><entry > <literal>roles</literal> <literal>[array]</literal> </entry><entry> - List of roles with parent privilege - </entry></row><row><entry > <literal>users</literal> <literal>[array]</literal> </entry><entry> - List of users with parent privilege - </entry></row></tbody></tgroup></table> - - <note> - <para> - If the security object for a database has never beent set, then - the value returned will be empty. - </para> - </note> - - </section> - - <section id="couchdb-api-db_db-security_put"> - - <title><literal>PUT /db/_security</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/_security</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>PUT /db/_security</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON specifying the admin and user security for the database - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON status message - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Sets the security object for the given database.For example, to - set the security object for the <literal>recipes</literal> - database: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/_security -Content-Type: application/json - -{ - "admins" : { - "roles" : [], - "names" : [ - "mc", - "slp" - ] - }, - "readers" : { - "roles" : [], - "names" : [ - "tim", - "brian" - ] - } -}</programlisting> - - <para> - If the setting was successful, a JSON status object will be - returned: - </para> - -<programlisting> -{ - "ok" : true -} -</programlisting> - - </section> - - <section id="couchdb-api-db_db-revs-limit_get"> - - <title><literal>GET /db/_revs_limit</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_revs_limit</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_revs_limit</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - The current revision limit setting - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Gets the current <literal>revs_limit</literal> (revision limit) - setting. - </para> - - <para> - For example to get the current limit: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_revs_limit -Content-Type: application/json -</programlisting> - - <para> - The returned information is the current setting as a numerical - scalar: - </para> - -<programlisting> -1000 -</programlisting> - - </section> - - <section id="couchdb-api-db_db-revs-limit_put"> - - <title><literal>PUT /db/_revs_limit</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/_revs_limit</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>PUT /db/_revs_limit</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - A scalar integer of the revision limit setting - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Confirmation of setting of the revision limit - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - 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 <literal>PUT</literal> with - a scalar integer of the limit that you want to set as the request - body. - </para> - - <para> - For example to set the revs limit to 100 for the - <literal>recipes</literal> database: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/_revs_limit -Content-Type: application/json - -100 -</programlisting> - - <para> - If the setting was successful, a JSON status object will be - returned: - </para> - -<programlisting> -{ - "ok" : true -} -</programlisting> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-dbdoc.xml b/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-dbdoc.xml deleted file mode 100644 index a924c2d71..000000000 --- a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-dbdoc.xml +++ /dev/null @@ -1,1091 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-dbdoc"> - - <title>CouchDB API Server Document Methods</title> - - <para> - The CouchDB API Server Document methods detail how to create, read, - update and delete documents within a database. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-dbdoc-summary"><title>Document API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>POST</literal></entry><entry><literal>/db</literal></entry><entry><link linkend="couchdb-api-dbdoc_db_post"> - Create a new document - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/doc</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc_get"> - Returns the latest revision of the document - </link></entry></row><row><entry><literal>HEAD</literal></entry><entry><literal>/db/doc</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc_head"> - Returns bare information in the HTTP Headers for the document - </link></entry></row><row><entry><literal>PUT</literal></entry><entry><literal>/db/doc</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc_put"> - Inserts a new document, or new version of an existing document - </link></entry></row><row><entry><literal>DELETE</literal></entry><entry><literal>/db/doc</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc_delete"> - Deletes the document - </link></entry></row><row><entry><literal>COPY</literal></entry><entry><literal>/db/doc</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc_copy"> - Copies the document - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/doc/attachment</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc-attachment_get"> - Gets the attachment of a document - </link></entry></row><row><entry><literal>PUT</literal></entry><entry><literal>/db/doc/attachment</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc-attachment_put"> - Adds an attachment of a document - </link></entry></row><row><entry><literal>DELETE</literal></entry><entry><literal>/db/doc/attachment</literal></entry><entry><link linkend="couchdb-api-dbdoc_db-doc-attachment_delete"> - Deletes an attachment of a document - </link></entry></row></tbody></tgroup></table> - - <section id="couchdb-api-dbdoc_db_post"> - - <title><literal>POST /db</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the new document - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON with the committed document information - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>batch</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Allow document store request to be batched with others - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>ok</literal></entry><entry>Enable</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document has been created successfully - </entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Conflict - a document with the specified document ID already - exists - </entry></row></tbody></tgroup></informaltable> - - <para> - Create a new document in the specified database, using the - supplied JSON document structure. If the JSON structure includes - the <literal>_id</literal> field, then the document will be - created with the specified document ID. If the - <literal>_id</literal> field is not specified, a new unique ID - will be generated. - </para> - - <para> - For example, you can generate a new document with a generated UUID - using the following request: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/ -Content-Type: application/json - -{ - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" -} -</programlisting> - - <para> - The return JSON will specify the automatically enerated ID and - revision information: - </para> - -<programlisting> -{ - "id" : "64575eef70ab90a2b8d55fc09e00440d", - "ok" : true, - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -} -</programlisting> - - <section id="couchdb-api-dbdoc_db_post-docid"> - - <title>Specifying the Document ID</title> - - <para> - The document ID can be specified by including the - <literal>_id</literal> field in the JSON of the submitted - record. The following request will create the same document with - the ID <literal>FishStew</literal>: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/ -Content-Type: application/json - -{ - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" -} -</programlisting> - - <para> - The structure of the submitted document is as shown in the table - below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-json-document" class="jsonstructure"><title> - CouchDB Document - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry ><literal>_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row></tbody></tgroup></table> - - <para> - In either case, the returned JSON will specify the document ID, - revision ID, and status message: - </para> - -<programlisting> -{ - "id" : "FishStew", - "ok" : true, - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -} - </programlisting> - - </section> - - <section id="couchdb-api-dbdoc_db_batchmode"> - - <title>Batch Mode Writes</title> - - <para> - You can write documents to the database at a higher rate by - using the batch option. This collects document writes together - in memory (on a user-by-user basis) before they are committed to - disk. This increases the risk of the documents not being stored - in the event of a failure, since the documents are not written - to disk immediately. - </para> - - <para> - To use the batched mode, append the <literal>batch=ok</literal> - query argument to the URL of the <literal>PUT</literal> or - <literal>POST</literal> request. The CouchDB server will respond - with a 202 HTTP response code immediately. - </para> - - </section> - - <section id="couchdb-api-dbdoc_db-doc-attachments"> - - <title>Including Attachments</title> - - <para> - You can include one or more attachments with a given document by - incorporating the attachment information within the JSON of the - document. This provides a simpler alternative to loading - documents with attachments than making a separate call (see - <xref - linkend="couchdb-api-dbdoc_db-doc-attachment_put"/>). - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-dbdoc-documentattachments" class="jsonstructure"><title> - Document with Attachments - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry ><literal>_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry ><literal>_attachments</literal> (optional) </entry><entry> - Document Attachment - </entry></row><row><entry > <literal>filename</literal> </entry><entry> - Attachment information - </entry></row><row><entry > <literal>content_type</literal> </entry><entry> - MIME Content type string - </entry></row><row><entry > <literal>data</literal> </entry><entry> - File attachment content, Base64 encoded - </entry></row></tbody></tgroup></table> - - <para> - The <literal>filename</literal> will be the attachment name. For - example, when sending the JSON structure below: - </para> - -<programlisting> -{ - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" - "_attachments" : { - "styling.css" : { - "content-type" : "text/css", - "data" : "cCB7IGZvbnQtc2l6ZTogMTJwdDsgfQo=", - }, - }, -} - </programlisting> - - <para> - The attachment <literal>styling.css</literal> can be accessed - using <literal>/recipes/FishStew/styling.css</literal>. For more - information on attachments, see - <xref - linkend="couchdb-api-dbdoc_db-doc-attachment_get"/>. - </para> - - <para> - The document data embedded in to the structure must be encoded - using base64. - </para> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_get"> - - <title><literal>GET /db/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Returns the JSON for the document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>conflicts</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Returns the conflict tree for the document. - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>true</literal></entry><entry>Includes the revisions</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the revision to return - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>true</literal></entry><entry>Includes the revisions</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>revs</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of the revisions for the document - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>revs_info</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of detailed revision information for the - document - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>true</literal></entry><entry>Includes the revisions</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document created - </entry></row><row><entry>400</entry><entry namest="info" nameend="addinfo"> - The format of the request or revision was invalid - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The specified document or revision cannot be found, or has been - deleted - </entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Conflict - a document with the specified document ID already - exists - </entry></row></tbody></tgroup></informaltable> - - <para> - Returns the specified <literal>doc</literal> from the specified - <literal>db</literal>. For example, to retrieve the document with - the id <literal>FishStew</literal> you would send the following - request: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/FishStew -Content-Type: application/json -Accept: application/json -</programlisting> - - <para> - The returned JSON is the JSON of the document, including the - document ID and revision number: - </para> - -<programlisting> -{ - "_id" : "FishStew", - "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c", - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "title" : "Irish Fish Stew" -} - </programlisting> - - <para> - Unless you request a specific revision, the latest revision of the - document will always be returned. - </para> - - <section id="couchdb-api-dbdoc_db-doc_get-attachments"> - - <title>Attachments</title> - - <para> - If the document includes attachments, then the returned - structure will contain a summary of the attachments associatd - with the document, but not the attachment data itself. - </para> - - <para> - The JSON for the returned document will include the - <literal>_attachments</literal> field, with one or more - attachment definitions. For example: - </para> - -<programlisting> -{ - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" - "_attachments" : { - "styling.css" : { - "stub" : true, - "content-type" : "text/css", - "length" : 783426, - }, - }, -} -</programlisting> - - <para> - The format of the returned JSON is shown in the table below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-dbdoc-returneddocumentattachments" class="jsonstructure"><title> - Returned Document with Attachments - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry ><literal>_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry ><literal>_attachments</literal> (optional) </entry><entry> - Document Attachment - </entry></row><row><entry > <literal>filename</literal> </entry><entry> - Attachment - </entry></row><row><entry > <literal>content_type</literal> </entry><entry> - MIME Content type string - </entry></row><row><entry > <literal>length</literal> </entry><entry> - Length (bytes) of the attachment data - </entry></row><row><entry > <literal>revpos</literal> </entry><entry> - Revision where this attachment exists - </entry></row><row><entry > <literal>stub</literal> </entry><entry> - Indicates whether the attachment is a stub - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_get-revs"> - - <title>Getting a List of Revisions</title> - - <para> - You can obtain a list of the revisions for a given document by - adding the <literal>revs=true</literal> parameter to the request - URL. For example: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/FishStew?revs=true -Accept: application/json -</programlisting> - - <para> - The returned JSON structure includes the original document, - including a <literal>_revisions</literal> structure that - includes the revision information: - </para> - -<programlisting> -{ - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "_id" : "FishStew", - "title" : "Irish Fish Stew", - "_revisions" : { - "ids" : [ - "a1a9b39ee3cc39181b796a69cb48521c", - "7c4740b4dcf26683e941d6641c00c39d", - "9c65296036141e575d32ba9c034dd3ee" - ], - "start" : 3 - }, - "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" -} -</programlisting> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-dbdoc-document_with_revs" class="jsonstructure"><title> - Returned CouchDB Document with Revision Info - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry ><literal>_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry ><literal>_revisions</literal> </entry><entry> - CouchDB Document Revisions - </entry></row><row><entry > <literal>ids</literal> <literal>[array]</literal> </entry><entry> - Array of valid revision IDs, in reverse order (latest first) - </entry></row><row><entry > <literal>start</literal> </entry><entry> - Prefix number for the latest revision - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_get-revsextended"> - - <title>Obtaining an Extended Revision History</title> - - <para> - You can get additional information about the revisions for a - given document by supplying the <literal>revs_info</literal> - argument to the query: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/FishStew?revs_info=true -Accept: application/json -</programlisting> - - <para> - This returns extended revision information, including the - availability and status of each revision: - </para> - -<programlisting> -{ - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "_id" : "FishStew", - "_revs_info" : [ - { - "status" : "available", - "rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" - }, - { - "status" : "available", - "rev" : "2-7c4740b4dcf26683e941d6641c00c39d" - }, - { - "status" : "available", - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" - } - ], - "title" : "Irish Fish Stew", - "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" -} -</programlisting> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-dbdoc-document_with_revs_info" class="jsonstructure"><title> - Returned CouchDB Document with Detailed Revision Info - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry ><literal>_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry ><literal>_revs_info</literal> <literal>[array]</literal> </entry><entry> - CouchDB Document Extended Revision Info - </entry></row><row><entry > <literal>rev</literal> </entry><entry> - Full revision string - </entry></row><row><entry > <literal>status</literal> </entry><entry> - Status of the revision - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_get-specrev"> - - <title>Obtaining a Specific Revision</title> - - <para> - To get a specific revision, use the <literal>rev</literal> - argument to the request, and specify the full revision number: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d -Accept: application/json -</programlisting> - - <para> - The specified revision of the document will be returned, - including a <literal>_rev</literal> field specifying the - revision that was requested: - </para> - -<programlisting> -{ - "_id" : "FishStew", - "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d", - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "title" : "Fish Stew" -} -</programlisting> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_head"> - - <title><literal>HEAD /db/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API HEAD /db/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>HEAD /db/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the revision to return - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>revs</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of the revisions for the document - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>revs_info</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of detailed revision information for the - document - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The specified document or revision cannot be found, or has been - deleted - </entry></row></tbody></tgroup></informaltable> - - <para> - Returns the HTTP Headers containing a minimal amount of - information about the specified document. The method supports the - same query arguments as the <literal>GET</literal> method, but - only the header information (including document size, and the - revision as an ETag), is returned. For example, a simple - <literal>HEAD</literal> request: - </para> - -<programlisting> -HEAD http://couchdb:5984/recipes/FishStew -Content-Type: application/json - </programlisting> - - <para> - Returns the following HTTP Headers: - </para> - -<programlisting> -HTTP/1.1 200 OK -Server: CouchDB/1.0.1 (Erlang OTP/R13B) -Etag: "7-a19a1a5ecd946dad70e85233ba039ab2" -Date: Fri, 05 Nov 2010 14:54:43 GMT -Content-Type: text/plain;charset=utf-8 -Content-Length: 136 -Cache-Control: must-revalidate -</programlisting> - - <para> - The <literal>Etag</literal> header shows the current revision for - the requested document, and the <literal>Content-Length</literal> - specifies the length of the data, if the document were requested - in full. - </para> - - <para> - Adding any of the query arguments (as supported by - <link linkend="couchdb-api-dbdoc_db-doc_get"><literal>GET</literal></link> - method), then the resulting HTTP Headers will correspond to what - would be returned. Note that the current revision is not returned - when the <literal>refs_info</literal> argument is used. For - example: - </para> - -<programlisting> -HTTP/1.1 200 OK -Server: CouchDB/1.0.1 (Erlang OTP/R13B) -Date: Fri, 05 Nov 2010 14:57:16 GMT -Content-Type: text/plain;charset=utf-8 -Content-Length: 609 -Cache-Control: must-revalidate -</programlisting> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_put"> - - <title><literal>PUT /db/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>PUT /db/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the new document, or updated version of the existed - document - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the document ID and revision - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>batch</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Allow document store request to be batched with others - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>ok</literal></entry><entry>Enable</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>If-Match</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document has been created successfully - </entry></row><row><entry>202</entry><entry namest="info" nameend="addinfo"> - Document accepted for writing (batch mode) - </entry></row></tbody></tgroup></informaltable> - - <para> - The <literal>PUT</literal> method creates a new named document, or - creates a new revision of the existing document. Unlike the - <link linkend="couchdb-api-dbdoc_db_post"><literal>POST</literal></link> - method, you must specify the document ID in the request URL. - </para> - - <para> - For example, to create the docment <literal>FishStew</literal>, - you would send the following request: - </para> - -<programlisting>PUT http://couchdb:5984/recipes/FishStew -Content-Type: application/json - -{ - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" -} -</programlisting> - - <para> - The return type is JSON of the status, document ID,and revision - number: - </para> - -<programlisting> -{ - "id" : "FishStew", - "ok" : true, - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -} -</programlisting> - - <section id="couchdb-api-dbdoc_db-doc_put-update"> - - <title>Updating an Existing Document</title> - - <para> - To update an existing document you must specify the current - revision number within the <literal>_rev</literal> parameter. - For example: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/FishStew -Content-Type: application/json - -{ - "_rev" : "1-9c65296036141e575d32ba9c034dd3ee", - "servings" : 4, - "subtitle" : "Delicious with fresh salad", - "title" : "Fish Stew" -} -</programlisting> - - <para> - Alternatively, you can supply the current revision number in the - <literal>If-Match</literal> HTTP header of the request. For - example: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/FishStew -If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea -Content-Type: application/json - -{ - "servings" : 4, - "subtitle" : "Delicious with fresh salad", - "title" : "Fish Stew" -} -</programlisting> - - <para> - The JSON returned will include the updated revision number: - </para> - -<programlisting> -{ - "id" : "FishStew99", - "ok" : true, - "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea" -} -</programlisting> - - <para> - For information on batched writes, which can provide improved - performance, see - <xref linkend="couchdb-api-dbdoc_db_batchmode"/>. - </para> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_delete"> - - <title><literal>DELETE /db/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API DELETE /db/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>DELETE /db/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the deleted revision - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current revision of the document for validation - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>If-Match</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Revision is missing, invalid or not the latest - </entry></row></tbody></tgroup></informaltable> - - <para> - Deletes the specified document from the database. You must supply - the current (latest) revision, either by using the - <literal>rev</literal> parameter to specify the revision: - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c -Content-Type: application/json -</programlisting> - - <para> - Alternatively, you can use ETags with the - <literal>If-Match</literal> field: - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes/FishStew -If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c -Content-Type: application/json - </programlisting> - - <para> - The returned JSON contains the document ID, revision and status: - </para> - -<programlisting> -{ - "id" : "FishStew", - "ok" : true, - "rev" : "4-2719fd41187c60762ff584761b714cfb" -} -</programlisting> - - <note> - <para> - Note that deletion of a record increments the revision number. - The use of a revision for deletion of the record allows - replication of the database to correctly track the deletion in - synchronized copies. - </para> - </note> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_copy"> - - <title><literal>COPY /db/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API COPY /db/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>COPY /db/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the new document and revision - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Revision to copy from - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>Destination</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Destination document (and optional revision)</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document has been copied and created successfully - </entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Conflict (target document already exists) - </entry></row></tbody></tgroup></informaltable> - - <para> - The <literal>COPY</literal> command (which is non-standard HTTP) - copies an existing document to a new or existing document. - </para> - - <para> - The source document is specified on the request line, with the - <literal>Destination</literal> HTTP Header of the request - specifying the target document. - </para> - - <section id="couchdb-api-dbdoc_db-doc_copy-simple"> - - <title>Copying a Document</title> - - <para> - You can copy the latest version of a document to a new document - by specifying the current document and target document: - </para> - -<programlisting> -COPY http://couchdb:5984/recipes/FishStew -Content-Type: application/json -Destination: IrishFishStew -</programlisting> - - <para> - The above request copies the document - <literal>FishStew</literal> to the new document - <literal>IrishFishStew</literal>. The response is the ID and - revision of the new document. - </para> - -<programlisting> -{ - "id" : "IrishFishStew", - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -} -</programlisting> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_copy-specrev"> - - <title>Copying from a Specific Revision</title> - - <para> - To copy <emphasis>from</emphasis> a specific version, use the - <literal>rev</literal> argument to the query string: - </para> - -<programlisting> -COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082 -Content-Type: application/json -Destination: IrishFishStew -</programlisting> - - <para> - The new document will be created using the information in the - specified revision of the source document. - </para> - - </section> - - <section id="couchdb-api-dbdoc_db-doc_copy-existing"> - - <title>Copying to an Existing Document</title> - - <para> - To copy to an existing document, you must specify the current - revision string for the target document, using the - <literal>rev</literal> parameter to the - <literal>Destination</literal> HTTP Header string. For example: - </para> - -<programlisting> -COPY http://couchdb:5984/recipes/FishStew -Content-Type: application/json -Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee -</programlisting> - - <para> - The return value will be the new revision of the copied - document: - </para> - -<programlisting> -{ - "id" : "IrishFishStew", - "rev" : "2-55b6a1b251902a2c249b667dab1c6692" -} -</programlisting> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc-attachment_get"> - - <title><literal>GET /db/doc/attachment</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/doc/attachment</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/doc/attachment</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Returns the document data - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Returns the file attachment <literal>attachment</literal> - associated with the document <literal>doc</literal>. The raw data - of the associated attachment is returned (just as if you were - accessing a static file. The returned HTTP - <literal>Content-type</literal> will be the same as the content - type set when the document attachment was submitted into the - database. - </para> - - </section> - - <section id="couchdb-api-dbdoc_db-doc-attachment_put"> - - <title><literal>PUT /db/doc/attachment</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/doc/attachment</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>PUT /db/doc/attachment</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - Raw document data - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON document status - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current document revision - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>Content-Length</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Length (bytes) of the attachment being uploaded</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>Content-Type</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>MIME type for the uploaded attachment</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>If-Match</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Attachment has been accepted - </entry></row></tbody></tgroup></informaltable> - - <para> - Upload the supplied content as an attachment to the specified - document (<literal>doc</literal>). The - <literal>attachment</literal> name provided must be a URL encoded - string. You must also supply either the <literal>rev</literal> - query argument or the <literal>If-Match</literal> HTTP header for - validation, and the HTTP headers (to set the attacment content - type). The content type is used when the attachment is requested - as the corresponding content-type in the returned document header. - </para> - - <para> - For example, you could upload a simple text document using the - following request: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca -Content-Length: 10 -Content-Type: text/plain - -Roast it - -</programlisting> - - <para> - Or by using the <literal>If-Match</literal> HTTP header: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/FishStew/basic -If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca -Content-Length: 10 -Content-Type: text/plain - -Roast it - -</programlisting> - - <para> - The returned JSON contains the new document information: - </para> - -<programlisting> -{ - "id" : "FishStew", - "ok" : true, - "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74" -} -</programlisting> - - <note> - <para> - Uploading an attachment updates the corresponding document - revision. Revisions are tracked for the parent document, not - individual attachments. - </para> - </note> - - <section id="couchdb-api-dbdoc_db-doc-attachment_put-existing"> - - <title>Updating an Existing Attachment</title> - - <para> - Uploading an attachment using an existing attachment name will - update the corresponding stored content of the database. Since - you must supply the revision information to add an attachment to - a document, this serves as validation to update the existing - attachment. - </para> - - </section> - - </section> - - <section id="couchdb-api-dbdoc_db-doc-attachment_delete"> - - <title><literal>DELETE /db/doc/attachment</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API DELETE /db/doc/attachment</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>DELETE /db/doc/attachment</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON status - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Revision of the document to be deleted - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>If-Match</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Attachment deleted successfully - </entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Supplied revision is incorrect or missing - </entry></row></tbody></tgroup></informaltable> - - <para> - Deletes the attachment <literal>attachment</literal> to the - specified <literal>doc</literal>. You must supply the - <literal>rev</literal> argument with the current revision to - delete the attachment. - </para> - - <para> - For example to delete the attachment <literal>basic</literal> from - the recipe <literal>FishStew</literal>: - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74 -Content-Type: application/json - - </programlisting> - - <para> - The returned JSON contains the updated revision information: - </para> - -<programlisting> -{ - "id" : "FishStew", - "ok" : true, - "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e" -} -</programlisting> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-design.xml b/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-design.xml deleted file mode 100644 index acf08eb7c..000000000 --- a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-design.xml +++ /dev/null @@ -1,1543 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-design"> - - <title>CouchDB API Server Design Document Methods</title> - - <para> - In CouchDB, design documents provide the main interface for building - a CouchDB application. The design document defines the views used to - extract information from CouchDB through one or more views. Design - documents are created within your CouchDB instance in the same way - as you create database documents, but the content and definition of - the documents is different. Design Documents are named using an ID - defined with the design document URL path, and this URL can then be - used to access the database contents. - </para> - - <para> - Views and lists operate together to provide automated (and - formatted) output from your database. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-design-summary"><title>Design Document API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>GET</literal></entry><entry><literal>/db/_design/design-doc</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc_get"> - Returns the latest revision of the design document - </link></entry></row><row><entry><literal>PUT</literal></entry><entry><literal>/db/_design/design-doc</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc_put"> - Creates or updates a design document - </link></entry></row><row><entry><literal>DELETE</literal></entry><entry><literal>/db/_design/design-doc</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc_delete"> - Deletes the design document - </link></entry></row><row><entry><literal>COPY</literal></entry><entry><literal>/db/_design/design-doc</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc_copy"> - Copies the design document - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/_design/design-doc/_info</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-info_get"> - Returns information about the design document - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-list-listname-otherdesigndoc-viewname_get"> - Invokes the list handler to translate the given view results - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-list-listname-otherdesigndoc-viewname_post"> - Invokes the list handler to translate the given view results for - certain documents - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/_design/design-doc/_list/list-name/view-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-list-listname-viewname_get"> - Invokes the list handler to translate the given view results - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_design/design-doc/_list/list-name/view-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-list-listname-viewname_post"> - Invokes the list handler to translate the given view results for - certain documents - </link></entry></row><row><entry><literal>ALL</literal></entry><entry><literal>/db/_design/design-doc/_rewrite/rewrite-name/anything</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-rewrite-rewritename-anything_all"> - Invokes the URL rewrite handler and processes the request after - rewriting - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/_design/design-doc/_show/show-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-show-showname_get"> - Invokes the show handler without a document - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/_design/design-doc/_show/show-name/doc</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-show-showname-doc_get"> - Invokes the show handler for the given document - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_design/design-doc/_update/update-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-update-updatename_post"> - Invokes the update handler without a document ID - </link></entry></row><row><entry><literal>PUT</literal></entry><entry><literal>/db/_design/design-doc/_update/update-name/doc</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-update-updatename-doc_put"> - Invokes the update handler with a specific document ID - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/_design/design-doc/_view/view-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-view-viewname_get"> - Returns results of the view - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/db/_design/design-doc/_view/view-name</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-view-viewname_post"> - Returns certain rows from the view - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/db/_design/design-doc/attachment</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-attachment_get"> - Gets an attachment of the design document - </link></entry></row><row><entry><literal>PUT</literal></entry><entry><literal>/db/_design/design-doc/attachment</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-attachment_put"> - Inserts an attachment to the design document - </link></entry></row><row><entry><literal>DELETE</literal></entry><entry><literal>/db/_design/design-doc/attachment</literal></entry><entry><link linkend="couchdb-api-design_db-design-designdoc-attachment_delete"> - Deletes an attachment from the design document - </link></entry></row></tbody></tgroup></table> - - <section id="couchdb-api-design_db-design-designdoc_get"> - - <title><literal>GET /db/_design/design-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_design/design-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the existing design document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the revision to return - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>revs</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of the revisions for the document - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>true</literal></entry><entry>Includes the revisions</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>revs_info</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of detailed revision information for the - document - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>true</literal></entry><entry>Includes the revisions</entry></row></tbody></tgroup></informaltable> - - <para> - Returns the specified design document, - <literal>design-doc</literal> from the specified - <literal>db</literal>. For example, to retrieve the design - document <literal>recipes</literal> you would send the following - request: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_design/recipes -Content-Type: application/json -</programlisting> - - <para> - The returned string will be the JSON of the design document: - </para> - -<programlisting> -{ - "_id" : "_design/recipes", - "_rev" : "5-39f56a392b86bbee57e2138921346406" - "language" : "javascript", - "views" : { - "by_recipe" : { - "map" : "function(doc) { if (doc.title != null) emit(doc.title, doc) }" - }, - }, -} -</programlisting> - - <para> - A list of the revisions can be obtained by using the - <literal>revs</literal> query argument, or an extended list of - revisions using the <literal>revs_info</literal> query argument. - This operates in the same way as for other documents. Fur further - examples, see - <xref - linkend="couchdb-api-dbdoc_db-doc_get"/>. - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_put"> - - <title><literal>PUT /db/_design/design-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/_design/design-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>PUT /db/_design/design-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the design document - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON status - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Upload the specified design document, - <literal>design-doc</literal>, to the specified database. The - design document should follow the definition of a design document, - as summarised in the following table. - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-json-designdoc" class="jsonstructure"><title> - Design Document - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>_id</literal> </entry><entry> - Design Document ID - </entry></row><row><entry ><literal>_rev</literal> </entry><entry> - Design Document Revision - </entry></row><row><entry ><literal>views</literal> </entry><entry> - View - </entry></row><row><entry > <literal>viewname</literal> </entry><entry> - View Definition - </entry></row><row><entry > <literal>map</literal> </entry><entry> - Map Function for View - </entry></row><row><entry > <literal>reduce</literal> (optional) </entry><entry> - Reduce Function for View - </entry></row></tbody></tgroup></table> - - <para> - For more information on writing views, see - <xref - linkend="couchdb-api-functional-views"/>. - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_delete"> - - <title><literal>DELETE /db/_design/design-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API DELETE /db/_design/design-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>DELETE /db/_design/design-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of deleted design document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current revision of the document for validation - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>If-Match</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Supplied revision is incorrect or missing - </entry></row></tbody></tgroup></informaltable> - - <para> - Delete an existing design document. Deleting a design document - also deletes all of the associated view indexes, and recovers the - corresponding space on disk for the indexes in question. - </para> - - <para> - To delete, you must specify the current revision of the design - document using the <literal>rev</literal> query argument. - </para> - - <para> - For example: - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8 -Content-Type: application/json -</programlisting> - - <para> - The response contains the delete document ID and revision: - </para> - -<programlisting> -{ - "id" : "recipe/_design/recipes" - "ok" : true, - "rev" : "3-7a05370bff53186cb5d403f861aca154", -} -</programlisting> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_copy"> - - <title><literal>COPY /db/_design/design-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API COPY /db/_design/design-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>COPY /db/_design/design-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the copied document and revision - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Revision to copy from - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>Destination</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Destination document (and optional revision)</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry></entry><entry></entry><entry></entry></row></tbody></tgroup></informaltable> - - <para> - The <literal>COPY</literal> command (non-standard HTTP) copies an - existing design document to a new or existing document. - </para> - - <para> - The source design document is specified on the request line, with - the <literal>Destination</literal> HTTP Header of the request - specifying the target document. - </para> - - <section id="couchdb-api-design_db-design-designdoc_copy-simple"> - - <title>Copying a Design Document</title> - - <para> - To copy the latest version of a design document to a new - document you specify the base document and target document: - </para> - -<programlisting> -COPY http://couchdb:5984/recipes/_design/recipes -Content-Type: application/json -Destination: /recipes/_design/recipelist -</programlisting> - - <para> - The above request copies the design document - <literal>recipes</literal> to the new design document - <literal>recipelist</literal>. The response is the ID and - revision of the new document. - </para> - -<programlisting> -{ - "id" : "recipes/_design/recipelist" - "rev" : "1-9c65296036141e575d32ba9c034dd3ee", -} -</programlisting> - - <note> - <para> - Copying a design document does automatically reconstruct the - view indexes. These will be recreated, as with other views, - the first time the new view is accessed. - </para> - </note> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_copy-specrev"> - - <title>Copying from a Specific Revision</title> - - <para> - To copy <emphasis>from</emphasis> a specific version, use the - <literal>rev</literal> argument to the query string: - </para> - -<programlisting> -COPY http://couchdb:5984/recipes/_design/recipes?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5 -Content-Type: application/json -Destination: recipes/_design/recipelist -</programlisting> - - <para> - The new design document will be created using the specified - revision of the source document. - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc_copy-existing"> - - <title>Copying to an Existing Design Document</title> - - <para> - To copy to an existing document, you must specify the current - revision string for the target document, using the - <literal>rev</literal> parameter to the - <literal>Destination</literal> HTTP Header string. For example: - </para> - -<programlisting> -COPY http://couchdb:5984/recipes/_design/recipes -Content-Type: application/json -Destination: recipes/_design/recipelist?rev=1-9c65296036141e575d32ba9c034dd3ee -</programlisting> - - <para> - The return value will be the new revision of the copied - document: - </para> - -<programlisting> -{ - "id" : "recipes/_design/recipes" - "rev" : "2-55b6a1b251902a2c249b667dab1c6692", -} -</programlisting> - - </section> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-attachment_get"> - - <title><literal>GET /db/_design/design-doc/attachment</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/attachment</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_design/design-doc/attachment</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Document content - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Returns the file attachment <literal>attachment</literal> - associated with the design document - <literal>/_design_/design-doc</literal>. The raw data of the - associated attachment is returned (just as if you were accessing a - static file. The returned HTTP <literal>Content-type</literal> - will be the same as the content type set when the document - attachment was submitted into the database. - </para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-attachment_put"> - - <title><literal>PUT /db/_design/design-doc/attachment</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/_design/design-doc/attachment</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>PUT /db/_design/design-doc/attachment</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the design document - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON status statement - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current revision of the document for validation - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>If-Match</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry></entry><entry></entry></row></tbody></tgroup></informaltable> - - <para> - Upload the supplied content as an attachment to the specified - design document (<literal>/_design/design-doc</literal>). The - <literal>attachment</literal> name provided must be a URL encoded - string. You must also supply either the <literal>rev</literal> - query argument or the <literal>If-Match</literal> HTTP header for - validation, and the HTTP headers (to set the attacment content - type). The content type is used when the attachment is requested - as the corresponding content-type in the returned document header. - </para> - - <para> - For example, you could upload a simple text document using the - following request: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/_design/recipes/view.css?rev=7-f7114d4d81124b223283f3e89eee043e -Content-Length: 39 -Content-Type: text/plain - -div.recipetitle { -font-weight: bold; -} - -</programlisting> - - <para> - Or by using the <literal>If-Match</literal> HTTP header: - </para> - -<programlisting> -PUT http://couchdb:5984/recipes/FishStew/basic -If-Match: 7-f7114d4d81124b223283f3e89eee043e -Content-Length: 39 -Content-Type: text/plain - -div.recipetitle { -font-weight: bold; -} - -</programlisting> - - <para> - The returned JSON contains the new document information: - </para> - -<programlisting> -{ - "id" : "_design/recipes" - "ok" : true, - "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5", -} -</programlisting> - - <note> - <para> - Uploading an attachment updates the corresponding document - revision. Revisions are tracked for the parent document, not - individual attachments. - </para> - </note> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-attachment_delete"> - - <title><literal>DELETE /db/_design/design-doc/attachment</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API DELETE /db/_design/design-doc/attachment</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>DELETE /db/_design/design-doc/attachment</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the deleted revision - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current revision of the document for validation - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>If-Match</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Supplied revision is incorrect or missing - </entry></row></tbody></tgroup></informaltable> - - <para> - Deletes the attachment <literal>attachment</literal> to the - specified <literal>_design/design-doc</literal>. You must supply - the <literal>rev</literal> argument with the current revision to - delete the attachment. - </para> - - <para> - For example to delete the attachment <literal>view.css</literal> - from the design document <literal>recipes</literal>: - </para> - -<programlisting> -DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a - </programlisting> - - <para> - The returned JSON contains the updated revision information for - the parent document: - </para> - -<programlisting> -{ - "id" : "_design/recipes" - "ok" : true, - "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c", -} -</programlisting> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-info_get"> - - <title><literal>GET /db/_design/design-doc/_info</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/_info</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_design/design-doc/_info</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the design document information - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Obtains information about a given design document, including the - index, index size and current status of the design document and - associated index information. - </para> - - <para> - For example, to get the information for the - <literal>recipes</literal> design document: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_design/recipes/_info -Content-Type: application/json -</programlisting> - - <para> - This returns the following JSON structure: - </para> - -<programlisting> -{ - "name" : "recipes" - "view_index" : { - "compact_running" : false, - "updater_running" : false, - "language" : "javascript", - "purge_seq" : 10, - "waiting_commit" : false, - "waiting_clients" : 0, - "signature" : "fc65594ee76087a3b8c726caf5b40687", - "update_seq" : 375031, - "disk_size" : 16491 - }, -} -</programlisting> - - <para> - The individual fields in the returned JSON structure are detailed - in - <xref linkend="table-couchdb-api-design_db-designdoc-info-json"/>. - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-design_db-designdoc-info-json" class="jsonstructure"><title>Design Document Info JSON Contents</title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>name</literal> </entry><entry> - Name/ID of Design Document - </entry></row><row><entry ><literal>view_index</literal> </entry><entry> - View Index - </entry></row><row><entry > <literal>compact_running</literal> </entry><entry> - Indicates whether a compaction routine is currently running on - the view - </entry></row><row><entry > <literal>disk_size</literal> </entry><entry> - Size in bytes of the view as stored on disk - </entry></row><row><entry > <literal>language</literal> </entry><entry> - Language for the defined views - </entry></row><row><entry > <literal>purge_seq</literal> </entry><entry> - The purge sequence that has been processed - </entry></row><row><entry > <literal>signature</literal> </entry><entry> - MD5 signature of the views for the design document - </entry></row><row><entry > <literal>update_seq</literal> </entry><entry> - The update sequence of the corresponding database that has been - indexed - </entry></row><row><entry > <literal>updater_running</literal> </entry><entry> - Indicates if the view is currently being updated - </entry></row><row><entry > <literal>waiting_clients</literal> </entry><entry> - Number of clients waiting on views from this design document - </entry></row><row><entry > <literal>waiting_commit</literal> </entry><entry> - Indicates if there are outstanding commits to the underlying - database that need to processed - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_get"> - - <title><literal>GET /db/_design/design-doc/_view/view-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/_view/view-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_design/design-doc/_view/view-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the documents returned by the view - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>descending</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return the documents in descending by key order - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>endkey</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Stop returning records when the specified key is reached - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>endkey_docid</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Stop returning records when the specified document ID is - reached - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>group</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Group the results using the reduce function to a group or - single row - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>group_level</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the group level to be used - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>include_docs</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the full content of the documents in the return - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>inclusive_end</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specifies whether the specified end key should be included - in the result - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>true</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>key</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return only documents that match the specified key - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>limit</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Limit the number of the returned documents to the specified - number - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>reduce</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Use the reduction function - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>true</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>skip</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Skip this number of records before starting to return the - results - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>0</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>stale</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Allow the results from a stale view to be used - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>ok</literal></entry><entry>Allow stale views</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>startkey</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return records starting with the specified key - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>startkey_docid</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return records starting with the specified document ID - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>update_seq</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the update sequence in the generated results - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row></tbody></tgroup></informaltable> - - <para> - Executes the specified <literal>view-name</literal> from the - specified <literal>design-doc</literal> design document. - </para> - - <section - id="couchdb-api-design_db-design-designdoc-view-viewname_get-indexes"> - - <title>Querying Views and Indexes</title> - - <para> - The definition of a view within a design document also creates - an index based on the key information defined within each view. - The production and use of the index significantly increases the - speed of access and searching or selecting documents from the - view. - </para> - - <para> - However, the index is not updated when new documents are added - or modified in the database. Instead, the index is generated or - updated, either when the view is first accessed, or when the - view is accessed after a document has been updated. In each - case, the index is updated before the view query is executed - against the database. - </para> - - <para> - View indexes are updated incrementally in the following - situations: - </para> - - <itemizedlist> - - <listitem> - <para> - A new document has been added to the database. - </para> - </listitem> - - <listitem> - <para> - A document has been deleted from the database. - </para> - </listitem> - - <listitem> - <para> - A document in the database has been updated. - </para> - </listitem> - - </itemizedlist> - - <para> - View indexes are rebuilt entirely when the view definition - changes. To achieve this, a 'fingerprint' of the view definition - is created when the design document is updated. If the - fingerprint changes, then the view indexes are entirely rebuilt. - This ensures that changes to the view definitions are reflected - in the view indexes. - </para> - - <note> - <para> - View index rebuilds occur when one view from the same the view - group (i.e. all the views defined within a single a design - document) has been determined as needing a rebuild. For - example, if if you have a design document with different - views, and you update the database, all three view indexes - within the design document will be updated. - </para> - </note> - - <para> - Because the view is updated when it has been queried, it can - result in a delay in returned information when the view is - accessed, especially if there are a large number of documents in - the database and the view index does not exist. There are a - number of ways to mitigate, but not completely eliminate, these - issues. These include: - </para> - - <itemizedlist> - - <listitem> - <para> - Create the view definition (and associated design documents) - on your database before allowing insertion or updates to the - documents. If this is allowed while the view is being - accessed, the index can be updated incrementally. - </para> - </listitem> - - <listitem> - <para> - Manually force a view request from the database. You can do - this either before users are allowed to use the view, or you - can access the view manually after documents are added or - updated. - </para> - </listitem> - - <listitem> - <para> - Use the <literal>/db/_changes</literal> method to monitor - for changes to the database and then access the view to - force the corresponding view index to be updated. See - <xref - linkend="couchdb-api-db_db-changes_get"/> - for more information. - </para> - </listitem> - - <listitem> - <para> - Use a monitor with the - <literal>update_notification</literal> section of the - CouchDB configuration file to monitor for changes to your - database, and trigger a view query to force the view to be - updated. For more information, see - <xref - linkend="couchdb-single-configuration-update_notification"/>. - </para> - </listitem> - - </itemizedlist> - - <para> - None of these can completely eliminate the need for the indexes - to be rebuilt or updated when the view is accessed, but they may - lessen the effects on end-users of the index update affecting - the user experience. - </para> - - <para> - Another alternative is to allow users to access a 'stale' - version of the view index, rather than forcing the index to be - updated and displaying the updated results. Using a stale view - may not return the latest information, but will return the - results of the view query using an existing version of the - index. - </para> - - <para> - For example, to access the existing stale view - <literal>by_recipe</literal> in the <literal>recipes</literal> - design document: - </para> - -<programlisting>http://couchdb:5984/recipes/_design/recipes/_view/by_recipe?stale=ok</programlisting> - - <para> - Accessing a stale view: - </para> - - <itemizedlist> - - <listitem> - <para> - Does not trigger a rebuild of the view indexes, even if - there have been changes since the last access. - </para> - </listitem> - - <listitem> - <para> - Returns the current version of the view index, if a current - version exists. - </para> - </listitem> - - <listitem> - <para> - Returns an empty result set if the given view index does - exist. - </para> - </listitem> - - </itemizedlist> - - <para> - As an alternative, you use the <literal>update_after</literal> - value to the <option>stale</option> paramater. This causes the - view to be returned as a stale view, but for the update process - to be triggered after the view information has been returned to - the client. - </para> - - <para> - In addition to using stale views, you can also make use of the - <literal>update_seq</literal> query argument. Using this query - argument generates the view information including the update - sequence of the database from which the view was generated. The - returned value can be compared this to the current update - sequence exposed in the database information (returned by - <xref linkend="couchdb-api-db_db_get"/>). - </para> - - </section> - - <section - id="couchdb-api-design_db-design-designdoc-view-viewname_get-sorting"> - - <title>Sorting Returned Rows</title> - - <para> - Each element within the returned array is sorted using native - UTF-8 sorting according to the contents of the key portion of - the emitted content. The basic order of output is as follows: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>null</literal> - </para> - </listitem> - - <listitem> - <para> - <literal>false</literal> - </para> - </listitem> - - <listitem> - <para> - <literal>true</literal> - </para> - </listitem> - - <listitem> - <para> - Numbers - </para> - </listitem> - - <listitem> - <para> - Text (case sensitive, lowercase first) - </para> - </listitem> - - <listitem> - <para> - Arrays (according to the values of each element, in order) - </para> - </listitem> - - <listitem> - <para> - Objects (according to the values of keys, in key order) - </para> - </listitem> - - </itemizedlist> - - - - <para> - You can reverse the order of the returned view information by - using the <literal>descending</literal> query value set to true. - For example, Retrieving the list of recipes using the - <literal>by_title</literal> (limited to 5 records) view: - </para> - -<programlisting> -{ - "offset" : 0, - "rows" : [ - { - "id" : "3-tiersalmonspinachandavocadoterrine", - "key" : "3-tier salmon, spinach and avocado terrine", - "value" : [ - null, - "3-tier salmon, spinach and avocado terrine" - ] - }, - { - "id" : "Aberffrawcake", - "key" : "Aberffraw cake", - "value" : [ - null, - "Aberffraw cake" - ] - }, - { - "id" : "Adukiandorangecasserole-microwave", - "key" : "Aduki and orange casserole - microwave", - "value" : [ - null, - "Aduki and orange casserole - microwave" - ] - }, - { - "id" : "Aioli-garlicmayonnaise", - "key" : "Aioli - garlic mayonnaise", - "value" : [ - null, - "Aioli - garlic mayonnaise" - ] - }, - { - "id" : "Alabamapeanutchicken", - "key" : "Alabama peanut chicken", - "value" : [ - null, - "Alabama peanut chicken" - ] - } - ], - "total_rows" : 2667 -} -</programlisting> - - <para> - Requesting the same in descending order will reverse the entire - view content. For example the request - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_design/recipes/_view/by_title?limit=5&descending=true -Accept: application/json -Content-Type: application/json</programlisting> - - <para> - Returns the last 5 records from the view: - </para> - -<programlisting> -{ - "offset" : 0, - "rows" : [ - { - "id" : "Zucchiniinagrodolcesweet-sourcourgettes", - "key" : "Zucchini in agrodolce (sweet-sour courgettes)", - "value" : [ - null, - "Zucchini in agrodolce (sweet-sour courgettes)" - ] - }, - { - "id" : "Zingylemontart", - "key" : "Zingy lemon tart", - "value" : [ - null, - "Zingy lemon tart" - ] - }, - { - "id" : "Zestyseafoodavocado", - "key" : "Zesty seafood avocado", - "value" : [ - null, - "Zesty seafood avocado" - ] - }, - { - "id" : "Zabaglione", - "key" : "Zabaglione", - "value" : [ - null, - "Zabaglione" - ] - }, - { - "id" : "Yogurtraita", - "key" : "Yogurt raita", - "value" : [ - null, - "Yogurt raita" - ] - } - ], - "total_rows" : 2667 -} -</programlisting> - - <para> - The sorting direction is applied before the filtering applied - using the <literal>startkey</literal> and - <literal>endkey</literal> query arguments. For example the - following query: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?startkey=%22carrots%22&endkey=%22egg%22 -Accept: application/json -Content-Type: application/json -</programlisting> - - <para> - Will operate correctly when listing all the matching entries - between <quote>carrots</quote> and <literal>egg</literal>. If - the order of output is reversed with the - <literal>descending</literal> query argument, the view request - will return no entries: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22carrots%22&endkey=%22egg%22 -Accept: application/json -Content-Type: application/json -</programlisting> - - <para> - The returned result is empty: - </para> - -<programlisting> -{ - "total_rows" : 26453, - "rows" : [], - "offset" : 21882 -} -</programlisting> - - <para> - The results will be empty because the entries in the view are - reversed before the key filter is applied, and therefore the - <literal>endkey</literal> of <quote>egg</quote> will be seen - before the <literal>startkey</literal> of - <quote>carrots</quote>, resulting in an empty list. - </para> - - <para> - Instead, you should reverse the values supplied to the - <literal>startkey</literal> and <literal>endkey</literal> - parameters to match the descending sorting applied to the keys. - Changing the previous example to: - </para> - -<programlisting> -GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22egg%22&endkey=%22carrots%22 -Accept: application/json -Content-Type: application/json -</programlisting> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_get-ranges"> - - <title>Specifying Start and End Values</title> - - <para> - The <literal>startkey</literal> and <literal>endkey</literal> - query arguments can be used to specify the range of values to be - displayed when querying the view. - </para> - - <note> - <para> - The values - </para> - </note> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_get-limit"> - - <title>Using Limits and Skipping Rows</title> - - <para> - TBC - </para> - - </section> - - <section - id="couchdb-api-design_db-design-designdoc-view-viewname_get-reduction"> - - <title>View Reduction and Grouping</title> - - <para> - TBC - </para> - - </section> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-view-viewname_post"> - - <title><literal>POST /db/_design/design-doc/_view/view-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_design/design-doc/_view/view-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_design/design-doc/_view/view-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - List of keys to be returned from specified view - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the documents returned by the view - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>descending</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return the documents in descending by key order - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>endkey</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Stop returning records when the specified key is reached - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>endkey_docid</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Stop returning records when the specified document ID is - reached - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>group</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Group the results using the reduce function to a group or - single row - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>group_level</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the group level to be used - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>include_docs</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the full content of the documents in the return - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>inclusive_end</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specifies whether the specified end key should be included - in the result - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>true</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>key</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return only documents that match the specified key - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>limit</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Limit the number of the returned documents to the specified - number - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>reduce</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Use the reduction function - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>true</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>skip</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Skip this number of records before starting to return the - results - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>0</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>stale</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Allow the results from a stale view to be used - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>ok</literal></entry><entry>Allow stale views</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>startkey</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return records starting with the specified key - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>startkey_docid</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return records starting with the specified document ID - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>update_seq</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Include the update sequence in the generated results - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>false</entry></row></tbody></tgroup></informaltable> - - <para> - Executes the specified <literal>view-name</literal> from the - specified <literal>design-doc</literal> design document. Unlike - the <literal>GET</literal> method for accessing views, the - <literal>POST</literal> method supports the specification of - explicit keys to be retrieved from the view results. The remainder - of the <literal>POST</literal> view functionality is identical to - the - <xref - linkend="couchdb-api-design_db-design-designdoc-view-viewname_get"/> - fun - </para> - - <para> - For example, the request below will return all the recipes where - the key for the view matches either <quote>claret</quote> or - <quote>clear apple cider</quote> : - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient -Content-Type: application/json - -{ - "keys" : [ - "claret", - "clear apple juice" - ] -} - </programlisting> - - <para> - The returned view data contains the standard view information, but - only where the keys match. - </para> - -<programlisting> -{ - "total_rows" : 26484, - "rows" : [ - { - "value" : [ - "Scotch collops" - ], - "id" : "Scotchcollops", - "key" : "claret" - }, - { - "value" : [ - "Stand pie" - ], - "id" : "Standpie", - "key" : "clear apple juice" - } - ], - "offset" : 6324 -} -</programlisting> - - <section - id="couchdb-api-design_db-design-designdoc-view-viewname_post-multidoc"> - - <title>Multi-document Fetching</title> - - <para> - By combining the <literal>POST</literal> method to a given view - with the <literal>include_docs=true</literal> query argument you - can obtain multiple documents from a database. The result is - more efficient than using multiple - <xref - linkend="couchdb-api-dbdoc_db-doc_get"/> - requests. - </para> - - <para> - For example, sending the following request for ingredients - matching <quote>claret</quote> and <quote>clear apple - juice</quote>: - </para> - -<programlisting> -POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?include_docs=true -Content-Type: application/json - -{ - "keys" : [ - "claret", - "clear apple juice" - ] -} -</programlisting> - - <para> - Returns the full document for each recipe: - </para> - -<programlisting> -{ - "offset" : 6324, - "rows" : [ - { - "doc" : { - "_id" : "Scotchcollops", - "_rev" : "1-bcbdf724f8544c89697a1cbc4b9f0178", - "cooktime" : "8", - "ingredients" : [ - { - "ingredient" : "onion", - "ingredtext" : "onion, peeled and chopped", - "meastext" : "1" - }, - ... - ], - "keywords" : [ - "cook method.hob, oven, grill@hob", - "diet@wheat-free", - "diet@peanut-free", - "special collections@classic recipe", - "cuisine@british traditional", - "diet@corn-free", - "diet@citrus-free", - "special collections@very easy", - "diet@shellfish-free", - "main ingredient@meat", - "occasion@christmas", - "meal type@main", - "diet@egg-free", - "diet@gluten-free" - ], - "preptime" : "10", - "servings" : "4", - "subtitle" : "This recipe comes from an old recipe book of 1683 called 'The Gentlewoman's Kitchen'. This is an excellent way of making a rich and full-flavoured meat dish in a very short time.", - "title" : "Scotch collops", - "totaltime" : "18" - }, - "id" : "Scotchcollops", - "key" : "claret", - "value" : [ - "Scotch collops" - ] - }, - { - "doc" : { - "_id" : "Standpie", - "_rev" : "1-bff6edf3ca2474a243023f2dad432a5a", - "cooktime" : "92", - "ingredients" : [ -... ], - "keywords" : [ - "diet@dairy-free", - "diet@peanut-free", - "special collections@classic recipe", - "cuisine@british traditional", - "diet@corn-free", - "diet@citrus-free", - "occasion@buffet party", - "diet@shellfish-free", - "occasion@picnic", - "special collections@lunchbox", - "main ingredient@meat", - "convenience@serve with salad for complete meal", - "meal type@main", - "cook method.hob, oven, grill@hob / oven", - "diet@cow dairy-free" - ], - "preptime" : "30", - "servings" : "6", - "subtitle" : "Serve this pie with pickled vegetables and potato salad.", - "title" : "Stand pie", - "totaltime" : "437" - }, - "id" : "Standpie", - "key" : "clear apple juice", - "value" : [ - "Stand pie" - ] - } - ], - "total_rows" : 26484 -} -</programlisting> - - </section> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-show-showname_get"> - - <title><literal>POST /db/_design/design-doc/_show/show-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/_show/show-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_design/design-doc/_show/show-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Returns the result of the show - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>details</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Indicates whether details should be included - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>format</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Format of the returned information - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row></tbody></tgroup></informaltable> - - <para></para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-show-showname-doc_get"> - - <title><literal>POST /db/_design/design-doc/_show/show-name/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/_show/show-name/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_design/design-doc/_show/show-name/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Returns the show for the given document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para></para> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-list-listname-otherdesigndoc-viewname_get"> - - <title><literal>GET - /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-list-listname-otherdesigndoc-viewname_post"> - - <title><literal>POST - /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-list-listname-viewname_get"> - - <title><literal>GET /db/_design/design-doc/_list/list-name/view-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_design/design-doc/_list/list-name/view-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_design/design-doc/_list/list-name/view-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-list-listname-viewname_post"> - - <title><literal>POST /db/_design/design-doc/_list/list-name/view-name</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_design/design-doc/_list/list-name/view-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_design/design-doc/_list/list-name/view-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section id="couchdb-api-design_db-design-designdoc-update-updatename-doc_put"> - - <title><literal>PUT /db/_design/design-doc/_update/updatename/doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/_design/design-doc/_update/update-name/doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>PUT /db/_design/design-doc/_update/update-name/doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - Document update information - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Updated document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section - id="couchdb-api-design_db-design-designdoc-update-updatename_post"> - - <title><literal>POST /db/_design/design-doc/_update/updatename</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API POST /db/_design/design-doc/_update/update-name</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /db/_design/design-doc/_update/update-name</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - Document update information - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Updated document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - - <section - id="couchdb-api-design_db-design-designdoc-rewrite-rewritename-anything"> - - <title><literal>ALL - /db/_design/design-doc/_rewrite/rewrite-name/anything</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API ALL /db/_design/design-doc/_rewrite/rewrite-name/anything</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>ALL /db/_design/design-doc/_rewrite/rewrite-name/anything</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - TBC - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-json.xml b/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-json.xml deleted file mode 100644 index 6e773d481..000000000 --- a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-json.xml +++ /dev/null @@ -1,347 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE appendix PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<appendix id="couchdb-api-json"> - - <title>JSON Structure Reference</title> - - <para> - The following appendix provides a quick reference to all the JSON - structures that you can supply to CouchDB, or get in return to - requests. - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-json-summary"><title>JSON Structures</title><tgroup cols="1"><colspec colname="desc"/><thead><row><entry>Description</entry></row></thead><tbody><row><entry><link linkend="table-couchdb-api-json_all-docs"> - All Database Documents - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_bulkdocsreturn"> - Bulk Document Response - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_bulkdocs"> - Bulk Documents - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_changes"> - Changes information for a database - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_document"> - CouchDB Document - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_jsonerror"> - CouchDB Error Status - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_db-info"> - CouchDB database information object - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_design-doc"> - Design Document - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_design-doc_info"> - Design Document Information - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_design-doc_info-spatial"> - Design Document spatial index Information - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_document_with_attachments"> - Document with Attachments - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_activetasks"> - List of Active Tasks - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_replication"> - Replication Settings - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_replication-status"> - Replication Status - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_document_with_revs_info"> - Returned CouchDB Document with Detailed Revision Info - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_document_with_revs"> - Returned CouchDB Document with Revision Info - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_returneddocument_with_attachments"> - Returned Document with Attachments - </link></entry></row><row><entry><link linkend="table-couchdb-api-json_security"> - Security Object - </link></entry></row></tbody></tgroup></table> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-json_all-docs" class="jsonstructure"><title> - All Database Documents - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>offset</literal> </entry><entry> - Offset where the document list started - </entry></row><row><entry ><literal>rows</literal> <literal>[array]</literal> </entry><entry> - Array of document object - </entry></row><row><entry ><literal>total_rows</literal> </entry><entry> - Number of documents in the database/view - </entry></row><row><entry ><literal>update_seq</literal> (optional) </entry><entry> - Current update sequence for the database - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_bulkdocsreturn" class="jsonstructure"><title> - Bulk Document Response - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>docs</literal> <literal>[array]</literal> </entry><entry> - Bulk Docs Returned Documents - </entry></row><row><entry > <literal>error</literal> </entry><entry> - Error type - </entry></row><row><entry > <literal>id</literal> </entry><entry> - Document ID - </entry></row><row><entry > <literal>reason</literal> </entry><entry> - Error string with extended reason - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_bulkdocs" class="jsonstructure"><title> - Bulk Documents - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>all_or_nothing</literal> (optional) </entry><entry> - Sets the database commit mode to use all-or-nothing semantics - </entry></row><row><entry ><literal>docs</literal> <literal>[array]</literal> </entry><entry> - Bulk Documents Document - </entry></row><row><entry > <literal>_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry > <literal>_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry > <literal>_deleted</literal> (optional) </entry><entry> - Whether the document should be deleted - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_changes" class="jsonstructure"><title> - Changes information for a database - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>last_seq</literal> </entry><entry> - Last change sequence number - </entry></row><row><entry ><literal>results</literal> <literal>[array]</literal> </entry><entry> - Changes made to a database - </entry></row><row><entry > <literal>changes</literal> <literal>[array]</literal> </entry><entry> - List of changes, field-by-field, for this document - </entry></row><row><entry > <literal>id</literal> </entry><entry> - Document ID - </entry></row><row><entry > <literal>seq</literal> </entry><entry> - Update sequence number - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_document" class="jsonstructure"><title> - CouchDB Document - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry ><literal>_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_jsonerror" class="jsonstructure"><title> - CouchDB Error Status - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>error</literal> </entry><entry> - Error type - </entry></row><row><entry ><literal>id</literal> </entry><entry> - Document ID - </entry></row><row><entry ><literal>reason</literal> </entry><entry> - Error string with extended reason - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_db-info" class="jsonstructure"><title> - CouchDB database information object - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>committed_update_seq</literal> </entry><entry> - The number of committed update. - </entry></row><row><entry ><literal>compact_running</literal> </entry><entry> - Set to true if the database compaction routine is operating on - this database. - </entry></row><row><entry ><literal>db_name</literal> </entry><entry> - The name of the database. - </entry></row><row><entry ><literal>disk_format_version</literal> </entry><entry> - The version of the physical format used for the data when it is - stored on disk. - </entry></row><row><entry ><literal>disk_size</literal> </entry><entry> - Size in bytes of the data as stored on the disk. Views indexes - are not included in the calculation. - </entry></row><row><entry ><literal>doc_count</literal> </entry><entry> - A count of the documents in the specified database. - </entry></row><row><entry ><literal>doc_del_count</literal> </entry><entry> - Number of deleted documents - </entry></row><row><entry ><literal>instance_start_time</literal> </entry><entry> - Timestamp of when the database was created, expressed in - milliseconds since the epoch. - </entry></row><row><entry ><literal>purge_seq</literal> </entry><entry> - The number of purge operations on the database. - </entry></row><row><entry ><literal>update_seq</literal> </entry><entry> - The current number of updates to the database. - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_design-doc" class="jsonstructure"><title> - Design Document - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>_id</literal> </entry><entry> - Design Document ID - </entry></row><row><entry ><literal>_rev</literal> </entry><entry> - Design Document Revision - </entry></row><row><entry ><literal>views</literal> </entry><entry> - View - </entry></row><row><entry > <literal>viewname</literal> </entry><entry> - View Definition - </entry></row><row><entry > <literal>map</literal> </entry><entry> - Map Function for View - </entry></row><row><entry > <literal>reduce</literal> (optional) </entry><entry> - Reduce Function for View - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_design-doc_info" class="jsonstructure"><title> - Design Document Information - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>name</literal> </entry><entry> - Name/ID of Design Document - </entry></row><row><entry ><literal>view_index</literal> </entry><entry> - View Index - </entry></row><row><entry > <literal>compact_running</literal> </entry><entry> - Indicates whether a compaction routine is currently running on - the view - </entry></row><row><entry > <literal>disk_size</literal> </entry><entry> - Size in bytes of the view as stored on disk - </entry></row><row><entry > <literal>language</literal> </entry><entry> - Language for the defined views - </entry></row><row><entry > <literal>purge_seq</literal> </entry><entry> - The purge sequence that has been processed - </entry></row><row><entry > <literal>signature</literal> </entry><entry> - MD5 signature of the views for the design document - </entry></row><row><entry > <literal>update_seq</literal> </entry><entry> - The update sequence of the corresponding database that has been - indexed - </entry></row><row><entry > <literal>updater_running</literal> </entry><entry> - Indicates if the view is currently being updated - </entry></row><row><entry > <literal>waiting_clients</literal> </entry><entry> - Number of clients waiting on views from this design document - </entry></row><row><entry > <literal>waiting_commit</literal> </entry><entry> - Indicates if there are outstanding commits to the underlying - database that need to processed - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_design-doc_info-spatial" class="jsonstructure"><title> - Design Document spatial index Information - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>name</literal> </entry><entry> - Name/ID of Design Document - </entry></row><row><entry ><literal>spatial_index</literal> </entry><entry> - View Index - </entry></row><row><entry > <literal>compact_running</literal> </entry><entry> - Indicates whether a compaction routine is currently running on - the view - </entry></row><row><entry > <literal>disk_size</literal> </entry><entry> - Size in bytes of the view as stored on disk - </entry></row><row><entry > <literal>language</literal> </entry><entry> - Language for the defined views - </entry></row><row><entry > <literal>purge_seq</literal> </entry><entry> - The purge sequence that has been processed - </entry></row><row><entry > <literal>signature</literal> </entry><entry> - MD5 signature of the views for the design document - </entry></row><row><entry > <literal>update_seq</literal> </entry><entry> - The update sequence of the corresponding database that has been - indexed - </entry></row><row><entry > <literal>updater_running</literal> </entry><entry> - Indicates if the view is currently being updated - </entry></row><row><entry > <literal>waiting_clients</literal> </entry><entry> - Number of clients waiting on views from this design document - </entry></row><row><entry > <literal>waiting_commit</literal> </entry><entry> - Indicates if there are outstanding commits to the underlying - database that need to processed - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_document_with_attachments" class="jsonstructure"><title> - Document with Attachments - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry ><literal>_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry ><literal>_attachments</literal> (optional) </entry><entry> - Document Attachment - </entry></row><row><entry > <literal>filename</literal> </entry><entry> - Attachment information - </entry></row><row><entry > <literal>content_type</literal> </entry><entry> - MIME Content type string - </entry></row><row><entry > <literal>data</literal> </entry><entry> - File attachment content, Base64 encoded - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_activetasks" class="jsonstructure"><title> - List of Active Tasks - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>tasks</literal> <literal>[array]</literal> </entry><entry> - Active Task - </entry></row><row><entry > <literal>pid</literal> </entry><entry> - Process ID - </entry></row><row><entry > <literal>status</literal> </entry><entry> - Task status message - </entry></row><row><entry > <literal>task</literal> </entry><entry> - Task name - </entry></row><row><entry > <literal>type</literal> </entry><entry> - Operation Type - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_replication" class="jsonstructure"><title> - Replication Settings - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>cancel</literal> (optional) </entry><entry> - Cancels the replication - </entry></row><row><entry ><literal>continuous</literal> (optional) </entry><entry> - Configure the replication to be continuous - </entry></row><row><entry ><literal>create_target</literal> (optional) </entry><entry> - Creates the target database - </entry></row><row><entry ><literal>doc_ids</literal> (optional) </entry><entry> - Array of document IDs to be synchronized - </entry></row><row><entry ><literal>proxy</literal> (optional) </entry><entry> - Address of a proxy server through which replication should occur - </entry></row><row><entry ><literal>source</literal> </entry><entry> - Source database name or URL - </entry></row><row><entry ><literal>target</literal> </entry><entry> - Target database name or URL - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_replication-status" class="jsonstructure"><title> - Replication Status - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>history</literal> <literal>[array]</literal> </entry><entry> - Replication History - </entry></row><row><entry > <literal>doc_write_failures</literal> </entry><entry> - Number of document write failures - </entry></row><row><entry > <literal>docs_read</literal> </entry><entry> - Number of documents read - </entry></row><row><entry > <literal>docs_written</literal> </entry><entry> - Number of documents written to target - </entry></row><row><entry > <literal>end_last_seq</literal> </entry><entry> - Last sequence number in changes stream - </entry></row><row><entry > <literal>end_time</literal> </entry><entry> - Date/Time replication operation completed - </entry></row><row><entry > <literal>missing_checked</literal> </entry><entry> - Number of missing documents checked - </entry></row><row><entry > <literal>missing_found</literal> </entry><entry> - Number of missing documents found - </entry></row><row><entry > <literal>recorded_seq</literal> </entry><entry> - Last recorded sequence number - </entry></row><row><entry > <literal>session_id</literal> </entry><entry> - Session ID for this replication operation - </entry></row><row><entry > <literal>start_last_seq</literal> </entry><entry> - First sequence number in changes stream - </entry></row><row><entry > <literal>start_time</literal> </entry><entry> - Date/Time replication operation started - </entry></row><row><entry ><literal>ok</literal> </entry><entry> - Replication status - </entry></row><row><entry ><literal>session_id</literal> </entry><entry> - Unique session ID - </entry></row><row><entry ><literal>source_last_seq</literal> </entry><entry> - Last sequence number read from source database - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_document_with_revs_info" class="jsonstructure"><title> - Returned CouchDB Document with Detailed Revision Info - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry ><literal>_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry ><literal>_revs_info</literal> <literal>[array]</literal> </entry><entry> - CouchDB Document Extended Revision Info - </entry></row><row><entry > <literal>rev</literal> </entry><entry> - Full revision string - </entry></row><row><entry > <literal>status</literal> </entry><entry> - Status of the revision - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_document_with_revs" class="jsonstructure"><title> - Returned CouchDB Document with Revision Info - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry ><literal>_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry ><literal>_revisions</literal> </entry><entry> - CouchDB Document Revisions - </entry></row><row><entry > <literal>ids</literal> <literal>[array]</literal> </entry><entry> - Array of valid revision IDs, in reverse order (latest first) - </entry></row><row><entry > <literal>start</literal> </entry><entry> - Prefix number for the latest revision - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_returneddocument_with_attachments" class="jsonstructure"><title> - Returned Document with Attachments - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>_id</literal> (optional) </entry><entry> - Document ID - </entry></row><row><entry ><literal>_rev</literal> (optional) </entry><entry> - Revision ID (when updating an existing document) - </entry></row><row><entry ><literal>_attachments</literal> (optional) </entry><entry> - Document Attachment - </entry></row><row><entry > <literal>filename</literal> </entry><entry> - Attachment - </entry></row><row><entry > <literal>content_type</literal> </entry><entry> - MIME Content type string - </entry></row><row><entry > <literal>length</literal> </entry><entry> - Length (bytes) of the attachment data - </entry></row><row><entry > <literal>revpos</literal> </entry><entry> - Revision where this attachment exists - </entry></row><row><entry > <literal>stub</literal> </entry><entry> - Indicates whether the attachment is a stub - </entry></row></tbody></tgroup></table><table id="table-couchdb-api-json_security" class="jsonstructure"><title> - Security Object - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>admins</literal> </entry><entry> - Roles/Users with admin privileges - </entry></row><row><entry > <literal>roles</literal> <literal>[array]</literal> </entry><entry> - List of roles with parent privilege - </entry></row><row><entry > <literal>users</literal> <literal>[array]</literal> </entry><entry> - List of users with parent privilege - </entry></row><row><entry ><literal>readers</literal> </entry><entry> - Roles/Users with reader privileges - </entry></row><row><entry > <literal>roles</literal> <literal>[array]</literal> </entry><entry> - List of roles with parent privilege - </entry></row><row><entry > <literal>users</literal> <literal>[array]</literal> </entry><entry> - List of users with parent privilege - </entry></row></tbody></tgroup></table> - -</appendix> diff --git a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-localdb.xml b/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-localdb.xml deleted file mode 100644 index 9f7161f14..000000000 --- a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-localdb.xml +++ /dev/null @@ -1,188 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-localdb"> - - <title>CouchDB API Server Local (non-replicating) Document Methods</title> - - <para> - The Local (non-replicating) document interface allows you to create - local documents that are not replicated to other databases. These - documents can be used to hold configuration or other information - that is required specifically on the local CouchDB instance. - </para> - - <para> - Local documents have the following limitations: - </para> - - <itemizedlist> - - <listitem> - <para> - Local documents are not replicated to other databases. - </para> - </listitem> - - <listitem> - <para> - The ID of the local document must be known for the document to - accessed. You cannot obtain a list of local documents from the - database. - </para> - </listitem> - - <listitem> - <para> - Local documents are not output by views, or the - <literal>_all_docs</literal> view. - </para> - </listitem> - - </itemizedlist> - - <para> - Local documents can be used when you want to store configuration or - other information for the curent (local) instance of a given - database. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-api-localdb-summary"><title>Local (non-replicating) Document API - Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>GET</literal></entry><entry><literal>/db/_local/local-doc</literal></entry><entry><link linkend="couchdb-api-localdb_db-local-localdoc_get"> - Returns the latest revision of the non-replicated document - </link></entry></row><row><entry><literal>PUT</literal></entry><entry><literal>/db/_local/local-doc</literal></entry><entry><link linkend="couchdb-api-localdb_db-local-localdoc_put"> - Inserts a new version of the non-replicated document - </link></entry></row><row><entry><literal>DELETE</literal></entry><entry><literal>/db/_local/local-doc</literal></entry><entry><link linkend="couchdb-api-localdb_db-local-localdoc_delete"> - Deletes the non-replicated document - </link></entry></row><row><entry><literal>COPY</literal></entry><entry><literal>/db/_local/local-doc</literal></entry><entry><link linkend="couchdb-api-localdb_db-local-localdoc_copy"> - Copies the non-replicated document - </link></entry></row></tbody></tgroup></table> - - <section id="couchdb-api-localdb_db-local-localdoc_get"> - - <title><literal>GET /db/_local/local-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /db/_local/local-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /db/_local/local-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the returned document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Specify the revision to return - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>true</literal></entry><entry>Includes the revisions</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>revs</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of the revisions for the document - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>revs_info</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Return a list of detailed revision information for the - document - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>boolean</entry></row><row><entry></entry><entry><emphasis role="bold">Supported Values</emphasis></entry></row><row><entry></entry><entry><literal>true</literal></entry><entry>Includes the revisions</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>400</entry><entry namest="info" nameend="addinfo"> - The format of the request or revision was invalid - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The specified document or revision cannot be found, or has been - deleted - </entry></row></tbody></tgroup></informaltable> - - <para> - Gets the specified local document. The semantics are identical to - accessing a standard document in the specified database, except - that the document is not replicated. See - <xref - linkend="couchdb-api-dbdoc_db-doc_get"/>. - </para> - - </section> - - <section id="couchdb-api-localdb_db-local-localdoc_put"> - - <title><literal>PUT /db/_local/local-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API PUT /db/_local/local-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>PUT /db/_local/local-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the document - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON with the committed document information - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document has been created successfully - </entry></row></tbody></tgroup></informaltable> - - <para> - Stores the specified local document. The semantics are identical - to storing a standard document in the specified database, except - that the document is not replicated. See - <xref - linkend="couchdb-api-dbdoc_db-doc_put"/>. - </para> - - </section> - - <section id="couchdb-api-localdb_db-local-localdoc_delete"> - - <title><literal>DELETE /db/_local/local-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API DELETE /db/_local/local-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>DELETE /db/_local/local-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON with the deleted document information - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Current revision of the document for validation - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>If-Match</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> - Supplied revision is incorrect or missing - </entry></row></tbody></tgroup></informaltable> - - <para> - Deletes the specified local document. The semantics are identical - to deleting a standard document in the specified database, except - that the document is not replicated. See - <xref - linkend="couchdb-api-dbdoc_db-doc_delete"/>. - </para> - - </section> - - <section id="couchdb-api-localdb_db-local-localdoc_copy"> - - <title><literal>COPY /db/_local/local-doc</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API COPY /db/_local/local-doc</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>COPY /db/_local/local-doc</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON of the copied document - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Revision to copy from - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>Destination</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Destination document (and optional revision)</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>no</entry></row><row><entry></entry><entry></entry><entry></entry></row></tbody></tgroup></informaltable> - - <para> - Copies the specified local document. The semantics are identical - to copying a standard document in the specified database, except - that the document is not replicated. See - <xref - linkend="couchdb-api-dbdoc_db-doc_copy"/>. - </para> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-misc.xml b/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-misc.xml deleted file mode 100644 index a9ae88264..000000000 --- a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-misc.xml +++ /dev/null @@ -1,1412 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<chapter id="couchdb-api-misc"> - - <title>CouchDB API Server Miscellaneous Methods</title> - - <para> - The CouchDB Miscellaneous interface provides the basic interface to - a CouchDB server for obtaining CouchDB information and getting and - setting configuration information. - </para> - - <para> - A list of the available methods and URL paths are provided below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-misc-summary"><title>Miscellaneous API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>GET</literal></entry><entry><literal>/</literal></entry><entry><link linkend="couchdb-api-misc_root_get"> - Get the welcome message and version information - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_active_tasks</literal></entry><entry><link linkend="couchdb-api-misc_active-tasks_get"> - Obtain a list of the tasks running in the server - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_all_dbs</literal></entry><entry><link linkend="couchdb-api-misc_all-dbs_get"> - Get a list of all the DBs - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_log</literal></entry><entry><link linkend="couchdb-api-misc_log_get"> - Return the server log file - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/_replicate</literal></entry><entry><link linkend="couchdb-api-misc_replicate_post"> - Set or cancel replication - </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/_restart</literal></entry><entry><link linkend="couchdb-api-misc_restart_post"> - Restart the server - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_stats</literal></entry><entry><link linkend="couchdb-api-misc_stats_get"> - Return server statistics - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_utils</literal></entry><entry><link linkend="couchdb-api-misc_utils_get"> - CouchDB administration interface (Futon) - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_uuids</literal></entry><entry><link linkend="couchdb-api-misc_uuids_get"> - Get generated UUIDs from the server - </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/favicon.ico</literal></entry><entry><link linkend="couchdb-api-misc_favicon_get"> - Get the site icon - </link></entry></row></tbody></tgroup></table> - - <section id="couchdb-api-misc_root_get"> - - <title><literal>GET /</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Welcome message and version - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - Accessing the root of a CouchDB instance returns meta information - about the instance. The response is a JSON structure containing - information about the server, including a welcome message and the - version of the server. - </para> - -<programlisting> -{ - "couchdb" : "Welcome", - "version" : "1.0.1" -} -</programlisting> - - </section> - - <section id="couchdb-api-misc_active-tasks_get"> - - <title><literal>GET /_active_tasks</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /_active_tasks</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /_active_tasks</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - List of running tasks, including the task type, name, status and - process ID - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - You can obtain a list of active tasks by using the - <literal>/_active_tasks</literal> URL. The result is a JSON array - of the currently running tasks, with each task being described - with a single object. For example: - </para> - -<programlisting> - -<![CDATA[ -[ - { - "pid" : "<0.11599.0>", - "status" : "Copied 0 of 18369 changes (0%)", - "task" : "recipes", - "type" : "Database Compaction" - } -] -]]> - - </programlisting> - - <para> - The returned structure includes the following fields for each - task: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-misc-active-tasks-json" class="jsonstructure"><title> - List of Active Tasks - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>tasks</literal> <literal>[array]</literal> </entry><entry> - Active Task - </entry></row><row><entry > <literal>pid</literal> </entry><entry> - Process ID - </entry></row><row><entry > <literal>status</literal> </entry><entry> - Task status message - </entry></row><row><entry > <literal>task</literal> </entry><entry> - Task name - </entry></row><row><entry > <literal>type</literal> </entry><entry> - Operation Type - </entry></row></tbody></tgroup></table> - - <para> - For operation type, valid values include: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>Database Compaction</literal> - </para> - </listitem> - - <listitem> - <para> - <literal>Replication</literal> - </para> - </listitem> - - <listitem> - <para> - <literal>View Group Compaction</literal> - </para> - </listitem> - - <listitem> - <para> - <literal>View Group Indexer</literal> - </para> - </listitem> - - </itemizedlist> - - </section> - - <section id="couchdb-api-misc_all-dbs_get"> - - <title><literal>GET /_all_dbs</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /_all_dbs</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /_all_dbs</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON list of DBs - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - Returns a list of all the databases in the CouchDB instance. For - example: - </para> - -<programlisting> -GET http://couchdb:5984/_all_dbs -Accept: application/json -</programlisting> - - <para> - The return is a JSON array: - </para> - -<programlisting> -[ - "_users", - "contacts", - "docs", - "invoices", - "locations" -] - -</programlisting> - - </section> - - <section id="couchdb-api-misc_log_get"> - - <title><literal>GET /_log</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API GET /_log</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /_log</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Log content - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>bytes</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Bytes to be returned - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>1000</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>offset</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Offset in bytes where the log tail should be started - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry></entry><entry><emphasis role="bold">Default</emphasis></entry><entry>0</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - Gets the CouchDB log, equivalent to accessing the local log file - of the corresponding CouchDB instance. - </para> - - <para> - When you request the log, the response is returned as plain - (UTF-8) text, with an HTTP <literal>Content-type</literal> header - as <literal>text/plain</literal>. - </para> - - <para> - For example, the request: - </para> - -<programlisting> -GET http://couchdb:5984/_log -Accept: */* -</programlisting> - - <para> - The raw text is returned: - </para> - -<programlisting> -<![CDATA[ -[Wed, 27 Oct 2010 10:49:42 GMT] [info] [<0.23338.2>] 192.168.0.2 - - 'PUT' /authdb 401 - -[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /recipes/FishStew 200 - -[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /_session 200 - -[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.24199.2>] 192.168.0.116 - - 'GET' / 200 - -[Wed, 27 Oct 2010 13:03:38 GMT] [info] [<0.24207.2>] 192.168.0.116 - - 'GET' /_log?offset=5 200 -]]> -</programlisting> - - <para> - If you want to pick out specific parts of the log information you - can use the <literal>bytes</literal> argument, which specifies the - number of bytes to be returned, and <literal>offset</literal>, - which specifies where the reading of the log should start, counted - back from the end. For example, if you use the following request: - </para> - -<programlisting> -GET /_log?bytes=500&offset=2000 -</programlisting> - - <para> - Reading of the log will start at 2000 bytes from the end of the - log, and 500 bytes will be shown. - </para> - - </section> - - <section id="couchdb-api-misc_replicate_post"> - - <title><literal>POST /_replicate</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<informaltable><textobject><phrase>URL API POST /_replicate</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /_replicate</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - Replication specification - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Welcome message and version - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Replication request successfully completed - </entry></row><row><entry>202</entry><entry namest="info" nameend="addinfo"> - Continuous replication request has been accepted - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - Either the source or target DB is not found - </entry></row><row><entry>500</entry><entry namest="info" nameend="addinfo"> - JSON specification was invalid - </entry></row></tbody></tgroup></informaltable> - - <para> - Request, configure, or stop, a replication operation. - </para> - - <para> - The specification of the replication request is controlled through - the JSON content of the request. The JSON should be an object with - the fields defining the source, target and other options. The - fields of the JSON request are shown in the table below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-misc-json-replication" class="jsonstructure"><title> - Replication Settings - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>cancel</literal> (optional) </entry><entry> - Cancels the replication - </entry></row><row><entry ><literal>continuous</literal> (optional) </entry><entry> - Configure the replication to be continuous - </entry></row><row><entry ><literal>create_target</literal> (optional) </entry><entry> - Creates the target database - </entry></row><row><entry ><literal>doc_ids</literal> (optional) </entry><entry> - Array of document IDs to be synchronized - </entry></row><row><entry ><literal>proxy</literal> (optional) </entry><entry> - Address of a proxy server through which replication should occur - </entry></row><row><entry ><literal>source</literal> </entry><entry> - Source database name or URL - </entry></row><row><entry ><literal>target</literal> </entry><entry> - Target database name or URL - </entry></row></tbody></tgroup></table> - - <section id="couchdb-api-misc_replicate_post-operation"> - - <title>Replication Operation</title> - - <para> - The aim of the replication is that at the end of the process, - all active documents on the source database are also in the - destination database and all documents that were deleted in the - source databases are also deleted (if they exist) on the - destination database. - </para> - - <para> - Replication can be described as either push or pull replication: - </para> - - <itemizedlist> - - <listitem> - <para> - <emphasis>Pull replication</emphasis> is where the - <literal>source</literal> is the remote CouchDB instance, - and the <literal>destination</literal> is the local - database. - </para> - - <para> - Pull replication is the most useful solution to use if your - source database has a permanent IP address, and your - destination (local) database may have a dynamically assigned - IP address (for example, through DHCP). This is particularly - important if you are replicating to a mobile or other device - from a central server. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Push replication</emphasis> is where the - <literal>source</literal> is a local database, and - <literal>destination</literal> is a remote database. - </para> - </listitem> - - </itemizedlist> - - </section> - - <section id="couchdb-api-misc_replicate_post-sourcetarget"> - - <title>Specifying the Source and Target Database</title> - - <para> - You must use the URL specification of the CouchDB database if - you want to perform replication in either of the following two - situations: - </para> - - <itemizedlist> - - <listitem> - <para> - Replication with a remote database (i.e. another instance of - CouchDB on the same host, or a different host) - </para> - </listitem> - - <listitem> - <para> - Replication with a database that requires authentication - </para> - </listitem> - - </itemizedlist> - - <para> - For example, to request replication between a database local to - the CouchDB instance to which you send the request, and a remote - database you might use the following request: - </para> - -<programlisting> -POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "source" : "recipes", - "target" : "http://coucdb-remote:5984/recipes", -} - </programlisting> - - <para> - In all cases, the requested databases in the - <literal>source</literal> and <literal>target</literal> - specification must exist. If they do not, an error will be - returned within the JSON object: - </para> - -<programlisting> -{ - "error" : "db_not_found" - "reason" : "could not open http://couchdb-remote:5984/ol1ka/", -} - </programlisting> - - <para> - You can create the target database (providing your user - credentials allow it) by adding the - <literal>create_target</literal> field to the request object: - </para> - -<programlisting> -POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "create_target" : true - "source" : "recipes", - "target" : "http://couchdb-remote:5984/recipes", -} -</programlisting> - - <para> - The <literal>create_target</literal> field is not destructive. - If the database already exists, the replication proceeds as - normal. - </para> - - </section> - - <section id="couchdb-api-misc_replicate_post-single"> - - <title>Single Replication</title> - - <para> - You can request replication of a database so that the two - databases can be synchronized. By default, the replication - process occurs one time and synchronizes the two databases - together. For example, you can request a single synchronization - between two databases by supplying the <literal>source</literal> - and <literal>target</literal> fields within the request JSON - content. - </para> - -<programlisting> -POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "source" : "recipes", - "target" : "recipes-snapshot", -} -</programlisting> - - <para> - In the above example, the databases <literal>recipes</literal> - and <literal>recipes-snapshot</literal> will be synchronized. - These databases are local to the CouchDB instance where the - request was made. The response will be a JSON structure - containing the success (or failure) of the synchronization - process, and statistics about the process: - </para> - -<programlisting> -{ - "ok" : true, - "history" : [ - { - "docs_read" : 1000, - "session_id" : "52c2370f5027043d286daca4de247db0", - "recorded_seq" : 1000, - "end_last_seq" : 1000, - "doc_write_failures" : 0, - "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT", - "start_last_seq" : 0, - "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT", - "missing_checked" : 0, - "docs_written" : 1000, - "missing_found" : 1000 - } - ], - "session_id" : "52c2370f5027043d286daca4de247db0", - "source_last_seq" : 1000 -} -</programlisting> - - <para> - The structure defines the replication status, as described in - the table below: - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//json/json.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/> -<table id="table-couchdb-api-misc-json-replication-status" class="jsonstructure"><title> - Replication Status - </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry ><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry ><literal>history</literal> <literal>[array]</literal> </entry><entry> - Replication History - </entry></row><row><entry > <literal>doc_write_failures</literal> </entry><entry> - Number of document write failures - </entry></row><row><entry > <literal>docs_read</literal> </entry><entry> - Number of documents read - </entry></row><row><entry > <literal>docs_written</literal> </entry><entry> - Number of documents written to target - </entry></row><row><entry > <literal>end_last_seq</literal> </entry><entry> - Last sequence number in changes stream - </entry></row><row><entry > <literal>end_time</literal> </entry><entry> - Date/Time replication operation completed - </entry></row><row><entry > <literal>missing_checked</literal> </entry><entry> - Number of missing documents checked - </entry></row><row><entry > <literal>missing_found</literal> </entry><entry> - Number of missing documents found - </entry></row><row><entry > <literal>recorded_seq</literal> </entry><entry> - Last recorded sequence number - </entry></row><row><entry > <literal>session_id</literal> </entry><entry> - Session ID for this replication operation - </entry></row><row><entry > <literal>start_last_seq</literal> </entry><entry> - First sequence number in changes stream - </entry></row><row><entry > <literal>start_time</literal> </entry><entry> - Date/Time replication operation started - </entry></row><row><entry ><literal>ok</literal> </entry><entry> - Replication status - </entry></row><row><entry ><literal>session_id</literal> </entry><entry> - Unique session ID - </entry></row><row><entry ><literal>source_last_seq</literal> </entry><entry> - Last sequence number read from source database - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-api-misc_replicate_post-continuous"> - - <title>Continuous Replication</title> - - <para> - Synchronization of a database with the previously noted methods - happens only once, at the time the replicate request is made. To - have the target database permanently replicated from the source, - you must set the <literal>continuous</literal> field of the JSON - object within the request to true. - </para> - - <para> - With continuous replication changes in the source database are - replicated to the target database in perpetuity until you - specifically request that replication ceases. - </para> - -<programlisting> -POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "continuous" : true - "source" : "recipes", - "target" : "http://couchdb-remote:5984/recipes", -} -</programlisting> - - <para> - Changes will be replicated between the two databases as long as - a network connection is available between the two instances. - </para> - - <note> - <para> - Two keep two databases synchronized with each other, you need - to set replication in both directions; that is, you must - replicate from <literal>databasea</literal> to - <literal>databaseb</literal>, and separately from - <literal>databaseb</literal> to <literal>databasea</literal>. - </para> - </note> - - </section> - - <section id="couchdb-api-misc_replicate_post-cancel"> - - <title>Canceling Continuous Replication</title> - - <para> - You can cancel continuous replication by adding the - <literal>cancel</literal> field to the JSON request object and - setting the value to true. Note that the structure of the - request must be identical to the original for the cancelation - request to be honoured. For example, if you requested continuous - replication, the cancellation request must also contain the - <literal>continuous</literal> field. - </para> - - <para> - For example, the replication request: - </para> - -<programlisting> -POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "source" : "recipes", - "target" : "http://couchdb-remote:5984/recipes", - "create_target" : true, - "continuous" : true -} -</programlisting> - - <para> - Must be canceled using the request: - </para> - -<programlisting> -POST http://couchdb:5984/_replicate -Content-Type: application/json -Accept: application/json - -{ - "cancel" : true, - "continuous" : true - "create_target" : true, - "source" : "recipes", - "target" : "http://couchdb-remote:5984/recipes", -} -</programlisting> - - <para> - Requesting cancellation of a replication that does not exist - results in a 404 error. - </para> - - </section> - - </section> - - <section id="couchdb-api-misc_restart_post"> - - <title><literal>POST /_restart</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API POST /_restart</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>POST /_restart</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - JSON status message - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">yes</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>201</entry><entry namest="info" nameend="addinfo"> - Document created successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - Restarts the CouchDB instance. You must be authenticated as a user - with administration privileges for this to work. - </para> - - <para> - For example: - </para> - -<programlisting> -POST http://admin:password@couchdb:5984/_restart -</programlisting> - - <para> - The return value (if the server has not already restarted) is a - JSON status object indicating that the request has been received: - </para> - -<programlisting> -{ - "ok" : true, -} -</programlisting> - - <para> - If the server has already restarted, the header may be returned, - but no actual data is contained in the response. - </para> - - </section> - - <section id="couchdb-api-misc_stats_get"> - - <title><literal>GET /_stats</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /_stats</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /_stats</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Server statistics - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - The <literal>_stats</literal> method returns a JSON object - containting the statistics for the running server. The object is - structured with top-level sections collating the statistics for a - range of entries, with each individual statistic being easily - identified, and the content of each statistic is self-describing. - For example, the request time statistics, within the - <literal>couchdb</literal> section are structured as follows: - </para> - -<programlisting> -{ - "couchdb" : { -... - "request_time" : { - "stddev" : "27.509", - "min" : "0.333333333333333", - "max" : "152", - "current" : "400.976", - "mean" : "10.837", - "sum" : "400.976", - "description" : "length of a request inside CouchDB without MochiWeb" - }, -... - } -} - </programlisting> - - <para> - The fields provide the current, minimum and maximum, and a - collection of statistical means and quantities. The quantity in - each case is not defined, but the descriptions below provide - </para> - - <para> - The statistics are divided into the following top-level sections: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>couchdb</literal> - </para> - - <para> - Describes statistics specific to the internals of CouchDB. - </para> - - <table> - <title><literal>couchdb</literal> statistics</title> - <tgroup cols="3"> - <colspec colname="stat"/> - <colspec colname="desc"/> - <colspec colname="unit"/> - <thead> - <row> - <entry> - Statistic ID - </entry> - <entry> - Description - </entry> - <entry> - Unit - </entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>auth_cache_hits</literal> - </entry> - <entry> - Number of authentication cache hits - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>auth_cache_misses</literal> - </entry> - <entry> - Number of authentication cache misses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>database_reads</literal> - </entry> - <entry> - Number of times a document was read from a database - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>database_writes</literal> - </entry> - <entry> - Number of times a database was changed - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>open_databases</literal> - </entry> - <entry> - Number of open databases - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>open_os_files</literal> - </entry> - <entry> - Number of file descriptors CouchDB has open - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>request_time</literal> - </entry> - <entry> - Length of a request inside CouchDB without MochiWeb - </entry> - <entry> - milliseconds - </entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - - <listitem> - <para> - <literal>httpd_request_methods</literal> - </para> - - <table> - <title><literal>httpd_request_methods</literal> statistics</title> - <tgroup cols="3"> - <colspec colname="stat"/> - <colspec colname="desc"/> - <colspec colname="unit"/> - <thead> - <row> - <entry> - Statistic ID - </entry> - <entry> - Description - </entry> - <entry> - Unit - </entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>COPY</literal> - </entry> - <entry> - Number of HTTP COPY requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>DELETE</literal> - </entry> - <entry> - Number of HTTP DELETE requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>GET</literal> - </entry> - <entry> - Number of HTTP GET requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>HEAD</literal> - </entry> - <entry> - Number of HTTP HEAD requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>POST</literal> - </entry> - <entry> - Number of HTTP POST requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>PUT</literal> - </entry> - <entry> - Number of HTTP PUT requests - </entry> - <entry> - number - </entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - - <listitem> - <para> - <literal>httpd_status_codes</literal> - </para> - - <table> - <title><literal>httpd_status_codes</literal> statistics</title> - <tgroup cols="3"> - <colspec colname="stat"/> - <colspec colname="desc"/> - <colspec colname="unit"/> - <thead> - <row> - <entry> - Statistic ID - </entry> - <entry> - Description - </entry> - <entry> - Unit - </entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>200</literal> - </entry> - <entry> - Number of HTTP 200 OK responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>201</literal> - </entry> - <entry> - Number of HTTP 201 Created responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>202</literal> - </entry> - <entry> - Number of HTTP 202 Accepted responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>301</literal> - </entry> - <entry> - Number of HTTP 301 Moved Permanently responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>304</literal> - </entry> - <entry> - Number of HTTP 304 Not Modified responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>400</literal> - </entry> - <entry> - Number of HTTP 400 Bad Request responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>401</literal> - </entry> - <entry> - Number of HTTP 401 Unauthorized responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>403</literal> - </entry> - <entry> - Number of HTTP 403 Forbidden responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>404</literal> - </entry> - <entry> - Number of HTTP 404 Not Found responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>405</literal> - </entry> - <entry> - Number of HTTP 405 Method Not Allowed responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>409</literal> - </entry> - <entry> - Number of HTTP 409 Conflict responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>412</literal> - </entry> - <entry> - Number of HTTP 412 Precondition Failed responses - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>500</literal> - </entry> - <entry> - Number of HTTP 500 Internal Server Error responses - </entry> - <entry> - number - </entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - - <listitem> - <para> - <literal>httpd</literal> - </para> - - <table> - <title><literal>httpd</literal> statistics</title> - <tgroup cols="3"> - <colspec colname="stat"/> - <colspec colname="desc"/> - <colspec colname="unit"/> - <thead> - <row> - <entry> - Statistic ID - </entry> - <entry> - Description - </entry> - <entry> - Unit - </entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>bulk_requests</literal> - </entry> - <entry> - Number of bulk requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>clients_requesting_changes</literal> - </entry> - <entry> - Number of clients for continuous _changes - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>requests</literal> - </entry> - <entry> - Number of HTTP requests - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>temporary_view_reads</literal> - </entry> - <entry> - Number of temporary view reads - </entry> - <entry> - number - </entry> - </row> - <row> - <entry><literal>view_reads</literal> - </entry> - <entry> - Number of view reads - </entry> - <entry> - number - </entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - - </itemizedlist> - - <para> - You can also access individual statistics by quoting the - statistics sections and statistic ID as part of the URL path. For - example, to get the <literal>request_time</literal> statistics, - you can use: - </para> - -<programlisting> -GET /_stats/couchdb/request_time - </programlisting> - - <para> - This returns an entire statistics object, as with the full - request, but containining only the request individual statistic. - Hence, the returned structure is as follows: - </para> - -<programlisting> -{ - "couchdb" : { - "request_time" : { - "stddev" : 7454.305, - "min" : 1, - "max" : 34185, - "current" : 34697.803, - "mean" : 1652.276, - "sum" : 34697.803, - "description" : "length of a request inside CouchDB without MochiWeb" - } - } -} - </programlisting> - - </section> - - <section id="couchdb-api-misc_utils_get"> - - <title><literal>GET /_utils</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /_utils</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /_utils</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Administration interface - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> - - <para> - Accesses the built-in Futon administration interface for CouchDB. - </para> - - </section> - - <section id="couchdb-api-misc_uuids_get"> - - <title><literal>GET /_uuids</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /_uuids</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /_uuids</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - List of UUIDs - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>count</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> - Number of UUIDs to return - </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>numeric</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row></tbody></tgroup></informaltable> - - <para> - Requests one or more Universally Unique Identifiers (UUIDs) from - the CouchDB instance. The response is a JSON object providing a - list of UUIDs. For example: - </para> - -<programlisting> -{ - "uuids" : [ - "7e4b5a14b22ec1cf8e58b9cdd0000da3" - ] -} -</programlisting> - - <para> - You can use the <literal>count</literal> argument to specify the - number of UUIDs to be returned. For example: - </para> - -<programlisting> - GET http://couchdb:5984/_uuids?count=5 -</programlisting> - - <para> - Returns: - </para> - -<programlisting> -{ - "uuids" : [ - "c9df0cdf4442f993fc5570225b405a80", - "c9df0cdf4442f993fc5570225b405bd2", - "c9df0cdf4442f993fc5570225b405e42", - "c9df0cdf4442f993fc5570225b4061a0", - "c9df0cdf4442f993fc5570225b406a20" - ] -} -</programlisting> - - <para> - The UUID type is determined by the UUID type setting in the - CouchDB configuration. See - <xref linkend="couchdb-api-config_config-section-key_put"/>. - </para> - - <para> - For example, changing the UUID type to <literal>random</literal>: - </para> - -<programlisting> -PUT http://couchdb:5984/_config/uuids/algorithm -Content-Type: application/json -Accept: */* - -"random" -</programlisting> - - <para> - When obtaining a list of UUIDs: - </para> - -<programlisting> -{ - "uuids" : [ - "031aad7b469956cf2826fcb2a9260492", - "6ec875e15e6b385120938df18ee8e496", - "cff9e881516483911aa2f0e98949092d", - "b89d37509d39dd712546f9510d4a9271", - "2e0dbf7f6c4ad716f21938a016e4e59f" - ] -} -</programlisting> - - </section> - - <section id="couchdb-api-misc_favicon_get"> - - <title><literal>GET /favicon.ico</literal></title> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<informaltable><textobject><phrase>URL API GET /favicon.ico</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /favicon.ico</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> - None - </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> - Binary content for the favicon.ico site icon - </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> - Request completed successfully. - </entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo"> - The requested content could not be found. The returned content - will include further information, as a JSON object, if available. - </entry></row></tbody></tgroup></informaltable> - - <para> - Returns the site icon. The return <literal>Content-type</literal> - header is <literal>image/x-icon</literal>, and the content stream - is the image data. - </para> - - </section> - -</chapter> diff --git a/share/docs/couchdb-manual-1.1/metadoc-couchdb-config-options.xml b/share/docs/couchdb-manual-1.1/metadoc-couchdb-config-options.xml deleted file mode 100644 index 177ab4181..000000000 --- a/share/docs/couchdb-manual-1.1/metadoc-couchdb-config-options.xml +++ /dev/null @@ -1,413 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE section PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<section id="couchdb-single-config-options"> - - <title>CouchDB Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="section"/><colspec colname="desc"/><thead><row><entry>Section</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>attachments</literal></entry><entry> - Attachment options - </entry></row><row><entry><literal>couchdb</literal></entry><entry> - CouchDB specific options - </entry></row><row><entry><literal>daemons</literal></entry><entry> - Daemons and background processes - </entry></row><row><entry><literal>httpd_db_handlers</literal></entry><entry> - Database Operation handlers - </entry></row><row><entry><literal>couch_httpd_auth</literal></entry><entry> - HTTPD Authentication options - </entry></row><row><entry><literal>httpd</literal></entry><entry> - HTTPD Server options - </entry></row><row><entry><literal>httpd_design_handlers</literal></entry><entry> - Handlers for design document operations - </entry></row><row><entry><literal>httpd_global_handlers</literal></entry><entry> - Handlers for global operations - </entry></row><row><entry><literal>log</literal></entry><entry> - Logging options - </entry></row><row><entry><literal>query_servers</literal></entry><entry> - Query Server options - </entry></row><row><entry><literal>query_server_config</literal></entry><entry> - Query server options - </entry></row><row><entry><literal>replicator</literal></entry><entry> - Replicator Options - </entry></row><row><entry><literal>ssl</literal></entry><entry> - SSL (Secure Sockets Layer) Options - </entry></row><row><entry><literal>stats</literal></entry><entry> - Statistics options - </entry></row><row><entry><literal>uuids</literal></entry><entry> - UUID generation options - </entry></row></tbody></tgroup></table> - - <section id="couchdb-single-config-options_attachments"> - - <title><literal>attachments</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-attachments-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>compressible_types</literal></entry><entry> - compressible_types - </entry></row><row><entry><literal>compression_level</literal></entry><entry> - compression_level - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_couchdb"> - - <title><literal>couchdb</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-couchdb-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>database_dir</literal></entry><entry> - database_dir - </entry></row><row><entry><literal>delayed_commits</literal></entry><entry> - delayed_commits - </entry></row><row><entry><literal>max_attachment_chunk_size</literal></entry><entry> - max_attachment_chunk_size - </entry></row><row><entry><literal>max_dbs_open</literal></entry><entry> - max_dbs_open - </entry></row><row><entry><literal>max_document_size</literal></entry><entry> - max_document_size - </entry></row><row><entry><literal>os_process_timeout</literal></entry><entry> - os_process_timeout - </entry></row><row><entry><literal>uri_file</literal></entry><entry> - uri_file - </entry></row><row><entry><literal>util_driver_dir</literal></entry><entry> - util_driver_dir - </entry></row><row><entry><literal>view_index_dir</literal></entry><entry> - view_index_dir - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_daemons"> - - <title><literal>daemons</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-daemons-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>httpsd</literal></entry><entry> - Enabled HTTPS service - </entry></row><row><entry><literal>auth_cache</literal></entry><entry> - auth_cache - </entry></row><row><entry><literal>db_update_notifier</literal></entry><entry> - db_update_notifier - </entry></row><row><entry><literal>external_manager</literal></entry><entry> - external_manager - </entry></row><row><entry><literal>httpd</literal></entry><entry> - httpd - </entry></row><row><entry><literal>query_servers</literal></entry><entry> - query_servers - </entry></row><row><entry><literal>stats_aggregator</literal></entry><entry> - stats_aggregator - </entry></row><row><entry><literal>stats_collector</literal></entry><entry> - stats_collector - </entry></row><row><entry><literal>uuids</literal></entry><entry> - uuids - </entry></row><row><entry><literal>view_manager</literal></entry><entry> - view_manager - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_httpd_db_handlers"> - - <title><literal>httpd_db_handlers</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-httpd_db_handlers-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>_changes</literal></entry><entry> - _changes - </entry></row><row><entry><literal>_compact</literal></entry><entry> - _compact - </entry></row><row><entry><literal>_design</literal></entry><entry> - _design - </entry></row><row><entry><literal>_temp_view</literal></entry><entry> - _temp_view - </entry></row><row><entry><literal>_view_cleanup</literal></entry><entry> - _view_cleanup - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_couch_httpd_auth"> - - <title><literal>couch_httpd_auth</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-couch_httpd_auth-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>auth_cache_size</literal></entry><entry> - auth_cache_size - </entry></row><row><entry><literal>authentication_db</literal></entry><entry> - authentication_db - </entry></row><row><entry><literal>authentication_redirect</literal></entry><entry> - authentication_redirect - </entry></row><row><entry><literal>require_valid_user</literal></entry><entry> - require_valid_user - </entry></row><row><entry><literal>timeout</literal></entry><entry> - timeout - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_httpd"> - - <title><literal>httpd</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-httpd-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>nodelay</literal></entry><entry> - Enable TCP_NODELAY - </entry></row><row><entry><literal>allow_jsonp</literal></entry><entry> - allow_jsonp - </entry></row><row><entry><literal>authentication_handlers</literal></entry><entry> - authentication_handlers - </entry></row><row><entry><literal>bind_address</literal></entry><entry> - bind_address - </entry></row><row><entry><literal>default_handler</literal></entry><entry> - default_handler - </entry></row><row><entry><literal>max_connections</literal></entry><entry> - max_connections - </entry></row><row><entry><literal>port</literal></entry><entry> - port - </entry></row><row><entry><literal>secure_rewrites</literal></entry><entry> - secure_rewrites - </entry></row><row><entry><literal>vhost_global_handlers</literal></entry><entry> - vhost_global_handlers - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_httpd_design_handlers"> - - <title><literal>httpd_design_handlers</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-httpd_design_handlers-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>_info</literal></entry><entry> - _info - </entry></row><row><entry><literal>_list</literal></entry><entry> - _list - </entry></row><row><entry><literal>_rewrite</literal></entry><entry> - _rewrite - </entry></row><row><entry><literal>_show</literal></entry><entry> - _show - </entry></row><row><entry><literal>_update</literal></entry><entry> - _update - </entry></row><row><entry><literal>_view</literal></entry><entry> - _view - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_httpd_global_handlers"> - - <title><literal>httpd_global_handlers</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-httpd_global_handlers-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>/</literal></entry><entry> - / - </entry></row><row><entry><literal>_active_tasks</literal></entry><entry> - _active_tasks - </entry></row><row><entry><literal>_all_dbs</literal></entry><entry> - _all_dbs - </entry></row><row><entry><literal>_config</literal></entry><entry> - _config - </entry></row><row><entry><literal>_log</literal></entry><entry> - _log - </entry></row><row><entry><literal>_oauth</literal></entry><entry> - _oauth - </entry></row><row><entry><literal>_replicate</literal></entry><entry> - _replicate - </entry></row><row><entry><literal>_restart</literal></entry><entry> - _restart - </entry></row><row><entry><literal>_session</literal></entry><entry> - _session - </entry></row><row><entry><literal>_stats</literal></entry><entry> - _stats - </entry></row><row><entry><literal>_utils</literal></entry><entry> - _utils - </entry></row><row><entry><literal>_uuids</literal></entry><entry> - _uuids - </entry></row><row><entry><literal>favicon.ico</literal></entry><entry> - favicon.ico - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_log"> - - <title><literal>log</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-log-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>file</literal></entry><entry> - file - </entry></row><row><entry><literal>include_sasl</literal></entry><entry> - include_sasl - </entry></row><row><entry><literal>level</literal></entry><entry> - level - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_query_servers"> - - <title><literal>query_servers</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-query_servers-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>javascript</literal></entry><entry> - javascript - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_query_server_config"> - - <title><literal>query_server_config</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-query_server_config-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>reduce_limit</literal></entry><entry> - reduce_limit - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_replicator"> - - <title><literal>replicator</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-replicator-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>max_http_pipeline_size</literal></entry><entry> - max_http_pipeline_size - </entry></row><row><entry><literal>max_http_sessions</literal></entry><entry> - max_http_sessions - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_stats"> - - <title><literal>stats</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-stats-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>rate</literal></entry><entry> - rate - </entry></row><row><entry><literal>samples</literal></entry><entry> - samples - </entry></row></tbody></tgroup></table> - - </section> - - <section id="couchdb-single-config-options_uuids"> - - <title><literal>uuids</literal> Configuration Options</title> - - <para> - - </para> - - <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/Config/Parser.pm"/> -<remark role="dependency-meta" condition="../metadocs//config/couchdb.xml"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/Config.pm"/> -<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> -<table id="table-couchdb-single-config-options-uuids-summary"><title>Configuration Groups</title><tgroup cols="2"><colspec colname="option"/><colspec colname="desc"/><thead><row><entry>Option</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>algorithm</literal></entry><entry> - algorithm - </entry></row></tbody></tgroup></table> - - </section> - -</section> diff --git a/share/docs/couchdb-release-1.1/couchdb-release-1.1-ready.xml b/share/docs/couchdb-release-1.1/couchdb-release-1.1-ready.xml deleted file mode 100644 index 208b9787a..000000000 --- a/share/docs/couchdb-release-1.1/couchdb-release-1.1-ready.xml +++ /dev/null @@ -1,1154 +0,0 @@ -<?xml version="1.0" encoding="utf-8" standalone="no"?> -<article id="couchdb-release-1.1"> - - <title>CouchDB Release 1.1 Feature Guide</title> - - <articleinfo> - - <abstract> - - <para> - This document provides details on the new features introduced in - the CouchDB 1.1 release from the CouchDB 1.0.x release series. - </para> - - <para xml:base="../common/docbuilddate.xml"> - <emphasis>Last document update</emphasis>: 25 Jan 2012 14:44; - <emphasis>Document built</emphasis>: 21 Feb 2012 20:8. -</para> - - </abstract> - - </articleinfo> - - <section id="couchdb-release-1.1-upgrading"> - - <title>Upgrading to CouchDB 1.1</title> - - <para> - You can upgrade your existing CouchDB 1.0.x installation to - CouchDB 1.1 without any specific steps or migration. When you run - CouchDB 1.1 the existing data and index files will be opened and - used as normal. - </para> - - <para> - The first time you run a compaction routine on your database - within CouchDB 1.1, the data structure and indexes will be updated - to the new version of the CouchDB database format that can only be - read by CouchDB 1.1 and later. This step is not reversable. Once - the data files have been updated and migrated to the new version - the data files will no longer work with a CouchDB 1.0.x release. - </para> - - <warning> - <para> - If you want to retain support for openein gthe data files in - CouchDB 1.0.x you must back up your data files before performing - the upgrade and compaction process. - </para> - </warning> - - </section> - - <section id="couchb-release-1.1-replicatordb"> - - <title>Replicator Database</title> - - <para> - A database where you - <literal>PUT</literal>/<literal>POST</literal> documents to - trigger replications and you <literal>DELETE</literal> to cancel - ongoing replications. These documents have exactly the same - content as the JSON objects we used to <literal>POST</literal> to - <literal>_replicate</literal> (fields <literal>source</literal>, - <literal>target</literal>, <literal>create_target</literal>, - <literal>continuous</literal>, <literal>doc_ids</literal>, - <literal>filter</literal>, <literal>query_params</literal>. - </para> - - <para> - Replication documents can have a user defined - <literal>_id</literal>. Design documents (and - <literal>_local</literal> documents) added to the replicator - database are ignored. - </para> - - <para> - The default name of this database is - <literal>_replicator</literal>. The name can be changed in the - <filename>local.ini</filename> configuration, section - <literal>[replicator]</literal>, parameter <literal>db</literal>. - </para> - - <section id="couchdb-release-1.1-replicatordb-basics"> - - <title>Basics</title> - - <para> - Let's say you PUT the following document into _replicator: - </para> - -<programlisting>{ - "_id": "my_rep", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "create_target": true -}</programlisting> - - <para> - In the couch log you'll see 2 entries like these: - </para> - -<programlisting>[Thu, 17 Feb 2011 19:43:59 GMT] [info] [<0.291.0>] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target` -[Thu, 17 Feb 2011 19:44:37 GMT] [info] [<0.124.0>] Replication `c0ebe9256695ff083347cbf95f93e280+create_target` finished (triggered by document `my_rep`)</programlisting> - - <para> - As soon as the replication is triggered, the document will be - updated by CouchDB with 3 new fields: - </para> - -<programlisting>{ - "_id": "my_rep", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "create_target": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -}</programlisting> - - <para> - Special fields set by the replicator start with the prefix - <literal>_replication_</literal>. - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>_replication_id</literal> - </para> - - <para> - The ID internally assigned to the replication. This is also - the ID exposed by <literal>/_active_tasks</literal>. - </para> - </listitem> - - <listitem> - <para> - <literal>_replication_state</literal> - </para> - - <para> - The current state of the replication. - </para> - </listitem> - - <listitem> - <para> - <literal>_replication_state_time</literal> - </para> - - <para> - A Unix timestamp (number of seconds since 1 Jan 1970) that - tells us when the current replication state (marked in - <literal>_replication_state</literal>) was set. - </para> - </listitem> - - </itemizedlist> - - <para> - When the replication finishes, it will update the - <literal>_replication_state</literal> field (and - <literal>_replication_state_time</literal>) with the value - <literal>completed</literal>, so the document will look like: - </para> - -<programlisting>{ - "_id": "my_rep", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "create_target": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "completed", - "_replication_state_time": 1297974122 -}</programlisting> - - <para> - When an error happens during replication, the - <literal>_replication_state</literal> field is set to - <literal>error</literal> (and - <literal>_replication_state</literal> gets updated of course). - </para> - - <para> - When you PUT/POST a document to the - <literal>_replicator</literal> database, CouchDB will attempt to - start the replication up to 10 times (configurable under - <literal>[replicator]</literal>, parameter - <literal>max_replication_retry_count</literal>). If it fails on - the first attempt, it waits 5 seconds before doing a second - attempt. If the second attempt fails, it waits 10 seconds before - doing a third attempt. If the third attempt fails, it waits 20 - seconds before doing a fourth attempt (each attempt doubles the - previous wait period). When an attempt fails, the Couch log will - show you something like: - </para> - -<programlisting>[error] [<0.149.0>] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,<<"could not open http://myserver:5986/foo/">></programlisting> - - <note> - <para> - The <literal>_replication_state</literal> field is only set to - <literal>error</literal> when all the attempts were - unsuccessful. - </para> - </note> - - <para> - There are only 3 possible values for the - <literal>_replication_state</literal> field: - <literal>triggered</literal>, <literal>completed</literal> and - <literal>error</literal>. Continuous replications never get - their state set to <literal>completed</literal>. - </para> - - </section> - - <section id="couchdb-release-1.1-replicatordb-docsame"> - - <title>Documents describing the same replication</title> - - <para> - Lets suppose 2 documents are added to the - <literal>_replicator</literal> database in the following order: - </para> - -<programlisting>{ - "_id": "doc_A", - "source": "http://myserver.com:5984/foo", - "target": "bar" -}</programlisting> - - <para> - and - </para> - -<programlisting>{ - "_id": "doc_B", - "source": "http://myserver.com:5984/foo", - "target": "bar" -}</programlisting> - - <para> - Both describe exactly the same replication (only their - <literal>_ids</literal> differ). In this case document - <literal>doc_A</literal> triggers the replication, getting - updated by CouchDB with the fields - <literal>_replication_state</literal>, - <literal>_replication_state_time</literal> and - <literal>_replication_id</literal>, just like it was described - before. Document <literal>doc_B</literal> however, is only - updated with one field, the <literal>_replication_id</literal> - so it will look like this: - </para> - -<programlisting>{ - "_id": "doc_B", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "_replication_id": "c0ebe9256695ff083347cbf95f93e280" -}</programlisting> - - <para> - While document <literal>doc_A</literal> will look like this: - </para> - -<programlisting>{ - "_id": "doc_A", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -}</programlisting> - - <para> - Note that both document get exactly the same value for the - <literal>_replication_id</literal> field. This way you can - identify which documents refer to the same replication - you can - for example define a view which maps replication IDs to document - IDs. - </para> - - </section> - - <section id="couchdb-release-1.1-replicatordb-cancel"> - - <title>Canceling replications</title> - - <para> - To cancel a replication simply <literal>DELETE</literal> the - document which triggered the replication. The Couch log will - show you an entry like the following: - </para> - -<programlisting>[Thu, 17 Feb 2011 20:16:29 GMT] [info] [<0.125.0>] Stopped replication `c0ebe9256695ff083347cbf95f93e280+continuous+create_target` because replication document `doc_A` was deleted</programlisting> - - <note> - <para> - You need to <literal>DELETE</literal> the document that - triggered the replication. <literal>DELETE</literal>ing - another document that describes the same replication but did - not trigger it, will not cancel the replication. - </para> - </note> - - </section> - - <section id="couchdb-release-1.1-replicatordb-restart"> - - <title>Server restart</title> - - <para> - When CouchDB is restarted, it checks its - <literal>_replicator</literal> database and restarts any - replication that is described by a document that either has its - <literal>_replication_state</literal> field set to - <literal>triggered</literal> or it doesn't have yet the - <literal>_replication_state</literal> field set. - </para> - - <note> - <para> - Continuous replications always have a - <literal>_replication_state</literal> field with the value - <literal>triggered</literal>, therefore they're always - restarted when CouchDB is restarted. - </para> - </note> - - </section> - - <section id="couchdb-release-1.1-replicatordb-changing"> - - <title>Changing the Replicator Database</title> - - <para> - Imagine your replicator database (default name is _replicator) - has the two following documents that represent pull replications - from servers A and B: - </para> - -<programlisting>{ - "_id": "rep_from_A", - "source": "http://aserver.com:5984/foo", - "target": "foo_a", - "continuous": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297971311 -} -{ - "_id": "rep_from_B", - "source": "http://bserver.com:5984/foo", - "target": "foo_b", - "continuous": true, - "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -}</programlisting> - - <para> - Now without stopping and restarting CouchDB, you change the name - of the replicator database to - <literal>another_replicator_db</literal>: - </para> - -<programlisting>$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"' -"_replicator"</programlisting> - - <para> - As soon as this is done, both pull replications defined before, - are stopped. This is explicitly mentioned in CouchDB's log: - </para> - -<programlisting>[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.104.0>] Stopping all ongoing replications because the replicator database was deleted or changed -[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.127.0>] 127.0.0.1 - - PUT /_config/replicator/db 200</programlisting> - - <para> - Imagine now you add a replication document to the new replicator - database named <literal>another_replicator_db</literal>: - </para> - -<programlisting>{ - "_id": "rep_from_X", - "source": "http://xserver.com:5984/foo", - "target": "foo_x", - "continuous": true -}</programlisting> - - <para> - From now own you have a single replication going on in your - system: a pull replication pulling from server X. Now you change - back the replicator database to the original one - <literal>_replicator</literal>: - </para> - -<programlisting>$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"' -"another_replicator_db"</programlisting> - - <para> - Immediately after this operation, the replication pulling from - server X will be stopped and the replications defined in the - _replicator database (pulling from servers A and B) will be - resumed. - </para> - - <para> - Changing again the replicator database to - <literal>another_replicator_db</literal> will stop the pull - replications pulling from servers A and B, and resume the pull - replication pulling from server X. - </para> - - </section> - - <section id="couchdb-release-1.1-replicatordb-replicating"> - - <title>Replicating the replicator database</title> - - <para> - Imagine you have in server C a replicator database with the two - following pull replication documents in it: - </para> - -<programlisting>{ - "_id": "rep_from_A", - "source": "http://aserver.com:5984/foo", - "target": "foo_a", - "continuous": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297971311 -} -{ - "_id": "rep_from_B", - "source": "http://bserver.com:5984/foo", - "target": "foo_b", - "continuous": true, - "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -}</programlisting> - - <para> - Now you would like to have the same pull replications going on - in server D, that is, you would like to have server D pull - replicating from servers A and B. You have two options: - </para> - - <itemizedlist> - - <listitem> - <para> - Explicitly add two documents to server's D replicator - database - </para> - </listitem> - - <listitem> - <para> - Replicate server's C replicator database into server's D - replicator database - </para> - </listitem> - - </itemizedlist> - - <para> - Both alternatives accomplish exactly the same goal. - </para> - - </section> - - <section id="couchdb-release-1.1-replicatordb-delegations"> - - <title>Delegations</title> - - <para> - Replication documents can have a custom - <literal>user_ctx</literal> property. This property defines the - user context under which a replication runs. For the old way of - triggering replications (POSTing to - <literal>/_replicate/</literal>), this property was not needed - (it didn't exist in fact) - this is because at the moment of - triggering the replication it has information about the - authenticated user. With the replicator database, since it's a - regular database, the information about the authenticated user - is only present at the moment the replication document is - written to the database - the replicator database implementation - is like a _changes feed consumer (with - <literal>?include_docs=true</literal>) that reacts to what was - written to the replicator database - in fact this feature could - be implemented with an external script/program. This - implementation detail implies that for non admin users, a - <literal>user_ctx</literal> property, containing the user's name - and a subset of his/her roles, must be defined in the - replication document. This is ensured by the document update - validation function present in the default design document of - the replicator database. This validation function also ensure - that a non admin user can set a user name property in the - <literal>user_ctx</literal> property that doesn't match his/her - own name (same principle applies for the roles). - </para> - - <para> - For admins, the <literal>user_ctx</literal> property is - optional, and if it's missing it defaults to a user context with - name null and an empty list of roles - this mean design - documents will not be written to local targets. If writing - design documents to local targets is desired, the a user context - with the roles <literal>_admin</literal> must be set explicitly. - </para> - - <para> - Also, for admins the <literal>user_ctx</literal> property can be - used to trigger a replication on behalf of another user. This is - the user context that will be passed to local target database - document validation functions. - </para> - - <note> - <para> - The <literal>user_ctx</literal> property only has effect for - local endpoints. - </para> - </note> - - <para> - Example delegated replication document: - </para> - -<programlisting>{ - "_id": "my_rep", - "source": "http://bserver.com:5984/foo", - "target": "bar", - "continuous": true, - "user_ctx": { - "name": "joe", - "roles": ["erlanger", "researcher"] - } -}</programlisting> - - <para> - As stated before, for admins the user_ctx property is optional, - while for regular (non admin) users it's mandatory. When the - roles property of <literal>user_ctx</literal> is missing, it - defaults to the empty list <literal>[ ]</literal>. - </para> - - </section> - - </section> - - <section id="couchdb-release-1.1-ssl"> - - <title>Native SSL Support</title> - - <para> - CouchDB 1.1 supports SSL natively. All your secure connection - needs can now be served without the need set and maintain a - separate proxy server that handles SSL. - </para> - - <para> - SSL setup can be tricky, but the configuration in CouchDB was - designed to be as easy as possible. All you need is two files; a - certificate and a private key. If you bought an official SSL - certificate from a certificate authority, both should be in your - possession already. - </para> - - <para> - If you just want to try this out and don't want to pay anything - upfront, you can create a self-signed certificate. Everything will - work the same, but clients will get a warning about an insecure - certificate. - </para> - - <para> - You will need the OpenSSL command line tool installed. It probably - already is. - </para> - -<programlisting>shell> <userinput>mkdir cert && cd cert</userinput> -shell> <userinput>openssl genrsa > privkey.pem</userinput> -shell> <userinput>openssl req -new -x509 -key privkey.pem -out mycert.pem -days 1095</userinput> -shell> <userinput>ls</userinput> -mycert.pem privkey.pem</programlisting> - - <para> - Now, you need to edit CouchDB's configuration, either by editing - your <filename>local.ini</filename> file or using the - <literal>/_config</literal> API calls or the configuration screen - in Futon. Here is what you need to do in - <filename>local.ini</filename>, you can infer what needs doing in - the other places. - </para> - - <para> - Be sure to make these edits. Under <literal>[daemons]</literal> - you should see: - </para> - -<programlisting>; enable SSL support by uncommenting the following line and supply the PEM's below. -; the default ssl port CouchDB listens on is 6984 -;httpsd = {couch_httpd, start_link, [https]}</programlisting> - - <para> - Here uncomment the last line: - </para> - -<programlisting>httpsd = {couch_httpd, start_link, [https]}</programlisting> - - <para> - Next, under <literal>[ssl]</literal> you will see: - </para> - -<programlisting>;cert_file = /full/path/to/server_cert.pem -;key_file = /full/path/to/server_key.pem</programlisting> - - <para> - Uncomment and adjust the paths so it matches your system's paths: - </para> - -<programlisting>cert_file = /home/jan/cert/mycert.pem -key_file = /home/jan/cert/privkey.pem</programlisting> - - <para> - For more information please read - <ulink url="http://www.openssl.org/docs/HOWTO/certificates.txt">http://www.openssl.org/docs/HOWTO/certificates.txt</ulink>. - </para> - - <para> - Now start (or restart) CouchDB. You should be able to connect to - it using HTTPS on port 6984: - </para> - -<programlisting>shell> <userinput>curl https://127.0.0.1:6984/</userinput> -curl: (60) SSL certificate problem, verify that the CA cert is OK. Details: -error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed -More details here: http://curl.haxx.se/docs/sslcerts.html - -curl performs SSL certificate verification by default, using a "bundle" -of Certificate Authority (CA) public keys (CA certs). If the default -bundle file isn't adequate, you can specify an alternate file -using the --cacert option. -If this HTTPS server uses a certificate signed by a CA represented in -the bundle, the certificate verification probably failed due to a -problem with the certificate (it might be expired, or the name might -not match the domain name in the URL). -If you'd like to turn off curl's verification of the certificate, use -the -k (or --insecure) option.</programlisting> - - <para> - Oh no what happened?! — Remember, clients will notify their - users that your certificate is self signed. - <command>curl</command> is the client in this case and it notifies - you. Luckily you trust yourself (don't you?) and you can specify - the <option>-k</option> option as the message reads: - </para> - -<programlisting>shell> <userinput>curl -k https://127.0.0.1:6984/</userinput> -{"couchdb":"Welcome","version":"1.1.0"}</programlisting> - - <para> - All done. - </para> - - </section> - - <section id="couchdb-release-1.1-httprange"> - - <title>HTTP Range Requests</title> - - <para> - HTTP allows you to specify byte ranges for requests. This allows - the implementation of resumable downloads and skippable audio and - video streams alike. Now this is available for all attachments - inside CouchDB. - </para> - - <para> - This is just a real quick run through how this looks under the - hood. Usually, you will have larger binary files to serve from - CouchDB, like MP3s and videos, but to make things a little more - obvious, I use a text file here (Note that I use the - <literal>application/octet-stream</literal> Content-Type instead - of <literal>text/plain</literal>). - </para> - -<programlisting>shell> <userinput>cat file.txt </userinput> -My hovercraft is full of eels!</programlisting> - - <para> - Now lets store this text file as an attachment in CouchDB. First, - we create a database: - </para> - -<programlisting>shell> <userinput>curl -X PUT http://127.0.0.1:5984/test</userinput> -{"ok":true}</programlisting> - - <para> - Then we create a new document and the file attachment in one go: - </para> - -<programlisting>shell> <userinput>curl -X PUT http://127.0.0.1:5984/test/doc/file.txt -H "Content-Type: application/octet-stream" -d@file.txt</userinput> -{"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}</programlisting> - - <para> - Now we can request the whole file easily: - </para> - -<programlisting>shell> <userinput>curl -X GET http://127.0.0.1:5984/test/doc/file.txt</userinput> -My hovercraft is full of eels!</programlisting> - - <para> - But say we only want the first 13 bytes: - </para> - -<programlisting>shell> <userinput>curl -X GET http://127.0.0.1:5984/test/doc/file.txt -H "Range: bytes=0-12"</userinput> -My hovercraft</programlisting> - - <para> - HTTP supports many ways to specify single and even multiple byte - rangers. Read all about it in - <ulink url="http://tools.ietf.org/html/rfc2616#section-14.27">RFC - 2616</ulink>. - </para> - - <note> - <para> - Databases that have been created with CouchDB 1.0.2 or earlier - will support range requests in 1.1.0, but they are using a - less-optimal algorithm. If you plan to make heavy use of this - feature, make sure to compact your database with CouchDB 1.1.0 - to take advantage of a better algorithm to find byte ranges. - </para> - </note> - - </section> - - <section id="couchdb-release-1.1-proxying"> - - <title>HTTP Proxying</title> - - <para> - The HTTP proxy feature makes it easy to map and redirect different - content through your CouchDB URL. The proxy works by mapping a - pathname and passing all content after that prefix through to the - configured proxy address. - </para> - - <para> - Configuration of the proxy redirect is handled through the - <literal>[httpd_global_handlers]</literal> section of the CouchDB - configuration file (typically <filename>local.ini</filename>). The - format is: - </para> - -<programlisting>[httpd_global_handlers] -PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>}</programlisting> - - <para> - Where: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>PREFIX</literal> - </para> - - <para> - Is the string that will be matched. The string can be any - valid qualifier, although to ensure that existing database - names are not overridden by a proxy configuration, you can use - an underscore prefix. - </para> - </listitem> - - <listitem> - <para> - <literal>DESTINATION</literal> - </para> - - <para> - The fully-qualified URL to which the request should be sent. - The destination must include the <literal>http</literal> - prefix. The content is used verbatim in the original request, - so you can also forward to servers on different ports and to - specific paths on the target host. - </para> - </listitem> - - </itemizedlist> - - <para> - The proxy process then translates requests of the form: - </para> - -<programlisting>http://couchdb:5984/PREFIX/path</programlisting> - - <para> - To: - </para> - -<programlisting>DESTINATION/path</programlisting> - - <note> - <para> - Everything after <literal>PREFIX</literal> including the - required forward slash will be appended to the - <literal>DESTINATION</literal>. - </para> - </note> - - <para> - The response is then communicated back to the original client. - </para> - - <para> - For example, the following configuration: - </para> - -<programlisting>_google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>}</programlisting> - - <para> - Would forward all requests for - <literal>http://couchdb:5984/_google</literal> to the Google - website. - </para> - - <para> - The service can also be used to forward to related CouchDB - services, such as Lucene: - </para> - -<programlisting>[httpd_global_handlers] -_fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}</programlisting> - - <note> - <para> - The proxy service is basic. If the request is not identified by - the <literal>DESTINATION</literal>, or the remainder of the - <literal>PATH</literal> specification is incomplete, the - original request URL is interpreted as if the - <literal>PREFIX</literal> component of that URL does not exist. - </para> - - <para> - For example, requesting - <literal>http://couchdb:5984/_intranet/media</literal> when - <filename>/media</filename> on the proxy destination does not - exist, will cause the request URL to be interpreted as - <literal>http://couchdb:5984/media</literal>. Care should be - taken to ensure that both requested URLs and destination URLs - are able to cope - </para> - </note> - - </section> - - <section id="couchdb-release-1.1-commonjs"> - - <title>Added CommonJS support to map functions</title> - - <para> - We didn't have CommonJS require in map functions because the - current CommonJS implementation is scoped to the whole design doc, - and giving views access to load code from anywhere in the design - doc would mean we'd have to blow away your view index any time you - changed anything. Having to rebuild views from scratch just - because you changed some CSS or a show function isn't fun, so we - avoided the issue by keeping CommonJS require out of map and - reduce altogether. - </para> - - <para> - The solution we came up with is to allow CommonJS inside map and - reduce funs, but only of libraries that are stored inside the - views part of the design doc. - </para> - - <para> - So you could continue to access CommonJS code in design_doc.foo, - from your list functions etc, but we'd add the ability to require - CommonJS modules within map and reduce, but only from - design_doc.views.lib - </para> - - <para> - There's no worry here about namespace collisions, as Couch just - plucks <literal>views.*.map</literal> and - <literal>views.*.reduce</literal> out of the design doc. So you - could have a view called <literal>lib</literal> if you wanted, and - still have CommonJS stored in <literal>views.lib.sha1</literal> - and <literal>views.lib.stemmer</literal> if you wanted. - </para> - - <para> - We simplified the implementation by enforcing that CommonJS - modules to be used in map functions be stored in views.lib. - </para> - - <para> - A sample design doc (taken from the test suite in Futon) is below: - </para> - -<programlisting>{ - "views" : { - "lib" : { - "baz" : "exports.baz = 'bam';", - "foo" : { - "zoom" : "exports.zoom = 'yeah';", - "boom" : "exports.boom = 'ok';", - "foo" : "exports.foo = 'bar';" - } - }, - "commonjs" : { - "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}" - } - }, - "_id" : "_design/test" -}</programlisting> - - <para> - The <literal>require()</literal> statement is relative to the - design document, but anything loaded form outside of - <literal>views/lib</literal> will fail. - </para> - - </section> - - <section id="couchdb-release-1.1-etag"> - - <title>More granular ETag support for views</title> - - <para> - ETags have been assigned to a map/reduce group (the collection of - views in a single design document). Any change to any of the - indexes for those views would generate a new ETag for all view - URL's in a single design doc, even if that specific view's results - had not changed. - </para> - - <para> - In CouchDB 1.1 each <literal>_view</literal> URL has it's own ETag - which only gets updated when changes are made to the database that - effect that index. If the index for that specific view does not - change, that view keeps the original ETag head (therefore sending - back 304 Not Modified more often). - </para> - - </section> - - <section id="couchdb-release-1.1-filters"> - - <title>Added built-in filters for <literal>_changes</literal>: - <literal>_doc_ids</literal> and <literal>_design</literal>.</title> - - <para> - The <literal>_changes</literal> feed can now be used to watch - changes to specific document ID's or the list of - <literal>_design</literal> documents in a database. If the - <literal>filters</literal> parameter is set to - <literal>_doc_ids</literal> a list of doc IDs can be passed in the - "doc_ids" as a JSON array. - </para> - - </section> - - <section id="couchdb-release-1.1-wildcards"> - - <title>Allow wildcards in vhosts definitions</title> - - <para> - Similar to the rewrites section of a <literal>_design</literal> - document, the new <literal>vhosts</literal> system uses variables - in the form of :varname or wildcards in the form of asterisks. The - variable results can be output into the resulting path as they are - in the rewriter. - </para> - - </section> - - <section id="couchdb-release-1.1-osprocess"> - - <title>OS Daemons</title> - - <para> - CouchDB now supports starting external processes. The support is - simple and enables CouchDB to start each configured OS daemon. If - the daemon stops at any point, CouchDB will restart it (with - protection to ensure regularly failing daemons are not repeatedly - restarted). - </para> - - <para> - The daemon starting process is one-to-one; for each each - configured daemon in the configuration file, CouchDB will start - exactly one instance. If you need to run multiple instances, then - you must create separate individual configurations. Daemons are - configured within the <literal>[os_daemons]</literal> section of - your configuration file (<filename>local.ini</filename>). The - format of each configured daemon is: - </para> - -<programlisting>NAME = PATH ARGS</programlisting> - - <para> - Where <literal>NAME</literal> is an arbitrary (and unique) name to - identify the daemon; <literal>PATH</literal> is the full path to - the daemon to be executed; <literal>ARGS</literal> are any - required arguments to the daemon. - </para> - - <para> - For example: - </para> - -<programlisting>[os_daemons] -basic_responder = /usr/local/bin/responsder.js</programlisting> - - <para> - There is no interactivity between CouchDB and the running process, - but you can use the OS Daemons service to create new HTTP servers - and responders and then use the new proxy service to redirect - requests and output to the CouchDB managed service. For more - information on proxying, see - <xref linkend="couchdb-release-1.1-proxying"/>. For further - background on the OS Daemon service, see - <ulink url="http://davispj.com/2010/09/26/new-couchdb-externals-api.html">CouchDB - Externals API</ulink> - </para> - - </section> - - <section id="coudhdb-release-1.1-updateafter"> - - <title>Stale views and <literal>update_after</literal></title> - - <para> - Currently a view request can include the - <literal>stale=ok</literal> query argument, which allows the - contents of a stale view index to be used to produce the view - output. In order to trigger a build of the outdated view index, a - second view request must be made. - </para> - - <para> - To simplify this process, the <literal>update_after</literal> - value can be supplied to the <literal>stale</literal> query - argument. This triggers a rebuild of the view index after the - results of the view have been retrieved. - </para> - - </section> - - <section id="couchdb-release-1.1-socketoptions"> - - <title>Socket Options Configuration Setting</title> - - <para> - The socket options for the listening socket in CouchDB can now be - set within the CouchDB configuration file. The setting should be - added to the <literal>[httpd]</literal> section of the file using - the option name <literal>socket_options</literal>. The - specification is as a list of tuples. For example: - </para> - -<programlisting>[httpd] -socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}]</programlisting> - - <para> - The options supported are a subset of full options supported by - the TCP/IP stack. A list of the supported options are provided in - the - <ulink url="http://www.erlang.org/doc/man/inet.html#setopts-2">Erlang - inet</ulink> documentation. - </para> - - </section> - - <section id="couchdb-release-1.1-serveroptions"> - - <title>Server Options Configuration Setting</title> - - <para> - Server options for the MochiWeb component of CouchDB can now be - added to the configuration file. Settings should be added to the - <literal>server_options</literal> option of the - <literal>[httpd]</literal> section of - <filename>local.ini</filename>. For example: - </para> - -<programlisting>[httpd] -server_options = [{backlog, 128}, {acceptor_pool_size, 16}]</programlisting> - - </section> - - <section id="couchdb-release-1.1-errormessages"> - - <title>Improved Error Messages</title> - - <para> - The errors reported when CouchDB is unable to read a required file - have been updated so that explicit information about the files and - problem can now be identified from the error message. The errors - report file permission access either when reading or writing to - configuration and database files. - </para> - - <para> - The error is raised both through the log file and the error - message returned through the API call as a JSON error message. For - example, when setting configuration values: - </para> - -<programlisting>shell> <userinput>curl -H 'X-Couch-Persist: true' -X PUT http://couchdb:5984/_config/couchdb/delayed_commits -d '"false"'</userinput> -{"error":"file_permission_error","reason":"/etc/couchdb/local.ini"}</programlisting> - - <para> - Errors will always be reported using the - <literal>file_permission_error</literal> error type. - </para> - - <para> - During startup permissions errors on key files are also reported - in the log with a descriptive error message and file location so - that permissions can be fixed before restart. - </para> - - </section> - - <section id="couchdb-release-1.1-microoptimizations"> - - <title>Multiple micro-optimizations when reading data.</title> - - <para> - We found a number of places where CouchDB wouldn't do the absolute - optimal thing when reading data and got rid of quite a few - inefficiencies. The problem with small optimizations all over the - place is that you may not notice them with every use-case, but we - sure hope you can see an improvement overall. - </para> - - </section> - -</article> diff --git a/share/docs/couchdb-release-1.1/couchdb-release-1.1.xml b/share/docs/couchdb-release-1.1/couchdb-release-1.1.xml deleted file mode 100644 index e70142adc..000000000 --- a/share/docs/couchdb-release-1.1/couchdb-release-1.1.xml +++ /dev/null @@ -1,1243 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' - 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ -<!ENTITY % every.entities SYSTEM "entities.ent"> -%every.entities; -]> -<article id="couchdb-release-1.1"> - - <title>CouchDB Release 1.1 Feature Guide</title> - - <articleinfo> - - <abstract> - - <para> - This document provides details on the new features introduced in - the CouchDB 1.1 release from the CouchDB 1.0.x release series. - </para> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../common/docbuilddate.xml"/> - - </abstract> - - </articleinfo> - - <section id="couchdb-release-1.1-upgrading"> - - <title>Upgrading to CouchDB 1.1</title> - - <para> - You can upgrade your existing CouchDB 1.0.x installation to - CouchDB 1.1 without any specific steps or migration. When you run - CouchDB 1.1 the existing data and index files will be opened and - used as normal. - </para> - - <para> - The first time you run a compaction routine on your database - within CouchDB 1.1, the data structure and indexes will be updated - to the new version of the CouchDB database format that can only be - read by CouchDB 1.1 and later. This step is not reversable. Once - the data files have been updated and migrated to the new version - the data files will no longer work with a CouchDB 1.0.x release. - </para> - - <warning> - <para> - If you want to retain support for openein gthe data files in - CouchDB 1.0.x you must back up your data files before performing - the upgrade and compaction process. - </para> - </warning> - - </section> - - <section id="couchb-release-1.1-replicatordb"> - - <title>Replicator Database</title> - - <para> - A database where you - <literal>PUT</literal>/<literal>POST</literal> documents to - trigger replications and you <literal>DELETE</literal> to cancel - ongoing replications. These documents have exactly the same - content as the JSON objects we used to <literal>POST</literal> to - <literal>_replicate</literal> (fields <literal>source</literal>, - <literal>target</literal>, <literal>create_target</literal>, - <literal>continuous</literal>, <literal>doc_ids</literal>, - <literal>filter</literal>, <literal>query_params</literal>. - </para> - - <para> - Replication documents can have a user defined - <literal>_id</literal>. Design documents (and - <literal>_local</literal> documents) added to the replicator - database are ignored. - </para> - - <para> - The default name of this database is - <literal>_replicator</literal>. The name can be changed in the - <filename>local.ini</filename> configuration, section - <literal>[replicator]</literal>, parameter <literal>db</literal>. - </para> - - <section id="couchdb-release-1.1-replicatordb-basics"> - - <title>Basics</title> - - <para> - Let's say you PUT the following document into _replicator: - </para> - -<programlisting> -{ - "_id": "my_rep", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "create_target": true -} -</programlisting> - - <para> - In the couch log you'll see 2 entries like these: - </para> - -<programlisting> -[Thu, 17 Feb 2011 19:43:59 GMT] [info] [<0.291.0>] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target` -[Thu, 17 Feb 2011 19:44:37 GMT] [info] [<0.124.0>] Replication `c0ebe9256695ff083347cbf95f93e280+create_target` finished (triggered by document `my_rep`) -</programlisting> - - <para> - As soon as the replication is triggered, the document will be - updated by CouchDB with 3 new fields: - </para> - -<programlisting> -{ - "_id": "my_rep", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "create_target": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -} -</programlisting> - - <para> - Special fields set by the replicator start with the prefix - <literal>_replication_</literal>. - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>_replication_id</literal> - </para> - - <para> - The ID internally assigned to the replication. This is also - the ID exposed by <literal>/_active_tasks</literal>. - </para> - </listitem> - - <listitem> - <para> - <literal>_replication_state</literal> - </para> - - <para> - The current state of the replication. - </para> - </listitem> - - <listitem> - <para> - <literal>_replication_state_time</literal> - </para> - - <para> - A Unix timestamp (number of seconds since 1 Jan 1970) that - tells us when the current replication state (marked in - <literal>_replication_state</literal>) was set. - </para> - </listitem> - - </itemizedlist> - - <para> - When the replication finishes, it will update the - <literal>_replication_state</literal> field (and - <literal>_replication_state_time</literal>) with the value - <literal>completed</literal>, so the document will look like: - </para> - -<programlisting> -{ - "_id": "my_rep", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "create_target": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "completed", - "_replication_state_time": 1297974122 -} -</programlisting> - - <para> - When an error happens during replication, the - <literal>_replication_state</literal> field is set to - <literal>error</literal> (and - <literal>_replication_state</literal> gets updated of course). - </para> - - <para> - When you PUT/POST a document to the - <literal>_replicator</literal> database, CouchDB will attempt to - start the replication up to 10 times (configurable under - <literal>[replicator]</literal>, parameter - <literal>max_replication_retry_count</literal>). If it fails on - the first attempt, it waits 5 seconds before doing a second - attempt. If the second attempt fails, it waits 10 seconds before - doing a third attempt. If the third attempt fails, it waits 20 - seconds before doing a fourth attempt (each attempt doubles the - previous wait period). When an attempt fails, the Couch log will - show you something like: - </para> - -<programlisting> -[error] [<0.149.0>] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,<<"could not open http://myserver:5986/foo/">> -</programlisting> - - <note> - <para> - The <literal>_replication_state</literal> field is only set to - <literal>error</literal> when all the attempts were - unsuccessful. - </para> - </note> - - <para> - There are only 3 possible values for the - <literal>_replication_state</literal> field: - <literal>triggered</literal>, <literal>completed</literal> and - <literal>error</literal>. Continuous replications never get - their state set to <literal>completed</literal>. - </para> - - </section> - - <section id="couchdb-release-1.1-replicatordb-docsame"> - - <title>Documents describing the same replication</title> - - <para> - Lets suppose 2 documents are added to the - <literal>_replicator</literal> database in the following order: - </para> - -<programlisting> -{ - "_id": "doc_A", - "source": "http://myserver.com:5984/foo", - "target": "bar" -} -</programlisting> - - <para> - and - </para> - -<programlisting> -{ - "_id": "doc_B", - "source": "http://myserver.com:5984/foo", - "target": "bar" -} -</programlisting> - - <para> - Both describe exactly the same replication (only their - <literal>_ids</literal> differ). In this case document - <literal>doc_A</literal> triggers the replication, getting - updated by CouchDB with the fields - <literal>_replication_state</literal>, - <literal>_replication_state_time</literal> and - <literal>_replication_id</literal>, just like it was described - before. Document <literal>doc_B</literal> however, is only - updated with one field, the <literal>_replication_id</literal> - so it will look like this: - </para> - -<programlisting> -{ - "_id": "doc_B", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "_replication_id": "c0ebe9256695ff083347cbf95f93e280" -} -</programlisting> - - <para> - While document <literal>doc_A</literal> will look like this: - </para> - -<programlisting> -{ - "_id": "doc_A", - "source": "http://myserver.com:5984/foo", - "target": "bar", - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -} -</programlisting> - - <para> - Note that both document get exactly the same value for the - <literal>_replication_id</literal> field. This way you can - identify which documents refer to the same replication - you can - for example define a view which maps replication IDs to document - IDs. - </para> - - </section> - - <section id="couchdb-release-1.1-replicatordb-cancel"> - - <title>Canceling replications</title> - - <para> - To cancel a replication simply <literal>DELETE</literal> the - document which triggered the replication. The Couch log will - show you an entry like the following: - </para> - -<programlisting> -[Thu, 17 Feb 2011 20:16:29 GMT] [info] [<0.125.0>] Stopped replication `c0ebe9256695ff083347cbf95f93e280+continuous+create_target` because replication document `doc_A` was deleted -</programlisting> - - <note> - <para> - You need to <literal>DELETE</literal> the document that - triggered the replication. <literal>DELETE</literal>ing - another document that describes the same replication but did - not trigger it, will not cancel the replication. - </para> - </note> - - </section> - - <section id="couchdb-release-1.1-replicatordb-restart"> - - <title>Server restart</title> - - <para> - When CouchDB is restarted, it checks its - <literal>_replicator</literal> database and restarts any - replication that is described by a document that either has its - <literal>_replication_state</literal> field set to - <literal>triggered</literal> or it doesn't have yet the - <literal>_replication_state</literal> field set. - </para> - - <note> - <para> - Continuous replications always have a - <literal>_replication_state</literal> field with the value - <literal>triggered</literal>, therefore they're always - restarted when CouchDB is restarted. - </para> - </note> - - </section> - - <section id="couchdb-release-1.1-replicatordb-changing"> - - <title>Changing the Replicator Database</title> - - <para> - Imagine your replicator database (default name is _replicator) - has the two following documents that represent pull replications - from servers A and B: - </para> - -<programlisting> -{ - "_id": "rep_from_A", - "source": "http://aserver.com:5984/foo", - "target": "foo_a", - "continuous": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297971311 -} -{ - "_id": "rep_from_B", - "source": "http://bserver.com:5984/foo", - "target": "foo_b", - "continuous": true, - "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -} -</programlisting> - - <para> - Now without stopping and restarting CouchDB, you change the name - of the replicator database to - <literal>another_replicator_db</literal>: - </para> - -<programlisting> -$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"' -"_replicator" -</programlisting> - - <para> - As soon as this is done, both pull replications defined before, - are stopped. This is explicitly mentioned in CouchDB's log: - </para> - -<programlisting><![CDATA[ -[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.104.0>] Stopping all ongoing replications because the replicator database was deleted or changed -[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.127.0>] 127.0.0.1 - - PUT /_config/replicator/db 200 -]]> -</programlisting> - - <para> - Imagine now you add a replication document to the new replicator - database named <literal>another_replicator_db</literal>: - </para> - -<programlisting> -{ - "_id": "rep_from_X", - "source": "http://xserver.com:5984/foo", - "target": "foo_x", - "continuous": true -} -</programlisting> - - <para> - From now own you have a single replication going on in your - system: a pull replication pulling from server X. Now you change - back the replicator database to the original one - <literal>_replicator</literal>: - </para> - -<programlisting> -$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"' -"another_replicator_db" -</programlisting> - - <para> - Immediately after this operation, the replication pulling from - server X will be stopped and the replications defined in the - _replicator database (pulling from servers A and B) will be - resumed. - </para> - - <para> - Changing again the replicator database to - <literal>another_replicator_db</literal> will stop the pull - replications pulling from servers A and B, and resume the pull - replication pulling from server X. - </para> - - </section> - - <section id="couchdb-release-1.1-replicatordb-replicating"> - - <title>Replicating the replicator database</title> - - <para> - Imagine you have in server C a replicator database with the two - following pull replication documents in it: - </para> - -<programlisting> -{ - "_id": "rep_from_A", - "source": "http://aserver.com:5984/foo", - "target": "foo_a", - "continuous": true, - "_replication_id": "c0ebe9256695ff083347cbf95f93e280", - "_replication_state": "triggered", - "_replication_state_time": 1297971311 -} -{ - "_id": "rep_from_B", - "source": "http://bserver.com:5984/foo", - "target": "foo_b", - "continuous": true, - "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1", - "_replication_state": "triggered", - "_replication_state_time": 1297974122 -} -</programlisting> - - <para> - Now you would like to have the same pull replications going on - in server D, that is, you would like to have server D pull - replicating from servers A and B. You have two options: - </para> - - <itemizedlist> - - <listitem> - <para> - Explicitly add two documents to server's D replicator - database - </para> - </listitem> - - <listitem> - <para> - Replicate server's C replicator database into server's D - replicator database - </para> - </listitem> - - </itemizedlist> - - <para> - Both alternatives accomplish exactly the same goal. - </para> - - </section> - - <section id="couchdb-release-1.1-replicatordb-delegations"> - - <title>Delegations</title> - - <para> - Replication documents can have a custom - <literal>user_ctx</literal> property. This property defines the - user context under which a replication runs. For the old way of - triggering replications (POSTing to - <literal>/_replicate/</literal>), this property was not needed - (it didn't exist in fact) - this is because at the moment of - triggering the replication it has information about the - authenticated user. With the replicator database, since it's a - regular database, the information about the authenticated user - is only present at the moment the replication document is - written to the database - the replicator database implementation - is like a _changes feed consumer (with - <literal>?include_docs=true</literal>) that reacts to what was - written to the replicator database - in fact this feature could - be implemented with an external script/program. This - implementation detail implies that for non admin users, a - <literal>user_ctx</literal> property, containing the user's name - and a subset of his/her roles, must be defined in the - replication document. This is ensured by the document update - validation function present in the default design document of - the replicator database. This validation function also ensure - that a non admin user can set a user name property in the - <literal>user_ctx</literal> property that doesn't match his/her - own name (same principle applies for the roles). - </para> - - <para> - For admins, the <literal>user_ctx</literal> property is - optional, and if it's missing it defaults to a user context with - name null and an empty list of roles - this mean design - documents will not be written to local targets. If writing - design documents to local targets is desired, the a user context - with the roles <literal>_admin</literal> must be set explicitly. - </para> - - <para> - Also, for admins the <literal>user_ctx</literal> property can be - used to trigger a replication on behalf of another user. This is - the user context that will be passed to local target database - document validation functions. - </para> - - <note> - <para> - The <literal>user_ctx</literal> property only has effect for - local endpoints. - </para> - </note> - - <para> - Example delegated replication document: - </para> - -<programlisting> -{ - "_id": "my_rep", - "source": "http://bserver.com:5984/foo", - "target": "bar", - "continuous": true, - "user_ctx": { - "name": "joe", - "roles": ["erlanger", "researcher"] - } -} -</programlisting> - - <para> - As stated before, for admins the user_ctx property is optional, - while for regular (non admin) users it's mandatory. When the - roles property of <literal>user_ctx</literal> is missing, it - defaults to the empty list <literal>[ ]</literal>. - </para> - - </section> - - </section> - - <section id="couchdb-release-1.1-ssl"> - - <title>Native SSL Support</title> - - <para> - CouchDB 1.1 supports SSL natively. All your secure connection - needs can now be served without the need set and maintain a - separate proxy server that handles SSL. - </para> - - <para> - SSL setup can be tricky, but the configuration in CouchDB was - designed to be as easy as possible. All you need is two files; a - certificate and a private key. If you bought an official SSL - certificate from a certificate authority, both should be in your - possession already. - </para> - - <para> - If you just want to try this out and don't want to pay anything - upfront, you can create a self-signed certificate. Everything will - work the same, but clients will get a warning about an insecure - certificate. - </para> - - <para> - You will need the OpenSSL command line tool installed. It probably - already is. - </para> - -<programlisting> -shell> <userinput>mkdir cert && cd cert</userinput> -shell> <userinput>openssl genrsa > privkey.pem</userinput> -shell> <userinput>openssl req -new -x509 -key privkey.pem -out mycert.pem -days 1095</userinput> -shell> <userinput>ls</userinput> -mycert.pem privkey.pem -</programlisting> - - <para> - Now, you need to edit CouchDB's configuration, either by editing - your <filename>local.ini</filename> file or using the - <literal>/_config</literal> API calls or the configuration screen - in Futon. Here is what you need to do in - <filename>local.ini</filename>, you can infer what needs doing in - the other places. - </para> - - <para> - Be sure to make these edits. Under <literal>[daemons]</literal> - you should see: - </para> - -<programlisting> -; enable SSL support by uncommenting the following line and supply the PEM's below. -; the default ssl port CouchDB listens on is 6984 -;httpsd = {couch_httpd, start_link, [https]} -</programlisting> - - <para> - Here uncomment the last line: - </para> - -<programlisting> -httpsd = {couch_httpd, start_link, [https]} -</programlisting> - - <para> - Next, under <literal>[ssl]</literal> you will see: - </para> - -<programlisting> -;cert_file = /full/path/to/server_cert.pem -;key_file = /full/path/to/server_key.pem -</programlisting> - - <para> - Uncomment and adjust the paths so it matches your system's paths: - </para> - -<programlisting> -cert_file = /home/jan/cert/mycert.pem -key_file = /home/jan/cert/privkey.pem -</programlisting> - - <para> - For more information please read - <ulink - url="http://www.openssl.org/docs/HOWTO/certificates.txt">http://www.openssl.org/docs/HOWTO/certificates.txt</ulink>. - </para> - - <para> - Now start (or restart) CouchDB. You should be able to connect to - it using HTTPS on port 6984: - </para> - -<programlisting> -shell> <userinput>curl https://127.0.0.1:6984/</userinput> -curl: (60) SSL certificate problem, verify that the CA cert is OK. Details: -error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed -More details here: http://curl.haxx.se/docs/sslcerts.html - -curl performs SSL certificate verification by default, using a "bundle" -of Certificate Authority (CA) public keys (CA certs). If the default -bundle file isn't adequate, you can specify an alternate file -using the --cacert option. -If this HTTPS server uses a certificate signed by a CA represented in -the bundle, the certificate verification probably failed due to a -problem with the certificate (it might be expired, or the name might -not match the domain name in the URL). -If you'd like to turn off curl's verification of the certificate, use -the -k (or --insecure) option. -</programlisting> - - <para> - Oh no what happened?! — Remember, clients will notify their - users that your certificate is self signed. - <command>curl</command> is the client in this case and it notifies - you. Luckily you trust yourself (don't you?) and you can specify - the <option>-k</option> option as the message reads: - </para> - -<programlisting> -shell> <userinput>curl -k https://127.0.0.1:6984/</userinput> -{"couchdb":"Welcome","version":"1.1.0"} -</programlisting> - - <para> - All done. - </para> - - </section> - - <section id="couchdb-release-1.1-httprange"> - - <title>HTTP Range Requests</title> - - <para> - HTTP allows you to specify byte ranges for requests. This allows - the implementation of resumable downloads and skippable audio and - video streams alike. Now this is available for all attachments - inside CouchDB. - </para> - - <para> - This is just a real quick run through how this looks under the - hood. Usually, you will have larger binary files to serve from - CouchDB, like MP3s and videos, but to make things a little more - obvious, I use a text file here (Note that I use the - <literal>application/octet-stream</literal> Content-Type instead - of <literal>text/plain</literal>). - </para> - -<programlisting> -shell> <userinput>cat file.txt </userinput> -My hovercraft is full of eels! -</programlisting> - - <para> - Now lets store this text file as an attachment in CouchDB. First, - we create a database: - </para> - -<programlisting> -shell> <userinput>curl -X PUT http://127.0.0.1:5984/test</userinput> -{"ok":true} -</programlisting> - - <para> - Then we create a new document and the file attachment in one go: - </para> - -<programlisting> -shell> <userinput>curl -X PUT http://127.0.0.1:5984/test/doc/file.txt -H "Content-Type: application/octet-stream" -d@file.txt</userinput> -{"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"} -</programlisting> - - <para> - Now we can request the whole file easily: - </para> - -<programlisting> -shell> <userinput>curl -X GET http://127.0.0.1:5984/test/doc/file.txt</userinput> -My hovercraft is full of eels! -</programlisting> - - <para> - But say we only want the first 13 bytes: - </para> - -<programlisting> -shell> <userinput>curl -X GET http://127.0.0.1:5984/test/doc/file.txt -H "Range: bytes=0-12"</userinput> -My hovercraft -</programlisting> - - <para> - HTTP supports many ways to specify single and even multiple byte - rangers. Read all about it in - <ulink - url="http://tools.ietf.org/html/rfc2616#section-14.27">RFC - 2616</ulink>. - </para> - - <note> - <para> - Databases that have been created with CouchDB 1.0.2 or earlier - will support range requests in 1.1.0, but they are using a - less-optimal algorithm. If you plan to make heavy use of this - feature, make sure to compact your database with CouchDB 1.1.0 - to take advantage of a better algorithm to find byte ranges. - </para> - </note> - - </section> - - <section id="couchdb-release-1.1-proxying"> - - <title>HTTP Proxying</title> - - <para> - The HTTP proxy feature makes it easy to map and redirect different - content through your CouchDB URL. The proxy works by mapping a - pathname and passing all content after that prefix through to the - configured proxy address. - </para> - - <para> - Configuration of the proxy redirect is handled through the - <literal>[httpd_global_handlers]</literal> section of the CouchDB - configuration file (typically <filename>local.ini</filename>). The - format is: - </para> - -<programlisting> -[httpd_global_handlers] -PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>} - </programlisting> - - <para> - Where: - </para> - - <itemizedlist> - - <listitem> - <para> - <literal>PREFIX</literal> - </para> - - <para> - Is the string that will be matched. The string can be any - valid qualifier, although to ensure that existing database - names are not overridden by a proxy configuration, you can use - an underscore prefix. - </para> - </listitem> - - <listitem> - <para> - <literal>DESTINATION</literal> - </para> - - <para> - The fully-qualified URL to which the request should be sent. - The destination must include the <literal>http</literal> - prefix. The content is used verbatim in the original request, - so you can also forward to servers on different ports and to - specific paths on the target host. - </para> - </listitem> - - </itemizedlist> - - <para> - The proxy process then translates requests of the form: - </para> - -<programlisting> -http://couchdb:5984/PREFIX/path -</programlisting> - - <para> - To: - </para> - -<programlisting> -DESTINATION/path -</programlisting> - - <note> - <para> - Everything after <literal>PREFIX</literal> including the - required forward slash will be appended to the - <literal>DESTINATION</literal>. - </para> - </note> - - <para> - The response is then communicated back to the original client. - </para> - - <para> - For example, the following configuration: - </para> - -<programlisting> -<![CDATA[ -_google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>}]]> -</programlisting> - - <para> - Would forward all requests for - <literal>http://couchdb:5984/_google</literal> to the Google - website. - </para> - - <para> - The service can also be used to forward to related CouchDB - services, such as Lucene: - </para> - -<programlisting> - <![CDATA[ -[httpd_global_handlers] -_fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}]]> -</programlisting> - - <note> - <para> - The proxy service is basic. If the request is not identified by - the <literal>DESTINATION</literal>, or the remainder of the - <literal>PATH</literal> specification is incomplete, the - original request URL is interpreted as if the - <literal>PREFIX</literal> component of that URL does not exist. - </para> - - <para> - For example, requesting - <literal>http://couchdb:5984/_intranet/media</literal> when - <filename>/media</filename> on the proxy destination does not - exist, will cause the request URL to be interpreted as - <literal>http://couchdb:5984/media</literal>. Care should be - taken to ensure that both requested URLs and destination URLs - are able to cope - </para> - </note> - - </section> - - <section id="couchdb-release-1.1-commonjs"> - - <title>Added CommonJS support to map functions</title> - - <para> - We didn't have CommonJS require in map functions because the - current CommonJS implementation is scoped to the whole design doc, - and giving views access to load code from anywhere in the design - doc would mean we'd have to blow away your view index any time you - changed anything. Having to rebuild views from scratch just - because you changed some CSS or a show function isn't fun, so we - avoided the issue by keeping CommonJS require out of map and - reduce altogether. - </para> - - <para> - The solution we came up with is to allow CommonJS inside map and - reduce funs, but only of libraries that are stored inside the - views part of the design doc. - </para> - - <para> - So you could continue to access CommonJS code in design_doc.foo, - from your list functions etc, but we'd add the ability to require - CommonJS modules within map and reduce, but only from - design_doc.views.lib - </para> - - <para> - There's no worry here about namespace collisions, as Couch just - plucks <literal>views.*.map</literal> and - <literal>views.*.reduce</literal> out of the design doc. So you - could have a view called <literal>lib</literal> if you wanted, and - still have CommonJS stored in <literal>views.lib.sha1</literal> - and <literal>views.lib.stemmer</literal> if you wanted. - </para> - - <para> - We simplified the implementation by enforcing that CommonJS - modules to be used in map functions be stored in views.lib. - </para> - - <para> - A sample design doc (taken from the test suite in Futon) is below: - </para> - -<programlisting> -{ - "views" : { - "lib" : { - "baz" : "exports.baz = 'bam';", - "foo" : { - "zoom" : "exports.zoom = 'yeah';", - "boom" : "exports.boom = 'ok';", - "foo" : "exports.foo = 'bar';" - } - }, - "commonjs" : { - "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}" - } - }, - "_id" : "_design/test" -} -</programlisting> - - <para> - The <literal>require()</literal> statement is relative to the - design document, but anything loaded form outside of - <literal>views/lib</literal> will fail. - </para> - - </section> - - <section id="couchdb-release-1.1-etag"> - - <title>More granular ETag support for views</title> - - <para> - ETags have been assigned to a map/reduce group (the collection of - views in a single design document). Any change to any of the - indexes for those views would generate a new ETag for all view - URL's in a single design doc, even if that specific view's results - had not changed. - </para> - - <para> - In CouchDB 1.1 each <literal>_view</literal> URL has it's own ETag - which only gets updated when changes are made to the database that - effect that index. If the index for that specific view does not - change, that view keeps the original ETag head (therefore sending - back 304 Not Modified more often). - </para> - - </section> - - <section id="couchdb-release-1.1-filters"> - - <title>Added built-in filters for <literal>_changes</literal>: - <literal>_doc_ids</literal> and <literal>_design</literal>.</title> - - <para> - The <literal>_changes</literal> feed can now be used to watch - changes to specific document ID's or the list of - <literal>_design</literal> documents in a database. If the - <literal>filters</literal> parameter is set to - <literal>_doc_ids</literal> a list of doc IDs can be passed in the - "doc_ids" as a JSON array. - </para> - - </section> - - <section id="couchdb-release-1.1-wildcards"> - - <title>Allow wildcards in vhosts definitions</title> - - <para> - Similar to the rewrites section of a <literal>_design</literal> - document, the new <literal>vhosts</literal> system uses variables - in the form of :varname or wildcards in the form of asterisks. The - variable results can be output into the resulting path as they are - in the rewriter. - </para> - - </section> - - <section id="couchdb-release-1.1-osprocess"> - - <title>OS Daemons</title> - - <para> - CouchDB now supports starting external processes. The support is - simple and enables CouchDB to start each configured OS daemon. If - the daemon stops at any point, CouchDB will restart it (with - protection to ensure regularly failing daemons are not repeatedly - restarted). - </para> - - <para> - The daemon starting process is one-to-one; for each each - configured daemon in the configuration file, CouchDB will start - exactly one instance. If you need to run multiple instances, then - you must create separate individual configurations. Daemons are - configured within the <literal>[os_daemons]</literal> section of - your configuration file (<filename>local.ini</filename>). The - format of each configured daemon is: - </para> - -<programlisting> -NAME = PATH ARGS - </programlisting> - - <para> - Where <literal>NAME</literal> is an arbitrary (and unique) name to - identify the daemon; <literal>PATH</literal> is the full path to - the daemon to be executed; <literal>ARGS</literal> are any - required arguments to the daemon. - </para> - - <para> - For example: - </para> - -<programlisting> -[os_daemons] -basic_responder = /usr/local/bin/responsder.js -</programlisting> - - <para> - There is no interactivity between CouchDB and the running process, - but you can use the OS Daemons service to create new HTTP servers - and responders and then use the new proxy service to redirect - requests and output to the CouchDB managed service. For more - information on proxying, see - <xref - linkend="couchdb-release-1.1-proxying"/>. For further - background on the OS Daemon service, see - <ulink url="http://davispj.com/2010/09/26/new-couchdb-externals-api.html">CouchDB - Externals API</ulink> - </para> - - </section> - - <section id="coudhdb-release-1.1-updateafter"> - - <title>Stale views and <literal>update_after</literal></title> - - <para> - Currently a view request can include the - <literal>stale=ok</literal> query argument, which allows the - contents of a stale view index to be used to produce the view - output. In order to trigger a build of the outdated view index, a - second view request must be made. - </para> - - <para> - To simplify this process, the <literal>update_after</literal> - value can be supplied to the <literal>stale</literal> query - argument. This triggers a rebuild of the view index after the - results of the view have been retrieved. - </para> - - </section> - - <section id="couchdb-release-1.1-socketoptions"> - - <title>Socket Options Configuration Setting</title> - - <para> - The socket options for the listening socket in CouchDB can now be - set within the CouchDB configuration file. The setting should be - added to the <literal>[httpd]</literal> section of the file using - the option name <literal>socket_options</literal>. The - specification is as a list of tuples. For example: - </para> - -<programlisting> -[httpd] -socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}] -</programlisting> - - <para> - The options supported are a subset of full options supported by - the TCP/IP stack. A list of the supported options are provided in - the - <ulink - url="http://www.erlang.org/doc/man/inet.html#setopts-2">Erlang - inet</ulink> documentation. - </para> - - </section> - - <section id="couchdb-release-1.1-serveroptions"> - - <title>Server Options Configuration Setting</title> - - <para> - Server options for the MochiWeb component of CouchDB can now be - added to the configuration file. Settings should be added to the - <literal>server_options</literal> option of the - <literal>[httpd]</literal> section of - <filename>local.ini</filename>. For example: - </para> - -<programlisting> -[httpd] -server_options = [{backlog, 128}, {acceptor_pool_size, 16}] - </programlisting> - - </section> - - <section id="couchdb-release-1.1-errormessages"> - - <title>Improved Error Messages</title> - - <para> - The errors reported when CouchDB is unable to read a required file - have been updated so that explicit information about the files and - problem can now be identified from the error message. The errors - report file permission access either when reading or writing to - configuration and database files. - </para> - - <para> - The error is raised both through the log file and the error - message returned through the API call as a JSON error message. For - example, when setting configuration values: - </para> - -<programlisting> -shell> <userinput>curl -H 'X-Couch-Persist: true' -X PUT http://couchdb:5984/_config/couchdb/delayed_commits -d '"false"'</userinput> -{"error":"file_permission_error","reason":"/etc/couchdb/local.ini"} - </programlisting> - - <para> - Errors will always be reported using the - <literal>file_permission_error</literal> error type. - </para> - - <para> - During startup permissions errors on key files are also reported - in the log with a descriptive error message and file location so - that permissions can be fixed before restart. - </para> - - </section> - - <section id="couchdb-release-1.1-microoptimizations"> - - <title>Multiple micro-optimizations when reading data.</title> - - <para> - We found a number of places where CouchDB wouldn't do the absolute - optimal thing when reading data and got rid of quite a few - inefficiencies. The problem with small optimizations all over the - place is that you may not notice them with every use-case, but we - sure hope you can see an improvement overall. - </para> - - </section> - -</article> |