.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
.. use this file except in compliance with the License. You may obtain a copy of
.. the License at
..
..   http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
.. License for the specific language governing permissions and limitations under
.. the License.

.. default-domain:: js

=============
Query Servers
=============

.. _queryserver_js:

JavaScript
==========

.. note:: While every design function has access to all JavaScript objects,
   the table below describes appropriate usage cases. For example,
   you may use :func:`emit` in :ref:`listfun`, but :func:`getRow` is not permitted during :ref:`mapfun`.

+--------------------------------+---------------------------------------------+
| JS Function                    | Reasonable to use in design doc functions   |
+================================+=============================================+
| :func:`emit`                   | :ref:`mapfun`                               |
+--------------------------------+---------------------------------------------+
| :func:`getRow`                 | :ref:`listfun`                              |
+--------------------------------+---------------------------------------------+
| :data:`JSON`                   | any                                         |
+--------------------------------+---------------------------------------------+
| :func:`isArray`                | any                                         |
+--------------------------------+---------------------------------------------+
| :func:`log`                    | any                                         |
+--------------------------------+---------------------------------------------+
| :func:`provides`               | :ref:`showfun`, :ref:`listfun`              |
+--------------------------------+---------------------------------------------+
| :func:`registerType`           | :ref:`showfun`, :ref:`listfun`              |
+--------------------------------+---------------------------------------------+
| :func:`require`                | any, except :ref:`reducefun`                |
+--------------------------------+---------------------------------------------+
| :func:`send`                   | :ref:`listfun`                              |
+--------------------------------+---------------------------------------------+
| :func:`start`                  | :ref:`listfun`                              |
+--------------------------------+---------------------------------------------+
| :func:`sum`                    | any                                         |
+--------------------------------+---------------------------------------------+
| :func:`toJSON`                 | any                                         |
+--------------------------------+---------------------------------------------+

Design functions context
------------------------

Each design function executes in a special context of predefined objects,
modules and functions:


.. function:: emit(key, value)

   Emits a `key`-`value` pair for further processing by CouchDB after the map
   function is done.

   :param key: The view key
   :param value: The `key`'s associated value

   .. code-block:: javascript

      function(doc){
        emit(doc._id, doc._rev);
      }


.. function:: getRow()

   Extracts the next row from a related view result.

   :return: View result row
   :rtype: object

   .. code-block:: javascript

      function(head, req){
        send('[');
        row = getRow();
        if (row){
          send(toJSON(row));
          while(row = getRow()){
            send(',');
            send(toJSON(row));
          }
        }
        return ']';
      }


.. data:: JSON

   `JSON2 <https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=share/server/json2.js>`_
   object.


.. function:: isArray(obj)

   A helper function to check if the provided value is an `Array`.

   :param obj: Any Javascript value
   :return: ``true`` if `obj` is `Array`-typed, ``false`` otherwise
   :rtype: boolean


.. function:: log(message)

   Log a message to the CouchDB log (at the `INFO` level).

   :param message: Message to be logged

   .. code-block:: javascript

      function(doc){
        log('Procesing doc ' + doc['_id']);
        emit(doc['_id'], null);
      }

   After the map function has run, the following line can be found in CouchDB
   logs (e.g. at `/var/log/couchdb/couch.log`):

   .. code-block:: text

      [Sat, 03 Nov 2012 17:38:02 GMT] [info] [<0.7543.0>] OS Process #Port<0.3289> Log :: Processing doc 8d300b86622d67953d102165dbe99467


.. function:: provides(key, func)

   Registers callable handler for specified MIME key.

   :param key: MIME key previously defined by :func:`registerType`
   :param func: MIME type handler


