(mongodb >=1.0.0)
MongoDB\Driver\Manager::executeCommand — Execute a database command
$db
, MongoDB\Driver\Command $command
, array|MongoDB\Driver\ReadPreference|null $options
= null
): MongoDB\Driver\Cursor
Selects a server according to the "readPreference"
option
and executes the command on that server.
This method applies no special logic to the command. The
Default values for the "readPreference"
,
"readConcern"
, and "writeConcern"
options will be inferred from an active transaction (indicated by the
"session"
option). If there is no active transaction, a
primary read preference will be used for server selection.
Default values will not be inferred from the connection URI. Users are therefore encouraged to use specific read and/or write command methods if possible.
db
(string)The name of the database on which to execute the command.
command
(MongoDB\Driver\Command)The command to execute.
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. |
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().
Returns MongoDB\Driver\Cursor on success.
"session"
option is used with an associated transaction in combination with a "readConcern"
or "writeConcern"
option."session"
option is used in combination with an unacknowledged write concern.
Versione | Descrizione |
---|---|
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.
|
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);
?>
Il precedente esempio visualizzerà:
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);
}
?>
Il precedente esempio visualizzerà:
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.
Nota: If a secondary
readPreference
is used, it is the caller's responsibility to ensure that thecommand
can be executed on a secondary. No validation is done by the driver.
Nota: This method does not default to using the read preference from the MongoDB Connection URI. Applications in need of that behavior should consider using MongoDB\Driver\Manager::executeReadCommand().