db.eval()¶

On this page

Definition
Behavior
Examples

Definition¶

db.eval(function, arguments)¶

Deprecated since version 3.0.

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

The helper db.eval() in the mongo shell wraps the eval command. Therefore, the helper method shares the characteristics and behavior of the underlying command with one exception: db.eval() method does not support the nolock option.

The method accepts the following parameters:

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:

function () {
  // ...
}

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

Behavior¶

Write Lock¶

By default, db.eval() takes a global write lock while evaluating the JavaScript function. As a result, db.eval() blocks all other read and write operations to the database while the db.eval() operation runs.

To prevent the taking of the global write lock while evaluating the JavaScript code, use the eval command with nolock set to true. nolock does not impact whether the operations within the JavaScript code take write locks.

For long running db.eval() operation, consider using either the eval command with nolock: true or using other server side code execution options.

Sharded Data¶

You can not use db.eval() with sharded collections. In general, you should avoid using db.eval() in sharded clusters; nevertheless, it is possible to use db.eval() with non-sharded collections and databases stored in a sharded cluster.

Access Control¶

Changed in version 2.6.

If authorization is enabled, you must have access to all actions on all resources in order to run eval. Providing such access is not recommended, but if your organization requires a user to run eval, create a role that grants anyAction on anyResource. Do not assign this role to any other user.

JavaScript Engine¶

Changed in version 2.4.

The V8 JavaScript engine, which became the default in 2.4, allows multiple JavaScript operations to execute at the same time. Prior to 2.4, db.eval() executed in a single thread.

Examples¶

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

db.eval( function(name, incAmount) {
            var doc = db.myCollection.findOne( { name : name } );

            doc = doc || { name : name , num : 0 , total : 0 , avg : 0 };

            doc.num++;
            doc.total += incAmount;
            doc.avg = doc.total / doc.num;

            db.myCollection.save( doc );
            return doc;
         },
         "eliot", 5 );

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 db.eval(). Otherwise, the mongo shell’s JavaScript interpreter evaluates functions entered directly into the shell.

If an error occurs, 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:

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

The statement results in the following exception:

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