CouchDB API Server Database Methods

-Database API CallsMethodPathDescriptionGET/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: - - - -GET /recipes - - - - For clarity, the form below is used in the URL paths: - - - -GET /db - - - - Where db is the name of any database. - - -

- - <literal>GET /db</literal> - - - - - - -URL API GET /dbMethodGET /dbRequest - None - Response - Information about the database in JSON format - Admin Privileges RequirednoReturn Codes404 - 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: - - - -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: - - - -{ - "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: - - - - - - - - - CouchDB database information object - FieldDescriptioncommitted_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. -

- -

- - <literal>PUT /db</literal> - - - - - - -URL API PUT /dbMethodPUT /dbRequest - None - Response - JSON success statement - Admin Privileges RequirednoReturn Codes400 - 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: - - - -PUT http://couchdb:5984/recipes -Content-Type: application/json - - - - The returned content contains the JSON status: - - - -{ - "ok" : true -} - - - - Anything should be treated as an error, and the problem should be - taken form the HTTP response code. - - -

- -

- - <literal>DELETE /db</literal> - - - - - - -URL API DELETE /dbMethodDELETE /dbRequest - None - Response - JSON success statement - Admin Privileges RequirednoReturn Codes200 - 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: - - - -DELETE http://couchdb:5984/recipes -Content-Type: application/json - - - - If successful, the returned JSON will indicate success - - - -{ - "ok" : true -} - - -

- -

- - <literal>GET /db/_changes</literal> - - - - - - -URL API GET /db/_changesMethodGET /db/_changesRequest - None - Response - JSON of the changes to the database - Admin Privileges RequirednoQuery ArgumentsArgumentdoc_idsDescription - Specify the list of documents IDs to be filtered - OptionalyesTypejsonDefaultnoneArgumentfeedDescription - Type of feed - OptionalyesTypestringDefaultnormalSupported ValuescontinuousContinuous (non-polling) modelongpollLong polling modenormalNormal modeArgumentfilterDescription - Filter function from a design document to get updates - OptionalyesTypestringDefaultnoneSupported ValuesArgumentheartbeatDescription - Period after which an empty line is sent during longpoll or - continuous - OptionalyesTypenumericDefault60000QuantitymillisecondsArgumentinclude_docsDescription - Include the document with the result - OptionalyesTypebooleanDefaultfalseArgumentlimitDescription - Maximum number of rows rows to return - OptionalyesTypenumericDefaultnoneArgumentsinceDescription - Start the results from changes immediately after the - specified sequence number - OptionalyesTypenumericDefault0ArgumenttimeoutDescription - Maximum period to wait before the response is sent - OptionalyesTypenumericDefault60000Quantitymilliseconds - - - 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 - - - -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 changesand 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. - - - - - - - - - Changes information for a database - FieldDescriptionlast_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: - - - -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 parameter as a JSON array. - - - - For more information, see - . - - -

- -

- - <literal>POST /db/_compact</literal> - - - - - - -URL API POST /db/_compactMethodPOST /db/_compactRequest - None - Response - JSON success statement - Admin Privileges RequirednoReturn Codes202 - 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 - . - - - - - - - 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 - . - - - - You can also obtain a list of running processes to determine - whether compaction is currently running. See - . - - -

- -

- - <literal>POST /db/_compact/design-doc</literal> - - - - - - -URL API POST /db/_compact/design-docMethodPOST /db/_compact/design-docRequest - None - Response - JSON success statement - Admin Privileges RequiredyesReturn Codes202 - 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: - - - -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): - - - -{ - "ok" : true -} - - -

- -

- - <literal>POST /db/_view_cleanup</literal> - - - - - - -URL API POST /db/_view_cleanupMethodPOST /db/_view_cleanupRequest - None - Response - JSON success statement - Admin Privileges Requiredyes - - - Cleans up the cached view output on disk for a given view. For - example: - - - -POST http://couchdb:5984/recipes/_view_cleanup -Content-Type: application/json - - - - If the request is successful, a basic status message us returned: - - - -{ - "ok" : true -} - - -

