We have a new wiki. The migration is not 100% complete. You can help out by moving pages across. This wiki will exist for as long as there are pages left.

The official documentation has moved to http://docs.couchdb.org — The transition is not 100% complete, but http://docs.couchdb.org should be seen as having the latest info. In some cases, the wiki still has some more or older info on certain topics inside CouchDB.

View Server

The View Server

CouchDB delegates computation of Views to external query servers. It communicates with them over standard input/output, using a very simple, line-based protocol. The default query server is written in Javascript, running via Mozilla SpiderMonkey. You can use other languages by setting a MIME type in the language property of a design document or the Content-Type header of a temporary view. Design documents that do not specify a language property are assumed to be of type javascript, as are ad hoc queries that are POSTed to _temp_view without a Content-Type header.

To register query servers with CouchDB, add a line for each server to local.ini. The basic syntax is:

Basic API

This shows you how the view server implementation for your language should behave. If in doubt, look at the share/server/main.js file in your CouchDB source tree for reference.

CouchDB launches the view server and starts sending commands. The server responds according to its evaluation of the commands. There are only three commands the view server needs to understand.

reset

This resets the state of the view server and makes it forget all previous input. If applicable, this is the point to run garbage collection.

CouchDB sends:

["reset"]\n

The view server responds:

true\n

add_fun

When creating a view, the view server gets sent the view function for evaluation. The view server should parse/compile/evaluate the function he receives to make it callable later. If this fails, the view server returns an error. CouchDB might store several functions before sending in any actual documents.

When the view server can evaluate the function and make it callable, it returns:

true\n

If not:

{"error": "some_error_code", "reason": "error message"}\n

map_doc

When the view function is stored in the view server, CouchDB starts sending in all the documents in the database, one at a time. The view server calls the previously stored functions one after another with the document and stores its result. When all functions have been called, the result is returned as a JSON string.

reduce

If the view has a reduce function defined, CouchDB will enter into the reduce phase. The view server will receive a list of reduce functions and some map results on which it can apply them. The map results are given in the form [[key, id-of-doc], value].

Note that even though the view server receives the map results in the form [[key, id-of-doc], value], the function may receive them in a different form. For example, the JavaScript view-server applies functions on the list of keys and the list of values.

rereduce

When building a view, CouchDB will apply the reduce step directly to the output of the map step and the rereduce step to the output of a previous reduce step.

CouchDB will send a list of values, with no keys or document ids, to the rereduce step.

CouchDB sends:

["rereduce",["function(k, v, r) { return sum(v); }"],[33,55,66]]\n

The view-server answers:

[true,[154]]\n

log

At any time, the view-server may send some information that will be saved in CouchDB's log file. This is done by sending a special object with just one field, log, on a separate line.