CouchDB 1.1 Manual

Futon is a native web-based interface built into CouchDB. It provides a basic interface to the majority of the functionality, including the ability to create, update, delete and view documents and views, provides access to the configuration parameters, and an interface for initiating replication.

The default view is the Overview page which provides you with a list of the databases. The basic structure of the page is consistent regardless of the section you are in. The main panel on the left provides the main interface to the databases, configuration or replication systems. The side panel on the right provides navigation to the main areas of Futon interface:

Figure 1.1. Futon Overview

The main sections are:

1.1.1. Managing Databases and Documents

You can manage databases and documents within Futon using the main Overview section of the Futon interface.

To create a new database, click the Create Database … button. You will be prompted for the database name, as shown in the figure below.

Figure 1.2. Creating a Database

Once you have created the database (or selected an existing one), you will be shown a list of the current documents. If you create a new document, or select an existing document, you will be presented with the edit document display.

Editing documents within Futon requires selecting the document and then editing (and setting) the fields for the document individually before saving the document back into the database.

For example, the figure below shows the editor for a single document, a newly created document with a single ID, the document _id field.

Figure 1.3. Editing a Document

To add a field to the document:

1. Click Add Field.

2. In the fieldname box, enter the name of the field you want to create. For example, “company”.

3. Click the green tick next to the field name to confirm the field name change.

4. Double-click the corresponding Value cell.

5. Enter a company name, for example “Example”.

6. Click the green tick next to the field value to confirm the field value.

7. The document is still not saved as this point. You must explicitly save the document by clicking the Save Document button at the top of the page. This will save the document, and then display the new document with the saved revision information (the _rev field).

   Figure 1.4. Edited Document
   
   

The same basic interface is used for all editng operations within Futon. You must rememmbr to save the individual element (fieldname, value) using the green tick button, before then saving the document.

1.1.2. Configuring Replication

When you click the Replicator option within the Tools menu you are presented with the Replicator screen. This allows you to start replication between two databases by filling in or select the appropriate options within the form provided.

Figure 1.5. Replication Form

To start a replication process, either the select the local database or enter a remote database name into the corresponding areas of the form. Replication occurs from the database on the left to the database on the right.

If you are specifying a remote database name, you must specify the full URL of the remote database (including the host, port number and database name). If the remote instance requires authentication, you can specify the username and password as part of the URL, for example http://username:pass@remotehost:5984/demo.

To enable continuous replication, click the Continuous checkbox.

To start the replication process, click the Replicate button. The replication process should start and will continue in the background. If the replication process will take a long time, you can monitor the status of the replication using the Status option under the Tools menu.

Once replication has been completed, the page will show the information returned when the replication process completes by the API.

The Replicator tool is an interface to the underlying replication API. For more information, see Section 9.5, “POST /_replicate”. For more information on replication, see Chapter 3, Replication.

The curl utility is a command line tool available on Unix, Linux, Mac OS X and Windows and many other platforms. curl provides easy access to the HTTP protocol (among others) directly from the command-line and is therefore an ideal way of interacting with CouchDB over the HTTP REST API.

For simple GET requests you can supply the URL of the request. For example, to get the database information:

shell> curl http://127.0.0.1:5984

This returns the database information (formatted in the output below for clarity):

{
   "modules" : {
      "geocouch" : "7fd793c10f3aa667a1088a937398bc5b51472b7f"
   },
   "couchdb" : "Welcome",
   "version" : "1.1.0",
}

shell> curl 'http://couchdb:5984/_uuids?count=5'

You can explicitly set the HTTP command using the -X command line option. For example, when creating a database, you set the name of the database in the URL you send using a PUT request:

shell> curl -X PUT http://127.0.0.1:5984/demo
{"ok":true}

But to obtain the database information you use a GET request (with the return information formatted for clarity):

