### Navigation

- index
- next |
- previous |
- Apache CouchDB 1.3 Manual »
- 18. API Reference »

# 18.3. 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.

## 18.3.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.

## 18.3.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.

## 18.3.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
    }

## 18.3.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.

### 18.3.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.

## 18.3.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.

## 18.3.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
    }

## 18.3.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
    }

## 18.3.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"
    }

## 18.3.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

### 18.3.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.

### 18.3.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.

### 18.3.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.

### 18.3.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"
      }

## 18.3.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.

## 18.3.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
    }

### 18.3.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.

## 18.3.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.

## 18.3.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
    }

## 18.3.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

## 18.3.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

## 18.3.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.

## 18.3.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
    }

## 18.3.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

## 18.3.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
    }

### Navigation

- index
- next |
- previous |
- Apache CouchDB 1.3 Manual »
- 18. API Reference »