Mercurial > browser-couch

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
  <link rel="stylesheet" type="text/css" media="all"
        href="css/tutorial.css" />
  <title>BrowserCouch Tutorial</title>
</head>
<body>
<div id="content" class="documentation">
<h1>BrowserCouch Tutorial</h1>

<p>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 <a class="intra-wiki" href="index.html">introduction</a>
to learn more about why this style of querying is being explored as an
alternative to SQL for client-side Web Storage.</p>

<p>It should also be noted that BrowserCouch is by no means "mature"
software. It currently lacks a lot of CouchDB's features that it ought
to have, and its API is not stable at all.</p>

<p>Finally, a note about the code examples in this tutorial: they're
actually being executed in your browser, and their output is sometimes
being displayed in this tutorial too. While this helps ensure that the
software is working as intended and also allows for some <a
class="intra-wiki" href="#try">interactive learning opportunities</a>,
right now it also means that some parts of the code examples may look
a bit unusual. Furthermore, if you see any conspicuously blank areas
in this tutorial, it could be because the tutorial code
crashed&mdash;our apologies if this occurs.</p>

<p>With that out of the way, let's get started.</p>

<h1>Getting Started</h1>

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

<div class="example-code">
BrowserCouch.get('blog-posts',
                 function onRetrieveCb(db) {
                   blogDb = db; /* Save the DB for later. */ DONE();
                 },
                 new FakeStorage());
</div>

<p>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.</p>

<p>The third parameter specifies the engine that will be used to
persistently store our database across browsing sessions. In this case
we're using <tt>FakeStorage</tt>, 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.</p>

<p>If the database doesn't already exist, an empty one will be created
for us. Putting blog posts into the database is done through the
<tt>put()</tt> method like so:</p>

<div class="example-code">
blogDb.put(
  [{id: 0, author: 'Myk', title: 'Burritos', content: 'Burritos are yum.'},
   {id: 1, author: 'Thunder', title: 'Bacon', content: 'I like bacon.'},
   {id: 2, author: 'Thunder', title: 'Beer', content: 'Beer is good too.'}],
  function onDone() { /* Do stuff... */ DONE();}
);
</div>

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

<h1>Views</h1>

<p>Now that we've put some data into our database, we can play around
with generating views on the data using the <a
href="http://en.wikipedia.org/wiki/MapReduce">MapReduce</a> mechanism.
For instance, here's an ad-hoc view using only the map phase that
organizes all the post titles by author:</p>

<div class="example-code">
blogDb.view({
  map: function(doc, emit) {
    emit(doc.author, doc.title);
  },
  finished: function(result) {
    displayInElement(result, 'author-keyed-view'); DONE();
  }
});
</div>

<p>The <tt>view()</tt> method above has lots of optional arguments,
which is why we're passing in a single object with keys corresponding
to argument names. The <tt>map</tt> argument is the function to use
for the map phase, and the <tt>finished</tt> argument is the callback
to pass the view results into when processing is complete.</p>

<p>The output placed in the <tt>author-keyed-view</tt> element is:</p>

<div class="example-output" id="author-keyed-view"></div>

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

<p>At this point you may want to jump to the <a class="intra-wiki"
href="#try">Try It For Yourself</a> section to play around with making
your own <tt>map()</tt> functions.</p>

<p>The reduce phase of a view is totally optional and a little
confusing. Let's try adding a <tt>reduce()</tt> function to our
earlier view to group together the blog post titles with the
authors:</p>

<div class="example-code">
blogDb.view({
  map: function(doc, emit) {
    emit(doc.author, doc.title);
  },
  reduce: function(keys, values) {
    return values;
  },
  finished: function(result) {
    authors = result; /* Save the result for later. */
    displayInElement(authors, 'author-titles-view'); DONE();
  }
});
</div>

<p>The output is as follows:</p>

<div class="example-output" id="author-titles-view"></div>

<p>Essentially, BrowserCouch takes all the rows generated by
<tt>map()</tt> 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 <tt>values</tt> argument passed to
<tt>reduce()</tt> is.</p>

<p>The <tt>keys</tt> argument is a list of 2-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.</p>

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

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

<div class="example-code">
var rowIndex = authors.findRow('Thunder');
displayInElement(authors.rows[rowIndex], 'author-find-row-view');
</div>

<p>The output for this one is:</p>

<div class="example-output" id="author-find-row-view"></div>

<a name="try"><h1>Try It For Yourself</h1></a>

<p>If your eyes are crossed right now, no worries&mdash;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.</p>

<p>You can use the text field below to do just that. Just press the
tab key when you're done making changes to recompute the view.</p>

<textarea class="example-code try-code">
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'); DONE();
  }
});
</textarea>

<p>Here's the output to the above view:</p>

<div class="example-output" id="try-my-view"></div>

<h1>Where To Go From Here</h1>

<p>There's features in the API that aren't covered here, so check out
the check out the <a class="intra-wiki"
href="index.html#js/tests.js">test suite's annotated source code</a>
for more examples.</p>

<script src="js/ext/jquery.js"></script>
<script src="js/browser-couch.js"></script>
<script src="js/tutorial.js"></script>
</body>
</html>
author	Atul Varma <varmaa@toolness.com>
date	Tue, 21 Apr 2009 12:13:18 -0700
parents	af36b00306d0
children