.. function:: registerType(key, *mimes)

   Registers list of MIME types by associated `key`.

   :param key: MIME types
   :param mimes: MIME types enumeration

   Predefined mappings (`key`-`array`):

   - **all**: ``*/*``
   - **text**: ``text/plain; charset=utf-8``, ``txt``
   - **html**: ``text/html; charset=utf-8``
   - **xhtml**: ``application/xhtml+xml``, ``xhtml``
   - **xml**: ``application/xml``, ``text/xml``, ``application/x-xml``
   - **js**: ``text/javascript``, ``application/javascript``,
     ``application/x-javascript``
   - **css**: ``text/css``
   - **ics**: ``text/calendar``
   - **csv**: ``text/csv``
   - **rss**: ``application/rss+xml``
   - **atom**: ``application/atom+xml``
   - **yaml**: ``application/x-yaml``, ``text/yaml``
   - **multipart_form**: ``multipart/form-data``
   - **url_encoded_form**: ``application/x-www-form-urlencoded``
   - **json**: ``application/json``, ``text/x-json``


.. function:: require(path)

   Loads CommonJS module by a specified `path`. The path should not start with
   a slash.

   :param path: A CommonJS module path started from design document root
   :return: Exported statements


.. function:: send(chunk)

   Sends a single string `chunk` in response.

   :param chunk: Text chunk

   .. code-block:: javascript

      function(head, req){
        send('Hello,');
        send(' ');
        send('Couch');
        return !
      }


.. function:: start(init_resp)

   Initiates chunked response. As an option, a custom
   :ref:`response <response_object>` object may be sent at this point.
   For `list`-functions only!

   .. note::
   
      list functions may set the `HTTP response code` and `headers` by calling
      this function. This function must be called before :func:`send`,
      :func:`getRow` or a `return` statement; otherwise, the query server will
      implicitly call this function with the empty object (``{}``).

   .. code-block:: javascript

      function(head, req){
        start({
          "code": 302,
          "headers": {
            "Location": "http://couchdb.apache.org"
          }
        });
        return "Relax!";
      }


.. function:: sum(arr)

   Sum `arr`'s items.

   :param arr: Array of numbers
   :rtype: number


.. function:: toJSON(obj)

   Encodes `obj` to JSON string. This is an alias for the ``JSON.stringify``
   method.

   :param obj: JSON encodable object
   :return: JSON string

.. _commonjs:

CommonJS Modules
----------------

Support for `CommonJS Modules <http://wiki.commonjs.org/wiki/Modules/1.1.1>`_
(introduced in CouchDB 0.11.0) allows you to create modular design functions
without the need for duplication of functionality.

Here's a CommonJS module that checks user permissions:

.. code-block:: javascript

    function user_context(userctx, secobj) {
      var is_admin = function() {
        return userctx.indexOf('_admin') != -1;
      }
      return {'is_admin': is_admin}
    }

    exports['user'] = user_context

Each module has access to additional global variables:

- **module** (`object`): Contains information about the stored module

  - **id** (`string`): The module id; a JSON path in ddoc context
  - **current** (`code`): Compiled module code object
  - **parent** (`object`): Parent frame
  - **exports** (`object`): Export statements

- **exports** (`object`): Shortcut to the ``module.exports`` object

The CommonJS module can be added to a design document, like so:

.. code-block:: javascript

    {
       "views": {
          "lib": {
             "security": "function user_context(userctx, secobj) { ... }"
          },
          "validate_doc_update": "function(newdoc, olddoc, userctx, secobj) {
            user = require('lib/security').user(userctx, secobj);
            return user.is_admin();
          }"
       },
       "_id": "_design/test"
    }

Modules paths are relative to the design document's ``views`` object, but
modules can only be loaded from the object referenced via ``lib``. The
``lib`` structure can still be used for view functions as well, by simply
storing view functions at e.g. ``views.lib.map``, ``views.lib.reduce``, etc.

.. _queryserver_erlang:

Erlang
======

.. warning::

   Unlike the JavaScript query server, the Erlang query server does not
   run in a sandbox. This means 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.


.. note::

   Due to security restrictions, the Erlang query server is disabled by
   default. To enable it, you need to edit your `local.ini` to include a
   ``native_query_servers`` section:

   .. code-block:: ini

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

   Don't forget to restart CouchDB after updating the configuration, and
   use the ``language: "erlang"`` property in your Erlang design documents.


.. function:: Emit(Id, Value)

   Emits `key`-`value` pairs to view indexer process.

   .. code-block:: erlang

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


.. function:: FoldRows(Fun, Acc)

   Helper to iterate over all rows in a list function.

   :param Fun: Function object.
   :param Acc: The value previously returned by `Fun`.

   .. code-block:: erlang

      fun(Head, {Req}) ->
        Fun = fun({Row}, Acc) ->
          Id = couch_util:get_value(<<"id">>, Row),
          Send(list_to_binary(io_lib:format("Previous doc id: ~p~n", [Acc]))),
          Send(list_to_binary(io_lib:format("Current  doc id: ~p~n", [Id]))),
          {ok, Id}
        end,
        FoldRows(Fun, nil),
        ""
      end.


.. function:: GetRow()

   Retrieves the next row from a related view result.

   .. code-block:: erlang

      %% FoldRows background implementation.
      %% https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=src/couchdb/couch_native_process.erl;hb=HEAD#l368
      %%
      foldrows(GetRow, ProcRow, Acc) ->
        case GetRow() of
          nil ->
            {ok, Acc};
          Row ->
            case (catch ProcRow(Row, Acc)) of
              {ok, Acc2} ->
                foldrows(GetRow, ProcRow, Acc2);
              {stop, Acc2} ->
                {ok, Acc2}
            end
      end.

.. function:: Log(Msg)

   :param Msg: Log a message at the `INFO` level.

   .. code-block:: erlang

      fun({Doc}) ->
        <<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null),
        V = proplists:get_value(<<"_id">>, Doc, null),
        Log(lists:flatten(io_lib:format("Hello from ~s doc!", [V]))),
        Emit(<<K>>, V)
      end.

   After the map function has run, the following line can be found in
   CouchDB logs (e.g. at `/var/log/couchdb/couch.log`):

   .. code-block:: text

      [Sun, 04 Nov 2012 11:33:58 GMT] [info] [<0.9144.2>] Hello from 8d300b86622d67953d102165dbe99467 doc!


.. function:: Send(Chunk)

   Sends a single string `Chunk` in response.

   .. code-block:: erlang

      fun(Head, {Req}) ->
        Send("Hello,"),
        Send(" "),
        Send("Couch"),
        "!"
      end.

   The function above produces the following response:

   .. code-block:: text

      Hello, Couch!


.. function:: Start(Headers)

   :param Headers: Proplist of :ref:`response object<response_object>`.

   Initialize :ref:`listfun` response. At this point, response code and headers
   may be defined. For example, this function redirects to the CouchDB web site:

   .. code-block:: erlang

      fun(Head, {Req}) ->
        Start({[{<<"code">>, 302},
                {<<"headers">>, {[
                  {<<"Location">>, <<"http://couchdb.apache.org">>}]
                }}
              ]}),
        "Relax!"
      end.