(mongodb >=1.0.0)
MongoDB\Driver\Manager::executeCommand — Ejecuta un comando de base de datos
$db
, MongoDB\Driver\Command $command
, ?array $options
= null
): MongoDB\Driver\Cursor
Selecciona un servidor en función de la opción "readPreference"
y ejecuta el comando en ese servidor.
Este método no aplica ninguna lógica especial al comando. Los valores
por defecto de las opciones "readPreference"
,
"readConcern"
y "writeConcern"
serán
deducidos a partir de una transacción activa (indicada por la opción
"session"
). Si no hay una transacción activa, se utilizará
una preferencia de lectura primaria para la selección del servidor.
Los valores por defecto no serán no deducidos a partir de la URI de conexión. Por lo tanto, se recomienda a los usuarios utilizar métodos de comando de lectura y/o escritura específicos si es posible.
db
(string)El nombre de la base de datos en la que ejecutar el comando.
command
(MongoDB\Driver\Command)El comando a ejecutar.
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. |
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().
Devuelve un MongoDB\Driver\Cursor en caso de éxito.
"session"
se usa con una transacción asociada junto a la opción "readConcern"
o "writeConcern"
option."session"
se usa junto a un asunto de escritura no reconocido.
Versión | Descripción |
---|---|
PECL mongodb 2.0.0 |
El parámetro options ya no acepta
una instancia de MongoDB\Driver\ReadPreference.
|
PECL mongodb 1.21.0 |
Pasar un objeto MongoDB\Driver\ReadPreference como
options está obsoleto y será eliminado en la 2.0.
|
PECL mongodb 1.4.4 |
Se lanzará una MongoDB\Driver\Exception\InvalidArgumentException
si la opción "session" se utiliza en combinación con una
preferencia de escritura no reconocida.
|
PECL mongodb 1.4.0 |
Este tercer parámetro es ahora un array de options .
Por razones de compatibilidad ascendente, este parámetro siempre aceptará
un objeto MongoDB\Driver\ReadPreference.
|
Ejemplo #1 MongoDB\Driver\Manager::executeCommand() con un comando que devuelve un solo documento de resultado
<?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;
}
/* El comando ping devuelve un solo documento de resultado, por lo que
* se debe acceder al primer resultado en el 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() con un comando que devuelve un 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);
/* El comando de agregación puede eventualmente devolver sus resultados en
* un cursor en lugar de un solo documento de resultado. En este caso, se puede
* iterar directamente sobre el cursor para acceder a estos resultados. */
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 Limitar el tiempo de ejecución de un comando
El tiempo de ejecución de un comando puede ser limitado especificando un valor para
"maxTimeMS"
en el documento MongoDB\Driver\Command.
Tenga en cuenta que este límite de tiempo se aplica en el lado del servidor y no tiene en cuenta
la latencia de la red. Ver » Terminar las operaciones en curso
en el manual de MongoDB para más información.
<?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]);
?>
Si el comando no logra completarse después de un segundo de ejecución en el servidor, se lanzará una MongoDB\Driver\Exception\ExecutionTimeoutException.
Nota: Si se utiliza una segunda
readPreference
, es responsabilidad del llamante asegurarse de que elcomando
pueda ser ejecutado en un secundario. No se realiza ninguna validación por parte del controlador.
Nota: Este método no utiliza por defecto la preferencia de lectura de la URI de conexión MongoDB. Las aplicaciones que lo necesiten deberían considerar el uso de MongoDB\Driver\Manager::executeReadCommand().