Differences between revisions 1 and 2
Revision 1 as of 2009-02-22 02:06:23
Size: 1538
Editor: c-76-115-0-4
Comment: documented show functions
Revision 2 as of 2009-02-22 02:27:17
Size: 2994
Editor: c-76-115-0-4
Comment: documentation for list funs
Deletions are marked like this. Additions are marked like this.
Line 36: Line 36:

List funcitons are stored under the `lists` key of design documents. Here's an example desgin doc with list functions:

{{{
{
"_id" : "_design/examples",
"views" {
  "posts-by-date" : "function(doc){...}",
  "posts-by-tag" : "function(doc){...}",
  "people-by-name" : "function(doc) {...}"
},
"lists" : {
  "index-posts" : "function(head, row, req, row_info) {...}",
  "browse-people" : "function(head, row, req, row_info) { ... }"
}
}}}

These lists are run by querying URLs like:

{{{
GET /db/_list/examples/index-posts/posts-by-date?descending=true&limit=10

GET /db/_list/examples/index-posts/posts-by-tag?key="howto"

GET /db/_list/examples/browse-people/people-by-name?startkey=["a"]&limit=10

}}}

List functions have a more interesting signature, as they are passed the head of the view on first invocation, then each row in turn, then called once finally for the tail of the view. They also have the ability to abort iteration early, which is handy for some filtering operations.

Example list function:

{{{
function(head, row, req, row_info) {
  if (head) {
    return "<p>head: "+JSON.stringify(head)+"</p><ul>"";
  } else if (row) {
    return "<li>"+JSON.stringify(row)+"</li>";
  } else {
    return "</ul><h4>the tail</h4>"
  }
}
}}}

Hopefully that gets you enough to get started. For a more complete set of examples, see the CouchDB test suite, especially show_documents.js and list_views.js

The basics of formatting documents using show and list functions. These functions convert documents and views, respectively, into non-JSON formats. The rows of each view are processed individually, which keeps long lists from becoming memory hogs.

They are designed to be cacheable. CouchDB handles generating Etags for show and list responses.

Show and list functions are side effect free and idempotent. They can not make additional HTTP requests against CouchDB. Their purpose is to render JSON documents in other formats.

Showing Documents

Show functions are stored in your design document, under the shows key. Here's an example set of show functions:

{
"_id" : "_design/examples",
"shows" : {
  "posts" : "function(doc, req) {... return responseObject;}",
  "people" : "function(doc, req) { ... }"
}

These functions could be queried like this:

GET /db/_show/examples/posts/somedocid

GET /db/_show/examples/people/otherdocid

GET /db/_show/examples/people/otherdocid?format=xml&details=true

The show function is run with two arguments, the first is the document corresponding to the requested docid. The second argument is the req object, which contains information about the query string, Accept headers, and other per-request information.

The show function returns a JSON object of the same format of the _external response. See ExternalProcesses for further explanation of the req object as well as documentation about the response.

Listing Views

List funcitons are stored under the lists key of design documents. Here's an example desgin doc with list functions:

{
"_id" : "_design/examples",
"views" {
  "posts-by-date" : "function(doc){...}",
  "posts-by-tag" : "function(doc){...}",
  "people-by-name" : "function(doc) {...}"
},
"lists" : {
  "index-posts" : "function(head, row, req, row_info) {...}",
  "browse-people" : "function(head, row, req, row_info) { ... }"
}

These lists are run by querying URLs like:

GET /db/_list/examples/index-posts/posts-by-date?descending=true&limit=10

GET /db/_list/examples/index-posts/posts-by-tag?key="howto"

GET /db/_list/examples/browse-people/people-by-name?startkey=["a"]&limit=10

List functions have a more interesting signature, as they are passed the head of the view on first invocation, then each row in turn, then called once finally for the tail of the view. They also have the ability to abort iteration early, which is handy for some filtering operations.

Example list function:

function(head, row, req, row_info) {
  if (head) {
    return "<p>head: "+JSON.stringify(head)+"</p><ul>"";
  } else if (row) {
    return "<li>"+JSON.stringify(row)+"</li>";
  } else {
    return "</ul><h4>the tail</h4>"
  }
}

Hopefully that gets you enough to get started. For a more complete set of examples, see the CouchDB test suite, especially show_documents.js and list_views.js