MongoDB::execute

Runs JavaScript code on the database server.

Description

public array MongoDB::execute ( mixed $code [, array $args = array() ] )

The Mongo database server runs a JavaScript engine. This method allows you to run arbitary JavaScript on the database. This can be useful if you want touch a number of collections lightly, or process some results on the database side to reduce the amount that has to be sent to the client.

Running JavaScript in the database takes a write lock, meaning it blocks other operations. Make sure you consider this before running a long script.

This is a wrapper for a database command. This method is basically:

<?php

public function execute($code$args) {
    return 
$this->command(array('$eval' => $code'args' => $args));
}

?>

MongoDB implies a return statement if you have a single statement on a single line. This can cause some unintuitive behavior. For example, this returns "foo":

<?php

$db
->execute('"foo";');

?>

However, these return NULL:

<?php

$db
->execute('"bar"; "foo";'); // more than one statement

$db->execute('db.foo.count(
);'
); // more than one line

?>

To avoid surprising behavior, it is best not to depend on MongoDB to decide what to return, but to explicitly state a return value. In the examples above, we can change them to:

<?php

$db
->execute('"bar"; return "foo";');

$db->execute('return db.foo.count(
);'
);

?>

Now the first statement will return "foo" and the second statement will return a count of the "foo" collection.

Parameters

code

MongoCode or string to execute.

args

Arguments to be passed to code.

Return Values

Returns the result of the evaluation.

Examples

Example #1 Simple MongoDB::execute example

<?php

$response 
$db->execute("function() { return 'Hello, world!'; }");
echo 
$response['retval'];

?>

The above example will output something similar to:


Hello, world!

Example #2 Parameter MongoDB::execute example

The optional array of parameters will be passed to the JavaScript function.

<?php

$response 
$db->execute("function(greeting, name) { return greeting+', '+name+'!'; }", array("Good bye""Joe"));
echo 
$response['retval'];

?>

The above example will output something similar to:


Good bye, Joe!

Example #3 Scope example

If a MongoCode object is used instead of a string for the first parameter, a scope can be passed in which the JavaScript will be executed.

<?php

$func 

    
"function(greeting, name) { ".
        
"return greeting+', '+name+', says '+greeter;".
    
"}";
$scope = array("greeter" => "Fred");

$code = new MongoCode($func$scope);

$response $db->execute($code, array("Goodbye""Joe"));
echo 
$response['retval'];

?>

The above example will output something similar to:


Goodbye, Joe, says Fred