shell> curl -X GET http://127.0.0.1:5984/demo
{
   "compact_running" : false,
   "doc_count" : 0,
   "db_name" : "demo",
   "purge_seq" : 0,
   "committed_update_seq" : 0,
   "doc_del_count" : 0,
   "disk_format_version" : 5,
   "update_seq" : 0,
   "instance_start_time" : "1306421773496000",
   "disk_size" : 79
}

For certain operations, you must specify the content type of request, which you do by specifying the Content-Type header using the -H command-line option:

shell> curl -H 'Content-type: application/json' http://127.0.0.1:5984/_uuids

You can also submit 'payload' data, that is, data in the body of the HTTP request using the -d option. This is useful if you need to submit JSON structures, for example document data, as part of the request. For example, to submit a simple document to the demo database:

shell> curl -H 'Content-type: application/json' \
     -X POST http://127.0.0.1:5984/demo \
     -d '{"company": "Example, Inc."}'
{"ok":true,"id":"8843faaf0b831d364278331bc3001bd8",
 "rev":"1-33b9fbce46930280dab37d672bbc8bb9"}

In the above example, the argument after the -d option is the JSON of the document we want to submit.

The document can be accessed by using the automatically generated document ID that was returned:

shell> curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8
{"_id":"8843faaf0b831d364278331bc3001bd8",
 "_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
 "company":"Example, Inc."}

The API samples in the Chapter 4, CouchDB API show the HTTP command, URL and any payload information that needs to be submitted (and the expected return value). All of these examples can be reproduced using curl with the command-line examples shown above.

HTTP allows you to specify byte ranges for requests. This allows the implementation of resumable downloads and skippable audio and video streams alike. The following example uses a text file to make the range request process easier.

shell> cat file.txt
My hovercraft is full of eels!

Uploading this as an attachment to a text database using curl:

shell> curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \
    -H "Content-Type: application/octet-stream" -d@file.txt
{"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}

Requesting the whole file works as normal:

shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt
My hovercraft is full of eels!

But to retrieve only the first 13 bytes using curl:

shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt -H "Range: bytes=0-12"
My hovercraft

HTTP supports many ways to specify single and even multiple byte rangers. See RFC 2616.

The HTTP proxy feature makes it easy to map and redirect different content through your CouchDB URL. The proxy works by mapping a pathname and passing all content after that prefix through to the configured proxy address.

Configuration of the proxy redirect is handled through the [httpd_global_handlers] section of the CouchDB configuration file (typically local.ini). The format is:

[httpd_global_handlers]
PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>}

Where:

The proxy process then translates requests of the form:

http://couchdb:5984/PREFIX/path

To:

DESTINATION/path

The response is then communicated back to the original client.

For example, the following configuration:

_google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>}

Would forward all requests for http://couchdb:5984/_google to the Google website.

The service can also be used to forward to related CouchDB services, such as Lucene:

[httpd_global_handlers]
_fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}

CommonJS support allows you to use CommonJS notation inside map and reduce functions, but only of libraries that are stored inside the views part of the design doc.

So you could continue to access CommonJS code in design_doc.foo, from your list functions etc, but we'd add the ability to require CommonJS modules within map and reduce, but only from design_doc.views.lib.

There's no worry here about namespace collisions, as Couch just plucks views.*.map and views.*.reduce out of the design doc. So you could have a view called lib if you wanted, and still have CommonJS stored in views.lib.sha1 and views.lib.stemmer if you wanted.

The implementation is simplified by enforcing that CommonJS modules to be used in map functions be stored in views.lib.

A sample design doc (taken from the test suite in Futon) is below:

{
   "views" : {
      "lib" : {
         "baz" : "exports.baz = 'bam';",
         "foo" : {
            "zoom" : "exports.zoom = 'yeah';",
            "boom" : "exports.boom = 'ok';",
            "foo" : "exports.foo = 'bar';"
         }
      },
      "commonjs" : {
         "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}"
      }
   },
   "_id" : "_design/test"
}

The require() statement is relative to the design document, but anything loaded form outside of views/lib will fail.

