You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ja...@apache.org on 2012/12/06 12:34:41 UTC
[23/50] [abbrv] git commit: import Couchbase docs
import Couchbase docs
git clone git://github.com/janl/couchdb-docs.git
cd couchdb-docs
rm -rf DocKit Makefile Makefile.bootstrap README.md common couchdb-manual-1.1 couchdb-release-1.1 metadocs
git checkout 9fc95b422060d020ba25f559e893fc7fb98c9a15 -- 'couchdb-manual-1.1/*.xml' 'couchdb-release-1.1/*.xml'
tar cvzf couchdb-docs.tar.gz couchdb-manual-1.1 couchdb-release-1.1
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/fd643691
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/fd643691
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/fd643691
Branch: refs/heads/1536-feature-add-docs
Commit: fd6436917dad93361f47cba8d54593e2f541b46c
Parents: 03ba853
Author: Dave Cottlehuber <dc...@apache.org>
Authored: Mon Dec 3 13:36:58 2012 +0100
Committer: Jan Lehnardt <ja...@apache.org>
Committed: Thu Dec 6 12:30:25 2012 +0100
----------------------------------------------------------------------
.../couchdb-api-auth-metasrc.xml | 36 +
.../couchdb-api-config-metasrc.xml | 359 +
.../couchdb-manual-1.1/couchdb-api-db-metasrc.xml | 1828 +++
.../couchdb-api-dbdoc-metasrc.xml | 1016 ++
.../couchdb-api-design-metasrc.xml | 1462 +++
.../couchdb-api-introduction.xml | 851 ++
.../couchdb-api-json-metasrc.xml | 43 +
.../couchdb-api-localdb-metasrc.xml | 186 +
.../couchdb-api-misc-metasrc.xml | 1357 +++
.../couchdb-manual-1.1/couchdb-changes-metasrc.xml | 67 +
.../couchdb-config-options-metasrc.xml | 393 +
.../couchdb-manual-1.1/couchdb-configuration.xml | 328 +
share/docs/couchdb-manual-1.1/couchdb-dbmaint.xml | 15 +
share/docs/couchdb-manual-1.1/couchdb-features.xml | 301 +
.../couchdb-manual-1.1/couchdb-introduction.xml | 578 +
.../couchdb-manual-1.1/couchdb-manual-ready.xml | 9409 +++++++++++++++
share/docs/couchdb-manual-1.1/couchdb-manual.xml | 65 +
.../couchdb-manual-1.1/couchdb-replication.xml | 554 +
.../couchdb-single-troubleshooting.xml | 35 +
share/docs/couchdb-manual-1.1/couchdb-views.xml | 15 +
.../metadoc-couchdb-api-auth.xml | 40 +
.../metadoc-couchdb-api-config.xml | 348 +
.../couchdb-manual-1.1/metadoc-couchdb-api-db.xml | 1937 +++
.../metadoc-couchdb-api-dbdoc.xml | 1091 ++
.../metadoc-couchdb-api-design.xml | 1543 +++
.../metadoc-couchdb-api-json.xml | 347 +
.../metadoc-couchdb-api-localdb.xml | 188 +
.../metadoc-couchdb-api-misc.xml | 1412 +++
.../metadoc-couchdb-config-options.xml | 413 +
.../couchdb-release-1.1-ready.xml | 1154 ++
.../couchdb-release-1.1/couchdb-release-1.1.xml | 1243 ++
31 files changed, 28614 insertions(+), 0 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fd643691/share/docs/couchdb-manual-1.1/couchdb-api-auth-metasrc.xml
----------------------------------------------------------------------
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
new file mode 100644
index 0000000..417500a
--- /dev/null
+++ b/share/docs/couchdb-manual-1.1/couchdb-api-auth-metasrc.xml
@@ -0,0 +1,36 @@
+<?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>
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fd643691/share/docs/couchdb-manual-1.1/couchdb-api-config-metasrc.xml
----------------------------------------------------------------------
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
new file mode 100644
index 0000000..aa1ac27
--- /dev/null
+++ b/share/docs/couchdb-manual-1.1/couchdb-api-config-metasrc.xml
@@ -0,0 +1,359 @@
+<?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>
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fd643691/share/docs/couchdb-manual-1.1/couchdb-api-db-metasrc.xml
----------------------------------------------------------------------
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
new file mode 100644
index 0000000..0b3084a
--- /dev/null
+++ b/share/docs/couchdb-manual-1.1/couchdb-api-db-metasrc.xml
@@ -0,0 +1,1828 @@
+<?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>