Skip to content

Fixes #36 - Add support for CouchDB lists #37

merged 2 commits into from Apr 2, 2012

2 participants


If a list is specified in config.list_name or a collection's db.list attribute, the collection will be built based on the list.

If no list is specified, the collection is based on the specified view, as in the previous version.

@kurtmilam kurtmilam Added Support for CouchDB Lists
If a list is specified in config.list_name or a collection's db.list
attribute, the collection will be built based on the list.

A note on implementation - your list function should return a stringified object containing a rows array. In short, the JSON returned by the list function should look similar to the JSON returned by a normal view.

Example list function:

function(head, req) {
    var row, obj = {rows:[]};
    while (row = getRow()){
    //One Model per row in obj.rows will be added to the Collection

Also: If you wish to base a collection on a list, you should still supply a view name for the list to be executed against, just as you normally would when querying a CouchDB list.

Testing: I have tested the javascript version of this. I made the coffeescript changes by hand, but have not yet tested them. (haven't started working with coffeescript yet)

Why would I want to use a list rather than a view?
CouchDB lists offer access to environment variables and querystring params that are not available to views. This includes things like the userCtx (the user name of the user who's executing the query). Using a list, you can filter the records returned by the underlying view based on the user who's making the request, or based on other querystring params that you send with your call to the list.

Most of the documentation I've read about CouchDB lists talks about transforming a view's JSON into HTML, XML or some other format. What's often not mentioned is that you can also use a list to transform a view's JSON into JSON, as well - this is probably the most interesting use w/r/t Backbone.js apps.

Example list function that filters records based on the current user:

//This example assumes your docs have a top-level key called 'documentOwner' whose value matches 
//the 'name' key of one of the users defined in your '_users' database
function(head, req) {
    var row,
        obj = {rows:[]},
        currentUser =;
    while (row = getRow()){
        if (row.value.documentOwner === currentUser)
    //In this example, one model per doc where doc.documentOwner = the name of the current user
    //will be added to the collection
@kurtmilam kurtmilam Fixes #36 - Add Support for CouchDB Lists
Oops - left out one important 'if' in the previous commit. Should be working
in .js and .coffee now.

The second commit is the correct one - it contains all of the changes from the first, plus an important if that I left out initially.


Thx for this addition, didn't know that you can use lists in that way :).
Can I take the text in your comment above and put it in the document at ?

@janmonschke janmonschke merged commit a8e8afd into janmonschke:master Apr 2, 2012

Feel free to reuse my text, but I should add that I discussed this use of lists with some CouchDB experts on #couchdb, and they informed me that this should be used sparingly - only where it's impossible to get the same results with a view. The reason for this is that views are prepared beforehand, but lists must be built each time they're called.

In short, if you need JSON, use a view whenever possible, and only use a list when there's no way to get the same results with a view.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.