http://git-wip-us.apache.org/repos/asf/couchdb/blob/838cf30b/share/docs/rst/api/database.rst ---------------------------------------------------------------------- diff --git a/share/docs/rst/api/database.rst b/share/docs/rst/api/database.rst new file mode 100644 index 0000000..becc7d5 --- /dev/null +++ b/share/docs/rst/api/database.rst @@ -0,0 +1,1451 @@ +.. _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/838cf30b/share/docs/rst/api/dbmaint.rst ---------------------------------------------------------------------- diff --git a/share/docs/rst/api/dbmaint.rst b/share/docs/rst/api/dbmaint.rst new file mode 100644 index 0000000..8686caf --- /dev/null +++ b/share/docs/rst/api/dbmaint.rst @@ -0,0 +1,3 @@ +==================== +Database Maintenance +====================
