3.8. Query Servers

3.8.1. Query Servers Definition

[query_servers]

Changed in version 1.2:: Added CoffeeScript query server

CouchDB delegates computation of design documents functions to external query servers. The external query server is a special OS process which communicates with CouchDB over standard input/output using a very simple line-based protocol with JSON messages.

The external query server may be defined in configuration file following next pattern:

[query_servers]
LANGUAGE = PATH ARGS

Where:

  • LANGUAGE: is a programming language which code this query server may execute. For instance, there are python, ruby, clojure and other query servers in wild. This value is also used for ddoc field language to determine which query server processes the functions.

    Note, that you may setup multiple query servers for the same programming language, but you have to name them different (like python-dev etc.).

  • PATH: is a system path to the executable binary program that runs the query server.

  • ARGS: optionally, you may specify additional command line arguments for the executable PATH.

The default query server is written in JavaScript, running via Mozilla SpiderMonkey:

[query_servers]
javascript = /usr/bin/couchjs /usr/share/couchdb/server/main.js
coffeescript = /usr/bin/couchjs /usr/share/couchdb/server/main-coffee.js

See also

Native Erlang Query Server that allows to process Erlang ddocs and runs within CouchDB bypassing stdio communication and JSON serialization/deserialization round trip overhead.

3.8.2. Query Servers Configuration

[query_server_config]
commit_freq

Specifies the delay in seconds before view index changes are committed to disk. The default value is 5:

[query_server_config]
commit_freq = 5
os_process_limit

Amount of time in seconds that the Query Server may process CouchDB command:

[query_server_config]
os_process_limit = 10

CouchDB will raise os_process_timeout error and kill the process in case the Query Server doesn’t return any result within this limit.

reduce_limit

Controls Reduce overflow error that raises when output of reduce functions is too big:

[query_server_config]
reduce_limit = true

Normally, you don’t have to disable (by setting false value) this option since main propose of reduce functions is to reduce the input.

3.8.3. Native Erlang Query Server

[native_query_servers]

Warning

Due to security restrictions, the Erlang query server is disabled by default.

Unlike the JavaScript query server, the Erlang one does not runs in a sandbox mode. This means that Erlang code has full access to your OS, filesystem and network, which may lead to security issues. While Erlang functions are faster than JavaScript ones, you need to be careful about running them, especially if they were written by someone else.

CouchDB has a native Erlang query server, allowing you to write your map/reduce functions in Erlang.

First, you’ll need to edit your local.ini to include a [native_query_servers] section:

[native_query_servers]
erlang = {couch_native_process, start_link, []}

To see these changes you will also need to restart the server. To test out using Erlang views, visit the Futon admin interface, create a new database and open a temporary view. You should now be able to select erlang from the language drop-down.

Let’s try an example of map/reduce functions which count the total documents at each number of revisions (there are x many documents at version “1”, and y documents at “2”... etc). Add a few documents to the database, then enter the following functions as a temporary view:

%% Map Function
fun({Doc}) ->
  <<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null),
  V = proplists:get_value(<<"_id">>, Doc, null),
  Emit(<<K>>, V)
end.

%% Reduce Function
fun(Keys, Values, ReReduce) -> length(Values) end.

If all has gone well, after running the view you should see a list of the total number of documents at each revision number.