8.1. 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:

GET /recipes

For clarity, the form below is used in the URL paths:

GET /db

Where db is the name of any database.

8.1.1. 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:

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:

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.

8.1.2. 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:

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.

8.1.3. 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:

DELETE http://couchdb:5984/recipes
Content-Type: application/json

If successful, the returned JSON will indicate success

{
   "ok" : true
}

8.1.4. 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

  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.

8.1.4.1. 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 doc_ids parameter as a JSON array. For more information, see Changes Feed.

8.1.5. 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 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 GET /db.

You can also obtain a list of running processes to determine whether compaction is currently running. See GET /_active_tasks.

8.1.6. 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:

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
}

8.1.7. 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:

POST http://couchdb:5984/recipes/_view_cleanup
Content-Type: application/json

If the request is successful, a basic status message us returned:

{
   "ok" : true
}

8.1.8. 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:

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"
}

8.1.9. 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

8.1.9.1. 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 Bulk Documents Transaction Semantics for more information. Conflicts and validation errors when updating documents in bulk must be handled separately; see Bulk Document Validation and Conflict Errors.

8.1.9.2. 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 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 Bulk Documents Transaction Semantics for more information. Conflicts and validation errors when updating documents in bulk must be handled separately; see Bulk Document Validation and Conflict Errors.

8.1.9.3. 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 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.

8.1.9.4. 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:

  throw({forbidden: 'invalid recipe ingredient'});
  

  The error returned will be:

  {
     "id" : "7f7638c86173eb440b8890839ff35433",
     "error" : "forbidden",
     "reason" : "invalid recipe ingredient"
  }
  

8.1.10. 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:

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.

8.1.11. 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 POST /db/_compact), and compact views (see POST /db/_compact/design-doc).

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
}

8.1.11.1. 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.

8.1.12. 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:

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.

8.1.13. 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 GET /db/doc 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
}

8.1.14. POST /db/_missing_revs

• Method: POST /db/_missing_revs
• Request: JSON list of document revisions
• Response: JSON of missing revisions
• Admin Privileges Required: no

8.1.15. 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

8.1.16. 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:

{
   "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.

8.1.17. 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:

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:

{
   "ok" : true
}

8.1.18. 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:

GET http://couchdb:5984/recipes/_revs_limit
Content-Type: application/json

The returned information is the current setting as a numerical scalar:

1000

8.1.19. 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:

PUT http://couchdb:5984/recipes/_revs_limit
Content-Type: application/json

100

If the setting was successful, a JSON status object will be returned:

{
   "ok" : true
}