Navigation
This version of the documentation is archived and no longer supported.

Server-side JavaScript

MongoDB supports server-side execution of JavaScript code within the database process.

Note

The JavaScript code execution takes a JavaScript lock: each mongod can only execute a single JavaScript operation at a time.

You can disable all server-side execution of JavaScript, by passing the --noscripting option on the command line or setting noscripting in a configuration file.

Map-Reduce

MongoDB performs the execution of JavaScript functions for Map-Reduce operations on the server. Within these JavaScript functions, you must not access the database for any reason, including to perform reads.

See the db.collection.mapReduce() and the Map-Reduce documentation for more information, including examples of map-reduce. See map-reduce concurrency section for concurrency information for map-reduce.

eval Command

The eval command, and the corresponding mongo shell method db.eval(), evaluates JavaScript functions on the database server. This command may be useful if you need to touch a lot of data lightly since the network transfer of the data could become a bottleneck if performing these operations on the client-side.

Warning

By default, eval command requires a write lock. As such eval will block all other read and write operations while it runs. Because only a single JavaScript process can run at a time, do not run mapReduce, group, queries with the $where or any other operation that requires JavaScript execution within eval operations.

See eval command and db.eval() documentation for more information, including examples.

Running .js files via a mongo shell Instance on the Server

Running a JavaScript (.js) file using a mongo shell instance on the server is a good technique for performing batch administrative work. When you run mongo shell on the server, connecting via the localhost interface, the connection is fast with low latency. Additionally, this technique has the advantage over the eval command since the command eval blocks all other operations.

$where Operator

To perform Read Operations, in addition to the standard operators (e.g. $gt, $lt), with the $where operator, you can also express the query condition either as a string or a full JavaScript function that specifies a SQL-like WHERE clause. However, use the standard operators whenever possible since $where operations have significantly slower performance.

Warning

Do not write to the database within the $where JavaScript function.

See $where documentation for more information, including examples.

Storing Functions Server-side

Note

We do not recommend using server-side stored functions if possible.

There is a special system collection named system.js that can store JavaScript functions for reuse.

To store a function, you can use the db.collection.save(), as in the following example:

db.system.js.save(
   {
     _id : "myAddFunction" ,
     value : function (x, y){ return x + y; }
   }
);
  • The _id field holds the name of the function and is unique per database.
  • The value field holds the function definition

Once you save a function in the system.js collection, you can use the function from any JavaScript context (e.g. eval, $where, map-reduce).

Consider the following example from the mongo shell that first saves a function named echoFunction to the system.js collection and calls the function using db.eval():

db.system.js.save(
                   { _id: "echoFunction",
                     value : function(x) { return x; }
                   }
                 )

db.eval( "echoFunction( 'test' )" )

See http://github.com/mongodb/mongo/tree/master/jstests/storefunc.js for a full example.

New in version 2.1: In the mongo shell, you can use db.loadServerScripts() to load all the scripts saved in the system.js collection for the current db. Once loaded, you can invoke the functions directly in the shell, as in the following example:

db.loadServerScripts();

echoFunction(3);

myAddFunction(3, 5);

Concurrency

Refer to the individual method or operator documentation for any concurrency information. See also the concurrency table.