couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Couchdb Wiki] Update of "Views" by NoahSlater
Date Sat, 29 Mar 2008 18:59:33 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The following page has been changed by NoahSlater:

The comment on the change is:
Copied from original CouchDB wiki

New page:
A simple introduction to CouchDB views.

== Concept ==

Views are the primary tool used for querying and reporting on CouchDB documents. There are
two different kinds of views: permanent and temporary views.

'''Permanent views''' are stored inside special documents called design documents, and can
be accessed via an HTTP ''GET'' request to the URI ''/{dbname}/{docid}/{viewname}'', where
''{docid}'' has the prefix ''_view/'' so that CouchDB recognizes the document as a design

'''Temporary views''' are not stored in the database, but rather executed on demand. To execute
a temporary view, you make an HTTP ''POST'' request to the URI ''/{dbname}/_temp_view'', where
the body of the request contains the code of the view function and the ''Content-Type'' header
is set to ''text/javascript''.

For both kinds of views, the view is defined by a !JavaScript function that maps view keys
to values (although it is possible to use other languages than !JavaScript by plugging in
third-party view servers).

Note that views are not created when a document is saved, but rather, when it is accessed.
As a result, the first access might take some time depending on the size of your data while
CouchDB creates the view.

== Basics ==

Here is the simplest example of a view function:

function(doc) {
  map(null, doc);

This function defines a table that contains all the documents in a CouchDB database, with
no particular key.

A view function should accept a single argument: the document object. To produce results,
it should call the implicitly available ''map(key, value)'' function. For every invocation
of that function, a result row is added to the view (if neither the ''key'' nor the ''value''
are undefined). As documents are added, edited and deleted, the rows in the computed table
are updated automatically.

Here is a slightly more complex example of a function that defines a view on values computed
from customer documents:

function(doc) {
  if (doc.Type == "customer") {
    map(null, {LastName: doc.LastName, FirstName: doc.FirstName, Address: doc.Address});

For each document in the database that has a Type field with the value ''customer'', a row
is created in the view. The ''value'' column of the view contains the ''!LastName'', ''!FirstName'',
and ''Address'' fields for each document. The key for all the documents is null in this case.

To be able to filter or sort the view by some document property, you would use that property
for the key. For example, the following view would allow you to lookup customer documents
by the ''!LastName'' or ''!FirstName'' fields:

function(doc) {
  if (doc.Type == "customer") {
    map(doc.LastName, {FirstName: doc.FirstName, Address: doc.Address});
    map(doc.FirstName, {LastName: doc.LastName, Address: doc.Address});

Here is an example of the results of such a view:

       "value":{"FirstName":"Damien", "Address":"2407 Sawyer drive, Charlotte NC"}
       "value":{"LastName":"Katz", "Address":"2407 Sawyer drive, Charlotte NC"}
       "value":{"FirstName":"Wayne", "Address":"123 Fake st., such and such"}
       "value":{"LastName":"Kerr", "Address":"123 Fake st., such and such"}

''This example output was reformatted for readability.''

== Lookup Views ==

The second parameter of the ''map()'' function can be ''NULL''. CouchDB then only stores the
key in the view. If you use the document's ID here, you can use the view as a compact lookup
mechanism and fetch the document's details, if needed, in subsequent requests.

== Complex Keys ==

Keys are not limited to simple values. You can use arbitrary JSON values to influence sorting.
See ViewCollation for the rules.

== Views in Practice ==

See HttpViewApi to learn how to work with views.

View raw message