Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

Ejecute un comando de base de datos

En esta guía, puedes aprender cómo utilizar el driver de Ruby para ejecutar un comando de base de datos. Puedes utilizar comandos de base de datos para realizar una variedad de tareas administrativas y de diagnóstico, como obtener estadísticas del servidor, inicializar un set de réplicas o ejecutar una pipeline de agregación.

Importante

Prefiere los métodos del controlador a los comandos de base de datos

El driver proporciona métodos contenedores para muchos comandos de base de datos. Si es posible, recomendamos utilizar estos métodos en lugar de ejecutar comandos de base de datos.

Para realizar tareas administrativas, utiliza la MongoDB Shell en lugar del driver de Ruby. El shell proporciona métodos asistentes que pueden no estar disponibles en el driver.

Si no hay asistentes disponibles en el driver o en la shell, puedes usar el método db.runCommand() de la shell o los métodos command y cursor_command del driver, que se describen en esta guía.

Los ejemplos en esta guía usan la base de datos sample_restaurants de los conjuntos de datos de muestra de Atlas. Para acceder a esta base de datos desde tu aplicación Ruby, crea un objeto Mongo::Client que se conecte a un clúster de Atlas y asigne el siguiente valor a tu variable database:

database = client.use('sample_restaurants').database

Para aprender cómo crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de ejemplo, consulta la guía MongoDB Get Started.

Para ejecutar un comando de base de datos, llame al método command en su instancia Mongo::Database y pase el nombre de la operación que desea ejecutar como parámetro.

El siguiente ejemplo llama al método command para ejecutar el comando hello, que devuelve información sobre el servidor:

database.command(hello: 1)

Tip

Para ver una lista completa de los comandos de base de datos y sus parámetros correspondientes, consulta Comandos de base de datos en el manual de MongoDB Server.

El método command devuelve un Mongo::Operation::Result que contiene la respuesta de la base de datos para el comando dado.

Puedes acceder a los campos del documento de respuesta de comando sin procesar usando los siguientes métodos:

Método
Descripción

acknowledged?

Devuelve true si el servidor reconoció el comando, y false en caso contrario.

inspect

Devuelve una representación en string y con formato de la respuesta del comando.

ok?

Devuelve true si el comando se ejecutó correctamente, y false en caso contrario. Si el método ok? devuelve false, el controlador genera un Mongo::Error::OperationFailure .

cluster_time

Devuelve la hora del clúster relatasada en la respuesta del servidor. El tiempo de clúster es un tiempo lógico que se utiliza para la ordenación de operaciones. Este campo solo se aplica a los comandos ejecutados en sets de réplicas o clústeres.

operation_time

Devuelve la hora lógica de la ejecución de la operación.

Para obtener una lista completa de los métodos disponibles en el objeto Result, consulte la documentación de la API.

Tip

Para obtener más información sobre el tiempo lógico, consulte la entrada de Wikipedia sobre el Reloj lógico.

El siguiente ejemplo ejecuta el comando dbStats para recuperar estadísticas de almacenamiento para la base de datos sample_restaurants, y luego imprime los resultados del comando utilizando el método inspect:

puts database.command({dbStats: 1}).first

La salida de este comando incluye información sobre los datos almacenados en la base de datos, como se muestra en el siguiente código:

{"db"=>"sample_restaurants", "collections"=>4, "views"=>0, "objects"=>18767, "avgObjSize"=>596.1911866574306,"dataSize"=>11188720, "storageSize"=>7528448, "totalFreeStorageSize"=>0, "numExtents"=>0, "indexes"=>6,"indexSize"=>1519616, "indexFreeStorageSize"=>0, "fileSize"=>0,"nsSizeMB"=>0, "ok"=>1}

Algunos comandos de base de datos devuelven sus resultados en un cursor. Para ejecutar estos comandos, llame al método cursor_command en su instancia Mongo::Database. Este método devuelve un objeto Mongo::Cursor que recuperar agrupar adicionales de resultados del servidor a medida que itera sobre él. Si la respuesta del comando no contiene un cursor, el driver genera un error Mongo::Error::InvalidCursorOperation.

El siguiente ejemplo ejecuta el comando listCollections mediante el método cursor_command e imprime el nombre y el tipo de cada colección en la base de datos sample_restaurants:

cursor = database.cursor_command(listCollections: 1, nameOnly: true)cursor.each do |doc| puts docend

Puedes pasar las siguientes opciones a los métodos command y cursor_command:

Opción
Métodos
Descripción

:read

command, cursor_command

La preferencia de lectura que se utilizará para el comando. El método cursor_command también utiliza esta preferencia de lectura para los comandos getMore posteriores. Por defecto, ambos métodos utilizan la preferencia de lectura primary.

:session

command, cursor_command

La sesión que se utilizará para el comando. Si no especifica una sesión para el método cursor_command, el driver crea una sesión implícita que dura toda la vida útil del cursor.

:timeout_ms

command, cursor_command

El tiempo de espera de la operación, en milisegundos. El valor debe ser un entero no negativo. Un valor de 0 significa que no hay tiempo de espera. Si no establece esta opción, el método hereda el tiempo de espera de la base de datos o del cliente.

:batch_size

cursor_command

El valor batchSize para enviar en los comandos getMore.

:max_time_ms

cursor_command

El valor maxTimeMS que se enviará en los comandos getMore. Para establecer un límite de tiempo en el comando inicial, incluya el campo maxTimeMS en el documento del comando.

:comment

cursor_command

Un comentario para adjuntar a los comandos getMore.

:cursor_type

cursor_command

El tipo de cursor, ya sea :tailable o :tailable_await. Este valor debe coincidir con las banderas establecidas en el documento de comando.

:timeout_mode

cursor_command

La moda de tiempo de espera, ya sea :cursor_lifetime o :iteration.

Los métodos command y cursor_command no heredan la preferencia de lectura en su instancia Database.

Puede establecer una preferencia de lectura para la ejecución del comando pasando la opción :read al método command, como se muestra en el siguiente código:

database.command({hello: 1}, read: {mode: :secondary})

Tip

Para obtener más información sobre las opciones de preferencia de lectura, consulta Preferencia de lectura en el manual de MongoDB Server.

Para obtener más información sobre los conceptos de esta guía, consulta la siguiente documentación en el manual de MongoDB Server:

Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API: