| .. 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 | |
| | | opened, expressed in microseconds 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 |
| |
| Occasionally something into ends up in your database that should never have |
| written to it, like a password or private key. Purge can help you here. |
| |
| 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. |
| |
| .. note:: |
| |
| Don't use purge as a regular operation, it is designed to be used |
| in exceptional cases. |
| |
| 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 |