ETags have been assigned to a map/reduce group (the collection of views in a single design document). Any change to any of the indexes for those views would generate a new ETag for all view URL's in a single design doc, even if that specific view's results had not changed.

In CouchDB 1.1 each _view URL has it's own ETag which only gets updated when changes are made to the database that effect that index. If the index for that specific view does not change, that view keeps the original ETag head (therefore sending back 304 Not Modified more often).

A database where you PUT/POST documents to trigger replications and you DELETE to cancel ongoing replications. These documents have exactly the same content as the JSON objects we used to POST to _replicate (fields source, target, create_target, continuous, doc_ids, filter, query_params.

Replication documents can have a user defined _id. Design documents (and _local documents) added to the replicator database are ignored.

The default name of this database is _replicator. The name can be changed in the local.ini configuration, section [replicator], parameter db.

{
    "_id": "my_rep",
    "source":  "http://myserver.com:5984/foo",
    "target":  "bar",
    "create_target":  true
}

[Thu, 17 Feb 2011 19:43:59 GMT] [info] [<0.291.0>] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target`
[Thu, 17 Feb 2011 19:44:37 GMT] [info] [<0.124.0>] Replication `c0ebe9256695ff083347cbf95f93e280+create_target` finished (triggered by document `my_rep`)

{
    "_id": "my_rep",
    "source":  "http://myserver.com:5984/foo",
    "target":  "bar",
    "create_target":  true,
    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
    "_replication_state":  "triggered",
    "_replication_state_time":  1297974122
}

{
    "_id": "my_rep",
    "source":  "http://myserver.com:5984/foo",
    "target":  "bar",
    "create_target":  true,
    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
    "_replication_state":  "completed",
    "_replication_state_time":  1297974122
}

[error] [<0.149.0>] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,<<"could not open http://myserver:5986/foo/">>

{
    "_id": "doc_A",
    "source":  "http://myserver.com:5984/foo",
    "target":  "bar"
}

{
    "_id": "doc_B",
    "source":  "http://myserver.com:5984/foo",
    "target":  "bar"
}

{
    "_id": "doc_B",
    "source":  "http://myserver.com:5984/foo",
    "target":  "bar",
    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280"
}

{
    "_id": "doc_A",
    "source":  "http://myserver.com:5984/foo",
    "target":  "bar",
    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
    "_replication_state":  "triggered",
    "_replication_state_time":  1297974122
}

[Thu, 17 Feb 2011 20:16:29 GMT] [info] [<0.125.0>] Stopped replication `c0ebe9256695ff083347cbf95f93e280+continuous+create_target` because replication document `doc_A` was deleted

{
    "_id": "rep_from_A",
    "source":  "http://aserver.com:5984/foo",
    "target":  "foo_a",
    "continuous":  true,
    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
    "_replication_state":  "triggered",
    "_replication_state_time":  1297971311
}
{
    "_id": "rep_from_B",
    "source":  "http://bserver.com:5984/foo",
    "target":  "foo_b",
    "continuous":  true,
    "_replication_id":  "231bb3cf9d48314eaa8d48a9170570d1",
    "_replication_state":  "triggered",
    "_replication_state_time":  1297974122
}

$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"'
"_replicator"

[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.104.0>] Stopping all ongoing replications because the replicator database was deleted or changed
[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.127.0>] 127.0.0.1 - - PUT /_config/replicator/db 200

{
    "_id": "rep_from_X",
    "source":  "http://xserver.com:5984/foo",
    "target":  "foo_x",
    "continuous":  true
}

$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"'
"another_replicator_db"

{
     "_id": "rep_from_A",
     "source":  "http://aserver.com:5984/foo",
     "target":  "foo_a",
     "continuous":  true,
     "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
     "_replication_state":  "triggered",
     "_replication_state_time":  1297971311
}
{
     "_id": "rep_from_B",
     "source":  "http://bserver.com:5984/foo",
     "target":  "foo_b",
     "continuous":  true,
     "_replication_id":  "231bb3cf9d48314eaa8d48a9170570d1",
     "_replication_state":  "triggered",
     "_replication_state_time":  1297974122
}

{
     "_id": "my_rep",
     "source":  "http://bserver.com:5984/foo",
     "target":  "bar",
     "continuous":  true,
     "user_ctx": {
          "name": "joe",
          "roles": ["erlanger", "researcher"]
     }
}

CouchDB supports the following HTTP request methods:

If you use the an unsupported HTTP request type with a URL that does not support the specified type, a 405 error will be returned, listing the supported HTTP methods. For example:

{
    "error":"method_not_allowed",
    "reason":"Only GET,HEAD allowed"
}

The CouchDB design document API and the functions when returning HTML (for example as part of a show or list) enables you to include custom HTTP headers through the headers block of the return object. For more information, see ???.

Because CouchDB uses HTTP for all communication, you need to ensure that the correct HTTP headers are supplied (and processed on retrieval) so that you get the right format and encoding. Different environments and clients will be more or less strict on the effect of these HTTP headers (especially when not present). Where possible you should be as specific as possible.

The majority of requests and responses to CouchDB use the JavaScript Object Notation (JSON) for formatting the content and structure of the data and responses.

JSON is used because it is the simplest and easiest to use solution for working with data within a web browser, as JSON structures can be evaluated and used as JavaScript objects within the web browser environment. JSON also integrates with the server-side JavaScript used within CouchDB.

JSON supports the same basic types as supported by JavaScript, these are:

Parsing JSON into a JavaScript object is supported through the eval() function in JavaScript, or through various libraries that will perform the parsing of the content into a JavaScript object for you. Libraries for parsing and generating JSON are available in many languages, including Perl, Python, Ruby, Erlang and others.

With the interface to CouchDB working through HTTP, error codes and statuses are reported using a combination of the HTTP status code number, and corresponding data in the body of the response data.

A list of the error codes returned by CouchDB, and generic descriptions of the related errors are provided below. The meaning of different status codes for specific request types are provided in the corresponding API call reference.

The components of the API URL path help determine the part of the CouchDB server that is being accessed. The result is the structure of the URL request both identifies and effectively describes the area of the database you are accessing.

As with all URLs, the individual components are separated by a forward slash.

As a general rule, URL components and JSON fields starting with the _ (underscore) character represent a special component or entity within the server or returned object. For example, the URL fragment /_all_dbs gets a list of all of the databases in a CouchDB instance.

The remainder of the URL API structure can be divided up according to the URL structure. The different sections are divided as follows:

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:

Creates a new database. The database name must be composed of one or more of the following characters:

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.

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
}

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.

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.

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.

GET /db/_changes?filter=design_doc/filtername

Request compaction of the specified database. Compaction compresses the disk database file by performing the following operations:

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 Section 5.1, “GET /db” .

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

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
}

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
}

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

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:

{
   "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"
      },
   ]
}

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

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

[
   {
      "id" : "FishStew",
      "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1"
   },
   {
      "id" : "LambStew",
      "rev" : "2-0786321986194c92dd3b57dfbfc741ce"
   },
   {
      "id" : "7f7638c86173eb440b8890839ff35433",
      "rev" : "2-bdd3bf3563bee516b96885a66c743f8e"
   }
]

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

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.

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
}

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.

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.

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 Section 6.2, “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
}

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" : [],
      "names" : [
         "mc",
         "slp"
      ]
   },
   "readers" : {
      "roles" : [],
      "names" : [
         "tim",
         "brian"
      ]
   }
}

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
}

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

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
}

Create a new document in the specified database, using the supplied JSON document structure. If the JSON structure includes the _id field, then the document will be created with the specified document ID. If the _id field is not specified, a new unique ID will be generated.

For example, you can generate a new document with a generated UUID using the following request:

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

{
   "servings" : 4,
   "subtitle" : "Delicious with fresh bread",
   "title" : "Fish Stew"
}

The return JSON will specify the automatically enerated ID and revision information:

{
   "id" : "64575eef70ab90a2b8d55fc09e00440d",
   "ok" : true,
   "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
}

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

{
   "_id" : "FishStew",
   "servings" : 4,
   "subtitle" : "Delicious with fresh bread",
   "title" : "Fish Stew"
}

{
   "id" : "FishStew",
   "ok" : true,
   "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
}

{
   "_id" : "FishStew",
   "servings" : 4,
   "subtitle" : "Delicious with fresh bread",
   "title" : "Fish Stew"
   "_attachments" : {
      "styling.css" : {
         "content-type" : "text/css",
         "data" : "cCB7IGZvbnQtc2l6ZTogMTJwdDsgfQo=",
         },
   },
}

Returns the specified doc from the specified db. For example, to retrieve the document with the id FishStew you would send the following request:

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

The returned JSON is the JSON of the document, including the document ID and revision number:

{
   "_id" : "FishStew",
   "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c",
   "servings" : 4,
   "subtitle" : "Delicious with a green salad",
   "title" : "Irish Fish Stew"
}

Unless you request a specific revision, the latest revision of the document will always be returned.

{
   "_id" : "FishStew",
   "servings" : 4,
   "subtitle" : "Delicious with fresh bread",
   "title" : "Fish Stew"
   "_attachments" : {
      "styling.css" : {
         "stub" : true,
         "content-type" : "text/css",
         "length" : 783426,
         },
   },
}

GET http://couchdb:5984/recipes/FishStew?revs=true
Accept: application/json

{
   "servings" : 4,
   "subtitle" : "Delicious with a green salad",
   "_id" : "FishStew",
   "title" : "Irish Fish Stew",
   "_revisions" : {
      "ids" : [
         "a1a9b39ee3cc39181b796a69cb48521c",
         "7c4740b4dcf26683e941d6641c00c39d",
         "9c65296036141e575d32ba9c034dd3ee"
      ],
      "start" : 3
   },
   "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
}

GET http://couchdb:5984/recipes/FishStew?revs_info=true
Accept: application/json

{
   "servings" : 4,
   "subtitle" : "Delicious with a green salad",
   "_id" : "FishStew",
   "_revs_info" : [
      {
         "status" : "available",
         "rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
      },
      {
         "status" : "available",
         "rev" : "2-7c4740b4dcf26683e941d6641c00c39d"
      },
      {
         "status" : "available",
         "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
      }
   ],
   "title" : "Irish Fish Stew",
   "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
}

GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d
Accept: application/json

{
   "_id" : "FishStew",
   "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d",
   "servings" : 4,
   "subtitle" : "Delicious with a green salad",
   "title" : "Fish Stew"
}

Returns the HTTP Headers containing a minimal amount of information about the specified document. The method supports the same query arguments as the GET method, but only the header information (including document size, and the revision as an ETag), is returned. For example, a simple HEAD request:

HEAD http://couchdb:5984/recipes/FishStew
Content-Type: application/json

Returns the following HTTP Headers:

HTTP/1.1 200 OK
Server: CouchDB/1.0.1 (Erlang OTP/R13B)
Etag: "7-a19a1a5ecd946dad70e85233ba039ab2"
Date: Fri, 05 Nov 2010 14:54:43 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 136
Cache-Control: must-revalidate

The Etag header shows the current revision for the requested document, and the Content-Length specifies the length of the data, if the document were requested in full.

Adding any of the query arguments (as supported by GET method), then the resulting HTTP Headers will correspond to what would be returned. Note that the current revision is not returned when the refs_info argument is used. For example:

HTTP/1.1 200 OK
Server: CouchDB/1.0.1 (Erlang OTP/R13B)
Date: Fri, 05 Nov 2010 14:57:16 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 609
Cache-Control: must-revalidate

The PUT method creates a new named document, or creates a new revision of the existing document. Unlike the POST method, you must specify the document ID in the request URL.

For example, to create the docment FishStew, you would send the following request:

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

{
  "servings" : 4,
  "subtitle" : "Delicious with fresh bread",
  "title" : "Fish Stew"
}

The return type is JSON of the status, document ID,and revision number:

{
   "id" : "FishStew",
   "ok" : true,
   "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
}

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

{
  "_rev" : "1-9c65296036141e575d32ba9c034dd3ee",
  "servings" : 4,
  "subtitle" : "Delicious with fresh salad",
  "title" : "Fish Stew"
}

PUT http://couchdb:5984/recipes/FishStew
If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea
Content-Type: application/json

{
   "servings" : 4,
   "subtitle" : "Delicious with fresh salad",
   "title" : "Fish Stew"
}

{
   "id" : "FishStew99",
   "ok" : true,
   "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea"
}

Deletes the specified document from the database. You must supply the current (latest) revision, either by using the rev parameter to specify the revision:

DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c
Content-Type: application/json

Alternatively, you can use ETags with the If-Match field:

DELETE http://couchdb:5984/recipes/FishStew
If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c
Content-Type: application/json

The returned JSON contains the document ID, revision and status:

{
   "id" : "FishStew",
   "ok" : true,
   "rev" : "4-2719fd41187c60762ff584761b714cfb"
}

The COPY command (which is non-standard HTTP) copies an existing document to a new or existing document.

The source document is specified on the request line, with the Destination HTTP Header of the request specifying the target document.

COPY http://couchdb:5984/recipes/FishStew
Content-Type: application/json
Destination: IrishFishStew

{
   "id" : "IrishFishStew",
   "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
}

COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082
Content-Type: application/json
Destination: IrishFishStew

COPY http://couchdb:5984/recipes/FishStew
Content-Type: application/json
Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee

{
   "id" : "IrishFishStew",
   "rev" : "2-55b6a1b251902a2c249b667dab1c6692"
}

Returns the file attachment attachment associated with the document doc. The raw data of the associated attachment is returned (just as if you were accessing a static file. The returned HTTP Content-type will be the same as the content type set when the document attachment was submitted into the database.

Upload the supplied content as an attachment to the specified document (doc). The attachment name provided must be a URL encoded string. You must also supply either the rev query argument or the If-Match HTTP header for validation, and the HTTP headers (to set the attacment content type). The content type is used when the attachment is requested as the corresponding content-type in the returned document header.

For example, you could upload a simple text document using the following request:

PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca
Content-Length: 10
Content-Type: text/plain

Roast it

Or by using the If-Match HTTP header:

PUT http://couchdb:5984/recipes/FishStew/basic
If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca
Content-Length: 10
Content-Type: text/plain

Roast it

The returned JSON contains the new document information:

{
   "id" : "FishStew",
   "ok" : true,
   "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74"
}

Deletes the attachment attachment to the specified doc. You must supply the rev argument with the current revision to delete the attachment.

For example to delete the attachment basic from the recipe FishStew:

DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74
Content-Type: application/json

The returned JSON contains the updated revision information:

{
   "id" : "FishStew",
   "ok" : true,
   "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e"
}

Gets the specified local document. The semantics are identical to accessing a standard document in the specified database, except that the document is not replicated. See Section 6.2, “GET /db/doc”.

Stores the specified local document. The semantics are identical to storing a standard document in the specified database, except that the document is not replicated. See Section 6.4, “PUT /db/doc”.

Deletes the specified local document. The semantics are identical to deleting a standard document in the specified database, except that the document is not replicated. See Section 6.5, “DELETE /db/doc”.

Copies the specified local document. The semantics are identical to copying a standard document in the specified database, except that the document is not replicated. See Section 6.6, “COPY /db/doc”.

Returns the specified design document, design-doc from the specified db. For example, to retrieve the design document recipes you would send the following request:

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

The returned string will be the JSON of the design document:

{
   "_id" : "_design/recipes",
   "_rev" : "5-39f56a392b86bbee57e2138921346406"
   "language" : "javascript",
   "views" : {
      "by_recipe" : {
         "map" : "function(doc) { if (doc.title != null) emit(doc.title, doc) }"
      },
   },
}

A list of the revisions can be obtained by using the revs query argument, or an extended list of revisions using the revs_info query argument. This operates in the same way as for other documents. Fur further examples, see Section 6.2, “GET /db/doc”.

Upload the specified design document, design-doc, to the specified database. The design document should follow the definition of a design document, as summarised in the following table.

For more information on writing views, see ???.

Delete an existing design document. Deleting a design document also deletes all of the associated view indexes, and recovers the corresponding space on disk for the indexes in question.

To delete, you must specify the current revision of the design document using the rev query argument.

For example:

DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8
Content-Type: application/json

The response contains the delete document ID and revision:

{
   "id" : "recipe/_design/recipes"
   "ok" : true,
   "rev" : "3-7a05370bff53186cb5d403f861aca154",
}

The COPY command (non-standard HTTP) copies an existing design document to a new or existing document.

The source design document is specified on the request line, with the Destination HTTP Header of the request specifying the target document.

COPY http://couchdb:5984/recipes/_design/recipes
Content-Type: application/json
Destination: /recipes/_design/recipelist

{
   "id" : "recipes/_design/recipelist"
   "rev" : "1-9c65296036141e575d32ba9c034dd3ee",
}

COPY http://couchdb:5984/recipes/_design/recipes?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5
Content-Type: application/json
Destination: recipes/_design/recipelist

COPY http://couchdb:5984/recipes/_design/recipes
Content-Type: application/json
Destination: recipes/_design/recipelist?rev=1-9c65296036141e575d32ba9c034dd3ee

{
   "id" : "recipes/_design/recipes"
   "rev" : "2-55b6a1b251902a2c249b667dab1c6692",
}

Returns the file attachment attachment associated with the design document /_design_/design-doc. The raw data of the associated attachment is returned (just as if you were accessing a static file. The returned HTTP Content-type will be the same as the content type set when the document attachment was submitted into the database.

Upload the supplied content as an attachment to the specified design document (/_design/design-doc). The attachment name provided must be a URL encoded string. You must also supply either the rev query argument or the If-Match HTTP header for validation, and the HTTP headers (to set the attacment content type). The content type is used when the attachment is requested as the corresponding content-type in the returned document header.

For example, you could upload a simple text document using the following request:

PUT http://couchdb:5984/recipes/_design/recipes/view.css?rev=7-f7114d4d81124b223283f3e89eee043e
Content-Length: 39
Content-Type: text/plain

div.recipetitle {
font-weight: bold;
}

Or by using the If-Match HTTP header:

PUT http://couchdb:5984/recipes/FishStew/basic
If-Match: 7-f7114d4d81124b223283f3e89eee043e
Content-Length: 39
Content-Type: text/plain

div.recipetitle {
font-weight: bold;
}

The returned JSON contains the new document information:

{
   "id" : "_design/recipes"
   "ok" : true,
   "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5",
}

Deletes the attachment attachment to the specified _design/design-doc. You must supply the rev argument with the current revision to delete the attachment.

For example to delete the attachment view.css from the design document recipes:

DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a

The returned JSON contains the updated revision information for the parent document:

{
   "id" : "_design/recipes"
   "ok" : true,
   "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c",
}

Obtains information about a given design document, including the index, index size and current status of the design document and associated index information.

For example, to get the information for the recipes design document:

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

This returns the following JSON structure:

{
   "name" : "recipes"
   "view_index" : {
      "compact_running" : false,
      "updater_running" : false,
      "language" : "javascript",
      "purge_seq" : 10,
      "waiting_commit" : false,
      "waiting_clients" : 0,
      "signature" : "fc65594ee76087a3b8c726caf5b40687",
      "update_seq" : 375031,
      "disk_size" : 16491
   },
}

The individual fields in the returned JSON structure are detailed in Table 8.3, “Design Document Info JSON Contents”.

Executes the specified view-name from the specified design-doc design document.