MongoDB\Driver\Manager::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeCommandExecute a database command

Descripción

final public MongoDB\Driver\Manager::executeCommand(string $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.

Parámetros

db (string)

El nombre de la base de datos en la que ejecutar el comando.

command (MongoDB\Driver\Command)

El comando a ejecutar.

options

options
Option Type Description
readConcern MongoDB\Driver\ReadConcern

Un asunto de escritura a aplicar a la operación.

Esta opción está disponible en MongoDB 3.2+ y resultará en una excepción en tiempo de ejecución si es especificada para una versión de servidor más antigua.

readPreference MongoDB\Driver\ReadPreference

Una preferencia de lectura a usar para seleccionar un servidor para la operación.

session MongoDB\Driver\Session

Una sesión a asociar con la operación.

writeConcern MongoDB\Driver\WriteConcern

Un asunto de escritura a aplicar a la operación.

Advertencia

Si se usa la opción "session" con sesión que tenga una transacción en progreso, no se puede especificar una opción "readConcern" o "writeConcern". Esto resultarña en una MongoDB\Driver\Exception\InvalidArgumentException. En su lugar se debería establecer estas dos opciones al crear la transacción con MongoDB\Driver\Session::startTransaction().

Valores devueltos

Devuelve un MongoDB\Driver\Cursor en caso de éxito.

Errores/Excepciones

Historial de cambios

Versión Descripción
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.

Ejemplos

Ejemplo #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);

?>

El resultado del ejemplo sería:

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

Ejemplo #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);
}

?>

El resultado del ejemplo sería:

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

Ejemplo #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.

Notas

Nota: 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.

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().

Ver también

add a note

User Contributed Notes

There are no user contributed notes for this page.
To Top