Overview
En esta guía se puede aprender a usar la librería de MongoDB para PHP para ejecutar un comando de base de datos. Puedes usar comandos de base de datos para realizar una variedad de tareas administrativas y de diagnóstico, como obtener estadísticas del servidor, iniciar un set de réplicas o ejecutar una pipeline de agregación.
Importante
Prefiera los métodos de la librería a los comandos de base de datos
La biblioteca proporciona métodos contenedor para muchos comandos de base de datos. Se recomienda usar estos métodos en lugar de ejecutar comandos de base de datos cuando sea posible.
Para realizar tareas administrativas, usa el MongoDB Shell en lugar de la MongoDB PHP librería. El shell proporciona métodos asistentes que podrían no estar disponibles en la librería.
Si no hay asistentes disponibles en la librería o en la shell, puedes usar el db.runCommand() el método shell o el método MongoDB\Database::command() de la librería, el cual se describe en esta guía.
Ejecutar un comando
Para ejecutar un comando de base de datos, debes especificar el comando y cualquier parámetro relevante en un documento de comando, y luego pasar el documento de comando al método MongoDB\Database::command(). Muchos comandos de base de datos devuelven múltiples documentos como resultado, así que el método command() devuelve un MongoDB\Driver\Cursor objeto que se puede recorrer.
El siguiente código muestra cómo se puede usar el método command() en un MongoDB\Database instancia para ejecutar el hello comando, que devuelve información sobre el servidor:
$database = $client->selectDatabase('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 se podría haber configurado en la instancia Database en otra parte del código. Por defecto, 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], );
Obtén más información sobre la clase ReadPreference en la documentación de la API de extensiones para PHP.
Para obtener más información sobre las opciones de preferencia de lectura, consulta 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 único documento de resultados, ese resultado está disponible como el primer y único documento en el cursor. Para los comandos que devuelven múltiples documentos de resultados, la librería convierte el envoltorio 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órmate sobre el formato de respuesta del comando para que tu aplicación pueda iterar entre resultados múltiples o extraer el primer y único documento del cursor. Consulta 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 formato contiene los siguientes campos:
Campo | Descripción |
|---|---|
<command result> | Campos específicos del comando de base de datos. Por ejemplo, la instrucción |
| Si el comando ha tenido éxito ( |
| 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 usa el método command() para ejecutar el comando dbStats y 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: