couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d..@apache.org
Subject [16/33] Transmogrify Couchbase XML to .rst and support Sphinx
Date Mon, 03 Dec 2012 13:33:18 GMT
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49d66c4b/share/doc/src/api/database.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database.rst b/share/doc/src/api/database.rst
new file mode 100644
index 0000000..826adaa
--- /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

http://git-wip-us.apache.org/repos/asf/couchdb/blob/49d66c4b/share/doc/src/api/dbmaint.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/dbmaint.rst b/share/doc/src/api/dbmaint.rst
new file mode 100644
index 0000000..9b2019d
--- /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
+====================


Mime
View raw message