Examples of CouchDB Usage

A few months ago, I gave a presentation to the local PHP group on CouchDB. For some background information, see my previous blog post about CouchDB and key-value data stores. Today I would like to provide a little more information on CouchDB along with a few examples.

CouchDB uses a RESTful API for queries and returns information in JSON. In my database, I set up an example database named phpug that models how CouchDB may be used to store events for an events calendar. I populated the database with random events occurring between 2009 and 2012 and belonging to a few different categories. Here are some example queries.

When no parameters are sent to the database, it returns a welcome message and the version.

URI: http://db.exampledomain.com/
Response:

{
	"couchdb":"Welcome",
	"version":"0.8.0-incubating"
}

When a database is added to the URI, statistics for that database are returned.

URI: http://db.exampledomain.com/phpug
Response:

 {
	"db_name":"phpug",
	"doc_count":0,
	"doc_del_count":0,
	"update_seq":0,
	"compact_running":false,
	"disk_size":4096
}

Finally, when an id is added to the URI, the document associated with that identifier is returned. Note the _id and _rev fields. The _id holds the identifier for the document. This can either be set or automatically generated. In this case, the populate script I used created the id. _rev denotes the revision of the current document.

URI: http://db.exampledomain.com/phpug/meeting-2009-09-24
Response:

 {
	"_id":"meeting-2009-09-24",
	"_rev":"4184112083",
	"location":"Kelly's",
	"time":"19:00",
	"date":"2009-09-24"
}

Views are an important way to bring back specific data in CouchDB. They could be considered somewhat equivalent to the WHERE clause in SQL. The following view was setup to bring back data by date and type (I have only included one meeting type in the example below) as well as provide a count of events in the database.

{
	"date": {
		"map": "function(doc) {
			emit(doc.date, doc);
		}"
	},
	"meetings": {
		"map": "function(doc) {
			if( doc.category == 'Meeting' ) {
				emit( doc.date, doc );
			}
		}"
	},
	"counts" : {
		"map": "function(doc) {
			emit( doc.date, 1 );
		}",
		"reduce": "function( keys, values ) {
			return sum(values);
		}"
	}
}

Bring back all results sorted by date:

http://db.exampledomain.com/phpug_calendar/_view/cal_views/date

Bring back results for a specific day (February 10, 2009):

http://db.exampledomain.com/phpug_calendar/_view/cal_views/date?key=”2009-2-10″

Bring back results for a range (2010):

http://db.exampledomain.com/phpug_calendar/_view/cal_views/date
?startkey=”2010-1-1″
&endkey=”2010-12-31″

Bring back first 5 results from the previous results:

http://db.exampledomain.com/phpug_calendar/_view/cal_views/date
?startkey=”2010-1-1″
&endkey=”2010-12-31″
&count=5

Get second page of results (from past two examples)

http://db.exampledomain.com/phpug_calendar/_view/cal_views/date
?startkey=”2010-1-1″
&endkey=”2010-12-31″
&count=5
&skip=5

(It is more efficient to keep using count and startkey_docid than skip=5 for large datasets)

Get the first 5 meetings

http://db.exampledomain.com/phpug_calendar/_view/cal_views/meetings
?count=5

Get the number of events on a specific day

http://db.exampledomain.com/phpug_calendar/_view/cal_views/counts
?key=”2009-2-10″

I have glossed over a few details such as the purpose of _rev, and how map/reduce/rereduce works, but this time I just wanted to show a few examples of how CouchDB works. For all the details, head over to the CouchDB site where there is plenty of documentation on how everything works.