db.eval()¶

db.eval(function, arguments)¶

The db.eval() provides the ability to run JavaScript code on the MongoDB server. It is a mongo shell wrapper around the eval command. However, unlike the eval command, the db.eval() method does not support the nolock option.

The method accepts the following parameters:

Parameters:

function (JavaScript) –
A JavaScript function.

The function need not take any arguments, as in the first example, or may optionally take arguments as in the second:
copy
```
function () {
  // ...
}
```
copy
```
function (arg1, arg2) {
   // ...
}
```
arguments – A list of arguments to pass to the JavaScript function if the function accepts arguments. Omit if the function does not take arguments.

Consider the following example of the db.eval() method:

copy

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;
         },
         "<name>", 5 );

The db in the function refers to the current database.
"<name>" 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. Consider the following invalid function that uses the variable x without declaring it as an argument:

copy

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

The statement will result in the following exception:

copy

{
   "errno" : -3,
   "errmsg" : "invoke failed: JS Error: ReferenceError: x is not defined nofile_b:1",
   "ok" : 0
}

Warning

By default, db.eval() takes a global write lock before 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. Set nolock to true on the eval command to prevent the eval command from taking the global write lock before evaluating the JavaScript. nolock does not impact whether operations within the JavaScript code itself takes a write lock.
db.eval() also takes a JavaScript lock.
Do not use db.eval() for long running operations, as db.eval() blocks all other operations. Consider using other server side code execution options.
You can not use db.eval() with sharded data. In general, you should avoid using db.eval() in sharded cluster; nevertheless, it is possible to use db.eval() with non-sharded collections and databases stored in sharded cluster.
With authentication enabled, db.eval() will fail during the operation if you do not have the permission to perform a specified task.