GETting Documents From CouchDB

To start off, here are the links to my previous posts about CouchDB:

1. Relaxing on the Couch(DB)
2. Installing the Couch(DB)
3. PUTting the Couch(DB) in Your Living Room

In my latest post, I explained how easy it is to create and manage documents in CouchDB. Today, I want to talk about how to retrieve a document from CouchDB.

In order to retrieve a document from CouchDB, we make use of the HTTP GET operation (duh). Using the GET method for retrieving a document takes the following general form:

http://myhost:5984/my_database/my_id

Its as simple as that. So, for example, sending the following request:

GET /documentstore/96f49e5a-6b5b-47ed-9234-9a98d600013e

makes CouchDB return the following response:

{
"_id":"96f49e5a-6b5b-47ed-9234-9a98d600013e",
"_rev":"2-1534297415",
"Author":"Stephen Hawking",
"Title":"The Universe in a Nutshell",
"Tags":[{"Name":"Physics"},{"Name":"Universe"},{"Name":"Space"}]
}

As already mentioned, CouchDB provides MVCC (multi-version concurrency control) for the documents it stores. Using the GET operation makes it possible to take advantage of this built-in feature. Notice that the first digit of the revision number in the example above indicates that this is the second version of the document we retrieved. This means that CouchDB possibly has an earlier version of the document. In order to find out what revisions are available, we can issue the following request:

GET /documentstore/96f49e5a-6b5b-47ed-9234-9a98d600013e?revs=true

CouchDB returns the current revision of the document as before, but now with an additional field named _revisions:

{
"_id":"96f49e5a-6b5b-47ed-9234-9a98d600013e",
"_rev":"2-1534297415",
"Author":"Stephen Hawking",
"Title":"The Universe in a Nutshell",
"Tags":[{"Name":"Physics"},{"Name":"Universe"},{"Name":"Space"}],
"_revisions":{"start":2,"ids":["1534297415","3158114761"]},
}

In order to retrieve the first revision of our document, we can send the following request to retrieve it:

GET /documentstore/96f49e5a-6b5b-47ed-9234-9a98d600013e?rev=1-3158114761

As expected, CouchDB now returns the first revision of the document:

{
"_id":"96f49e5a-6b5b-47ed-9234-9a98d600013e",
"_rev":"1-3158114761",
"Author":"Stephen Hawking",
"Title":"The Universe in a Nutshell",
"Tags":[{"Name":"Physics"},{"Name":"Universe"}]
}

It seems that for the second revision of the document, we have added an extra tag. Having this kind of automatic versioning for your data is a really nice feature in my book.

For my next post, I will talk about how to delete a document from CouchDB..

Till next time