- -

- - <literal>POST /db/_ensure_full_commit</literal> - - - - - - -URL API POST /db/_ensure_full_commitMethodPOST /db/_ensure_full_commitRequest - None - Response - JSON success statement - Admin Privileges RequirednoReturn Codes200 - 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: - - - -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: - - - -{ - "ok" : true, - "instance_start_time" : "1288186189373361" -} - - - - -

- -

- - <literal>POST /db/_bulk_docs</literal> - - - - - - -URL API POST /db/_bulk_docsMethodPOST /db/_bulk_docsRequest - JSON of the docs and updates to be applied - Response - JSON of updated documents - Admin Privileges RequirednoReturn Codes201 - 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: - - - - - - - - - Bulk Documents - FieldDescriptionall_or_nothing (optional) - Sets the database commit mode to use all-or-nothing semantics - docs [array] - Bulk Documents Document - _id (optional) - Document ID - _rev (optional) - Revision ID (when updating an existing document) - _deleted (optional) - Whether the document should be deleted -

- -

- - 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: - - - -{ - "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: - - - -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 - - for more information. Conflicts and validation errors when - updating documents in bulk must be handled separately; see - . - - -

- -

- - 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: - - - -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: - - - -[ - { - "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 docment 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 - - for more information. Conflicts and validation errors when - updating documents in bulk must be handled separately; see - . - - -

- -

- - 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: - - - -[ - { - "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: - - - -[ - { - "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 in the table below: - - - - Conflicts on Bulk Inserts - - - - - Transaction Mode - - - Transaction - - - Cause - - - Resolution - - - - - - - Non-atomic - - - Insert - - - Requested document ID already exists - - - Resubmit with different document ID, or update the - existing document - - - - - Non-atomic - - - Update - - - Revision missing or incorrect - - - Resubmit with correct revision - - - - - All-or-nothing - - - Insert - - - Additional revision inserted - - - Resolve conflicted revisions - - - - - All-or-nothing - - - Update - - - Additional revision inserted - - - 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 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 shown in - . - - - - - - - - - Bulk Document Response - FieldDescriptiondocs [array] - Bulk Docs Returned Documents - error - Error type - id - Document ID - reason - Error string with extended reason -

- - - When a document (or document revision) is not correctly comitted - 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: - - - throw({forbidden: 'invalid recipe ingredient'}); - - - The error returned will be: - - - -{ - "id" : "7f7638c86173eb440b8890839ff35433", - "error" : "forbidden", - "reason" : "invalid recipe ingredient" -} - - - - For more information, see - . - - - - - -

- -

- - <literal>POST /db/_temp_view</literal> - - - - - - -URL API POST /db/_temp_viewMethodPOST /db/_temp_viewRequest - JSON with the temporary view definition - Response - Temporary view result set - Admin Privileges Requiredyes - - - Creates (and executes) a temporary view based on the view function - supplied in the JSON request. For example: - - - -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: - - - -{ - "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. - - - - For more information, see - . - - -

- -

- - <literal>POST /db/_purge</literal> - - - - - - -URL API POST /db/_purgeMethodPOST /db/_purgeRequest - JSON of the document IDs/revisions to be purged - Response - JSON structure with purged documents and purge sequence - Admin Privileges Requiredno - - - A database purge permanently removes the references to deleted - documents from the database. Deleting a document within CouchDB - does not actually remove the documen from the database, instead, - the document is marked as a deleted (and a new revision is - created). This is to ensure that deleted documents are replicated - to other databases as having been deleted. This also means that - you can check the status of a document and identify that the - document has been deleted. - - - - The purge operation removes the refernces to the deleted documents - from the database. The purging of old documents is not replicated - to other databases. If you are replicating between databases and - have deleted a large number of documents you should run purge on - each database. - - - - - Purging documents does not remove the space used by them on - disk. To reclaim disk space, you should run a database compact - (see , and - compact views (see - ). - - - - - To perform a purge operation you must send a request including the - JSON of the document IDs that you want to purge. For example: - - - -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. - - - -{ - "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. - - -

- -

- - <literal>GET /db/_all_docs</literal> - - - - - - -URL API GET /db/_all_docsMethodGET /db/_all_docsRequest - None - Response - JSON object containing document information, ordered by the - document ID - Admin Privileges RequirednoQuery ArgumentsArgumentdescendingDescription - Return the documents in descending by key order - OptionalyesTypebooleanDefaultfalseArgumentendkeyDescription - Stop returning records when the specified key is reached - OptionalyesTypestringArgumentendkey_docidDescription - Stop returning records when the specified document ID is - reached - OptionalyesTypestringArgumentgroupDescription - Group the results using the reduce function to a group or - single row - OptionalyesTypebooleanDefaultfalseArgumentgroup_levelDescription - Specify the group level to be used - OptionalyesTypenumericArgumentinclude_docsDescription - Include the full content of the documents in the return - OptionalyesTypebooleanDefaultfalseArgumentinclusive_endDescription - Specifies whether the specified end key should be included - in the result - OptionalyesTypebooleanDefaulttrueArgumentkeyDescription - Return only documents that match the specified key - OptionalyesTypestringArgumentlimitDescription - Limit the number of the returned documents to the specified - number - OptionalyesTypenumericArgumentreduceDescription - Use the reduction function - OptionalyesTypebooleanDefaulttrueArgumentskipDescription - Skip this number of records before starting to return the - results - OptionalyesTypenumericDefault0ArgumentstaleDescription - Allow the results from a stale view to be used - OptionalyesTypestringDefaultSupported ValuesokAllow stale viewsArgumentstartkeyDescription - Return records starting with the specified key - OptionalyesTypestringArgumentstartkey_docidDescription - Return records starting with the specified document ID - OptionalyesTypestringArgumentupdate_seqDescription - Include the update sequence in the generated results - OptionalyesTypebooleanDefaultfalse - - - 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. - - - - - - - - - All Database Documents - FieldDescriptionoffset - Offset where the document list started - rows [array] - Array of document object - total_rows - Number of documents in the database/view - update_seq (optional) - Current update sequence for the database -

- - - By default the information returned contains only the document ID - and revision. For example, the request: - - - -GET http://couchdb:5984/recipes/_all_docs -Accept: application/json - - - - Returns the following structure: - - - -{ - "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. - - - - -

- -

- - <literal>POST /db/_all_docs</literal> - - - - - - -URL API POST /db/_all_docsMethodPOST /db/_all_docsRequest - JSON of the document IDs you want included - Response - JSON of the returned view - Admin Privileges Requiredno - - - 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 - requests. - - - - The request body should contain a list of the keys to be returned - as an array to a keys object. For example: - - - -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: - - - -{ - "total_rows" : 2666, - "rows" : [ - { - "value" : { - "rev" : "1-a3544d296de19e6f5b932ea77d886942" - }, - "id" : "Zingylemontart", - "key" : "Zingylemontart" - }, - { - "value" : { - "rev" : "1-91635098bfe7d40197a1b98d7ee085fc" - }, - "id" : "Yogurtraita", - "key" : "Yogurtraita" - } - ], - "offset" : 0 -} - - - - -

- -

- - <literal>POST /db/_missing_revs</literal> - - - - - - -URL API POST /db/_missing_revsMethodPOST /db/_missing_revsRequest - JSON list of document revisions - Response - JSON of missing revisions - Admin Privileges Requiredno - -

- -

- - <literal>POST /db/_revs_diff</literal> - - - - - - -URL API POST /db/_revs_diffMethodPOST /db/_revs_diffRequest - JSON list of document and revisions - Response - JSON list of differences from supplied document/revision list - Admin Privileges Requiredno - -

- -

- - <literal>GET /db/_security</literal> - - - - - - -URL API GET /db/_securityMethodGET /db/_securityRequest - None - Response - JSON of the security object - Admin Privileges Requiredno - - - Gets the current secrity 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: - - - -{ - "admins" : { - "roles" : [], - "