MongoDB\Driver\Manager::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeCommandExecute a database command

Description

final public MongoDB\Driver\Manager::executeCommand(string $db, MongoDB\Driver\Command $command, array $options = array()): MongoDB\Driver\Cursor

Selects a server according to the "readPreference" option and executes the command on that server. By default, the read preference from the MongoDB Connection URI will be used.

This method applies no special logic to the command. Although this method accepts "readConcern" and "writeConcern" options, which will be incorporated into the command document, those options will not default to corresponding values from the MongoDB Connection URI nor will the MongoDB server version be taken into account. Users are therefore encouraged to use specific read and/or write command methods if possible.

Parameters

db (string)

The name of the database on which to execute the command.

command (MongoDB\Driver\Command)

The command to execute.

options

options
Option Type Description
readConcern MongoDB\Driver\ReadConcern

A read concern to apply to the operation.

This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.

readPreference MongoDB\Driver\ReadPreference

A read preference to use for selecting a server for the operation.

session MongoDB\Driver\Session

A session to associate with the operation.

writeConcern MongoDB\Driver\WriteConcern

A write concern to apply to the operation.

Warning

If you are using a "session" which has a transaction in progress, you cannot specify a "readConcern" or "writeConcern" option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

Return Values

Returns MongoDB\Driver\Cursor on success.

Errors/Exceptions

Changelog

Version Description
PECL mongodb 1.4.4 MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\ReadPreference object.

Examples

Example #1 MongoDB\Driver\Manager::executeCommand() with a command returning a single result document

<?php

$manager 
= new MongoDB\Driver\Manager('mongodb://localhost:27017');
$command = new MongoDB\Driver\Command(['ping' => 1]);

try {
    
$cursor $manager->executeCommand('admin'$command);
} catch(
MongoDB\Driver\Exception $e) {
    echo 
$e->getMessage(), "\n";
    exit;
}

/* The ping command returns a single result document, so we need to access the
 * first result in the cursor. */
$response $cursor->toArray()[0];

var_dump($response);

?>

The above example will output:

array(1) {
  ["ok"]=>
  float(1)
}

Example #2 MongoDB\Driver\Manager::executeCommand() with a command returning a cursor

<?php

$manager 
= new MongoDB\Driver\Manager("mongodb://localhost:27017");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1'y' => 'foo']);
$bulk->insert(['x' => 2'y' => 'bar']);
$bulk->insert(['x' => 3'y' => 'bar']);
$manager->executeBulkWrite('db.collection'$bulk);

$command = new MongoDB\Driver\Command([
    
'aggregate' => 'collection',
    
'pipeline' => [
        [
'$group' => ['_id' => '$y''sum' => ['$sum' => '$x']]],
    ],
    
'cursor' => new stdClass,
]);
$cursor $manager->executeCommand('db'$command);

/* The aggregate command can optionally return its results in a cursor instead
 * of a single result document. In this case, we can iterate on the cursor
 * directly to access those results. */
foreach ($cursor as $document) {
    
var_dump($document);
}

?>

The above example will output:

object(stdClass)#6 (2) {
  ["_id"]=>
  string(3) "bar"
  ["sum"]=>
  int(10)
}
object(stdClass)#7 (2) {
  ["_id"]=>
  string(3) "foo"
  ["sum"]=>
  int(2)
}

Example #3 Limiting execution time for a command

The execution time of a command may be limited by specifying a value for "maxTimeMS" in the MongoDB\Driver\Command document. Note that this time limit is enforced on the server side and does not take network latency into account. See » Terminate Running Operations in the MongoDB manual for more information.

<?php

$manager 
= new MongoDB\Driver\Manager('mongodb://localhost:27017');

$command = new MongoDB\Driver\Command([
    
'count' => 'collection',
    
'query' => ['x' => ['$gt' => 1]],
    
'maxTimeMS' => 1000,
]);

$cursor $manager->executeCommand('db'$command);

var_dump($cursor->toArray()[0]);

?>

If the command fails to complete after one second of execution time on the server, a MongoDB\Driver\Exception\ExecutionTimeoutException will be thrown.

Notes

Note: If a secondary readPreference is used, it is the caller's responsibility to ensure that the command can be executed on a secondary. No validation is done by the driver.

See Also

Here you can write a comment


Please enter at least 10 characters.
Loading... Please wait.
* Pflichtangabe
There are no comments available yet.

PHP cURL Tutorial: Using cURL to Make HTTP Requests

cURL is a powerful PHP extension that allows you to communicate with different servers using various protocols, including HTTP, HTTPS, FTP, and more. ...

TheMax

Autor : TheMax
Category: PHP-Tutorials

Midjourney Tutorial - Instructions for beginners

There is an informative video about Midjourney, the tool for creating digital images using artificial intelligence, entitled "Midjourney tutorial in German - instructions for beginners" ...

Mike94

Autor : Mike94
Category: KI Tutorials

Basics of views in MySQL

Views in a MySQL database offer the option of creating a virtual table based on the result of an SQL query. This virtual table can be queried like a normal table without changing the underlying data. ...

admin

Autor : admin
Category: mySQL-Tutorials

Publish a tutorial

Share your knowledge with other developers worldwide

Share your knowledge with other developers worldwide

You are a professional in your field and want to share your knowledge, then sign up now and share it with our PHP community

learn more

Publish a tutorial