Overview
En esta guía, aprenderá a usar la biblioteca PHP de MongoDB para ejecutar un comando de base de datos. Puede usar comandos de base de datos para realizar diversas tareas administrativas y de diagnóstico, como obtener estadísticas del servidor, inicializar un conjunto de réplicas o ejecutar una canalización de agregación.
Importante
Prefiera los métodos de biblioteca a los comandos de base de datos
La biblioteca proporciona métodos de encapsulamiento para numerosos comandos de base de datos. Recomendamos usar estos métodos en lugar de ejecutar comandos de base de datos siempre que sea posible.
Para realizar tareas administrativas, utilice el MongoDB Shell en lugar de la biblioteca PHP de MongoDB. El shell proporciona métodos auxiliares que podrían no estar disponibles en la biblioteca.
Si no hay ayudantes disponibles en la biblioteca o el shell, puede utilizar el db.runCommand() método de shell o el método MongoDB\Database::command() de la biblioteca, que se describe en esta guía.
Ejecutar un comando
Para ejecutar un comando de base de datos, debe especificar el comando y los parámetros relevantes en un documento de comando y, a continuación, pasar dicho documento al MongoDB\Database::command() método. Muchos comandos de base de datos devuelven varios documentos de resultados, por lo que el command() método devuelve un MongoDB\Driver\Cursor. objeto sobre el que puedes iterar.
El siguiente código muestra cómo puedes usar el método command() en un MongoDB\Database instancia para ejecutar el hello comando, que devuelve información sobre el servidor:
$database = $client->getDatabase('myDB'); $cursor = $database->command(['hello' => 1]);
Para encontrar un enlace a una lista completa de comandos de bases de datos y parámetros correspondientes, consulta la sección Información adicional.
Nota
preferencia de lectura
El método command() no hereda la preferencia de lectura que podría haber establecido en su instancia Database en otra parte del código. De forma predeterminada, command() usa la preferencia de lectura primary.
Puede establecer una preferencia de lectura para la ejecución de comandos configurando una en el parámetro de opciones, como se muestra en el siguiente código:
$readPref = new MongoDB\Driver\ReadPreference('primaryPreferred'); $cursor = $database->command( ['hello' => 1], ['readPreference' => $readPref], );
Obtenga más información sobre la ReadPreference clase en la documentación de la API de extensión PHP.
Para obtener más información sobre las opciones de preferencia de lectura, consulte Preferencia de lectura en el manual de MongoDB Server.
Respuesta
El método command() devuelve un objeto Cursor que contiene la respuesta de la base de datos al comando dado. Cada comando de la base de datos realiza una función diferente, por lo que el contenido de la respuesta puede variar.
Para los comandos que devuelven un solo documento de resultados, este se encuentra disponible como el primer y único documento en el cursor. Para los comandos que devuelven varios documentos de resultados, la biblioteca convierte la envolvente del cursor en la respuesta del comando sin procesar, que incluye el ID del cursor y el primer lote de resultados, en un cursor iterable.
Antes de ejecutar un comando, infórmese sobre el formato de respuesta para que su aplicación itere a través de múltiples resultados o extraiga el primer y único documento en el cursor. Consulte la sección "Información adicional" de esta guía para encontrar un enlace a la lista completa de comandos de base de datos.
La respuesta del comando sin procesar contiene los siguientes campos:
Campo | Descripción |
|---|---|
<command result> | Campos específicos del comando de base de datos. Por ejemplo, el comando |
| Si el comando se ejecutó correctamente |
| El tiempo lógico de la operación. MongoDB utiliza el tiempo lógico para ordenar las operaciones. Para conocer más sobre este concepto, consulta nuestra entrada de blog sobre el Global Logical Clock. |
| Un documento que contiene la hora de clúster firmada. La hora de clúster es una hora lógica utilizada para ordenar las operaciones. |
Ejemplo de comando
El siguiente ejemplo utiliza el método command() para ejecutar el comando dbStats para recuperar estadísticas de almacenamiento para la base de datos accounts:
$database = $client->accounts; $command = ['dbStats' => 1]; // dbStats returns a single document $cursor = $database->command($command); // Print the first document in the cursor echo json_encode($cursor->toArray()[0]), PHP_EOL;
La salida de este comando incluye información sobre las colecciones en la base de datos y describe la cantidad y el tamaño de los datos almacenados en todas las colecciones:
{"db":"accounts","collections":2,"views":0,"objects":5,"avgObjSize":22,"dataSize":110, "storageSize":40960,"totalFreeStorageSize":0,"numExtents":0,"indexes":2,"indexSize":40960, "indexFreeStorageSize":0,"fileSize":0,"nsSizeMB":0,"ok":1}
Información Adicional
Para obtener más información sobre los conceptos de esta guía, consulte la siguiente documentación en el manual de MongoDB Server:
Documentación de la API
Para obtener más información sobre el método command(), consulta la siguiente documentación de la API de la librería MongoDB PHP: