db.eval.txt

=========
db.eval()
=========

.. Edits to this page should be carried over to the command eval.txt
   file.  HOWEVER, the parameters are different between command and method.

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Definition
----------

.. method:: db.eval(function, arguments)

   .. deprecated:: 3.0

   Provides the ability to run JavaScript code on the MongoDB server.

   .. |list| replace:: A list

   .. include:: /includes/fact-eval-helper-method.rst

   The method accepts the following parameters:


   .. list-table::
      :header-rows: 1
      :widths: 20 20 80
   
      * - Parameter
   
        - Type
   
        - Description
   
      * - ``function``
   
        - function
   
        - A JavaScript function to execute.
          
          
   
      * - ``arguments``
   
        - list
   
        - Optional. A list of arguments to pass to the JavaScript function. Omit if the function does not take arguments.
          
          
   


   The JavaScript function need not take any arguments, as in the first example,
   or may optionally take arguments as in the second:

   .. code-block:: javascript

      function () {
        // ...
      }

   .. code-block:: javascript

      function (arg1, arg2) {
         // ...
      }

Behavior
--------

.. |object| replace:: :method:`db.eval()`
.. |nolockobject| replace:: :dbcommand:`eval` *command*
.. include:: /includes/admonitions-eval.rst

Examples
--------

The following is an example of the :method:`db.eval()` method:

.. include:: /includes/examples-eval.rst
   :start-after: .. eval-method-example

- The ``db`` in the function refers to the current database.

- ``"eliot"`` is the argument passed to the function, and corresponds to
  the ``name`` argument.

- ``5`` is an argument to the function and corresponds to the
  ``incAmount`` field.

If you want to use the server's interpreter, you must run
:method:`db.eval()`. Otherwise, the :binary:`~bin.mongo` shell's JavaScript
interpreter evaluates functions entered directly into the shell.

If an error occurs, :method:`db.eval()` throws an exception. The
following is an example of an invalid function that uses the variable
``x`` without declaring it as an argument:

.. code-block:: javascript

   db.eval( function() { return x + x; }, 3 );

The statement results in the following exception:

.. code-block:: javascript

   {
      "errmsg" : "exception: JavaScript execution failed: ReferenceError: x is not defined near '{ return x + x; }' ",
      "code" : 16722,
      "ok" : 0
   }

.. seealso::

   :doc:`/core/server-side-javascript`