Using BrowserCouch

This is a brief introduction to using the BrowserCouch API and the MapReduce mechanism. If you haven't already read it, you may want to check out the introduction to learn more about why this style of querying is being explored as an alternative to SQL for client-side Web Storage.

Suppose we want to add offline support for a blog. To get a database called blog-posts in BrowserCouch, you can use the following function:

BrowserCouch.get('blog-posts', onRetrieveCb, new FakeStorage());

It's clear that the first parameter is the name of the database we want; the second parameter is the callback that will be passed the database once it's fetched.

The third parameter specifies the engine that will be used to persistently store our database across browsing sessions. In this case we're using FakeStorage, which just stores everything non-persistently in memory for the sake of example. We could just as easily leave out the third parameter to have BrowserCouch figure out the best storage backend based on our browser's capabilities.

If the database doesn't already exist, an empty one will be created for us. Putting blog posts into the database can be done via an onRetrieveCb() function like this:

Every item we put into our database needs to have an id attribute, but aside from that, the item can contain any JSON-encodable data.

Now that we've put some data into our database, we can play around with generating views on the data using the MapReduce mechanism. For instance, here's an ad-hoc view using only the map phase that organizes all the post titles by author:

function onPutCb() { blogDb.view({ map: function(doc, emit) { emit(doc.author, doc.title); }, finished: function(result) { displayInElement(result, 'author-keyed-view'); tryAnotherView(); } }); }

The output placed in the author-keyed-view element is:

As you can see, BrowserCouch essentially iterated over all of the blog posts, passing each one to map(), along with an arbitrary function called emit(). The map() function then emitted key-value pairs which show up in the view. It's worth noting that map() can call emit() as much as it wants to; each call will add a new row to the view.

We could also try creating another view that adds a reduce() function to group together the blog post titles with the authors:

The output is as follows:

The reduce() mechanism is a bit harder to understand. Essentially, BrowserCouch takes all the rows generated by map() and generates a new list of key-value rows, where the value of each row is the list of all values that match the row's key. This explains what the values argument passed to reduce() is.

The keys argument is a list of two-tuples, the first of which is the key, and the second of which is the document id that emitted the key during the map phase.

The reduce() function is called for each unique key, and its return value is the value for its key in the final view.

Once you've got a view, you can use the view's findRow() method to find the first row whose key matchest (or is closest to) the one you provide. For example:

function findRows(result) { var rowIndex = result.findRow('Thunder'); displayInElement(result.rows[rowIndex], 'author-find-row-view'); tryMyView(); }

The output for this one is:

Now You Try!

If your eyes are crossed right now, no worries—most people take a long time to understand exactly what MapReduce is doing. That said, the easiest way to understand how MapReduce works is just to play around with creating your own view.

So, to get a better feel for how MapReduce works, you can use the text field below to try making your own view. Just press the tab key when you're done making changes to recompute the view.

function tryMyView() {
  blogDb.view({
    map: function(doc, emit) {
      emit(doc.author, doc.title);
    },
    reduce: function(keys, values) {
      return values;
    },
    finished: function(result) {
      displayInElement(result, 'try-my-view');
    }
  });
}

Here's the output to the above view:

Where To Go From Here

There's features in the API that aren't covered here, so check out the check out the annotated source code for the test suite for more sample code.