Definición
findEjecuta una query y devuelve el primer grupo de resultados y el ID del cursor, a partir del cual el cliente puede desarrollar un cursor.
Tip
En
mongosh, este comando también se puede ejecutar a través deldb.collection.find()o métodosdb.collection.findOne()auxiliares.Los métodos asistente son convenientes para usuarios de
mongosh, pero es posible que no proporcionen el mismo nivel de información que los comandos de base de datos. En los casos en que no se necesite la conveniencia o se requieran campos de retorno adicionales, utiliza el comando de base de datos.
Compatibilidad
Este comando está disponible en implementaciones alojadas en los siguientes entornos:
MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube
Importante
Este comando tiene soporte limitado en los clústeres Flex y M0. Para obtener más información, consulta Comandos no compatibles.
MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.
Sintaxis
El comando find tiene la siguiente sintaxis:
Modificado en la versión 5.0.
db.runCommand( { find: <string>, filter: <document>, sort: <document>, projection: <document>, hint: <document or string>, skip: <int>, limit: <int>, batchSize: <int>, singleBatch: <bool>, comment: <any>, maxTimeMS: <int>, readConcern: <document>, max: <document>, min: <document>, returnKey: <bool>, showRecordId: <bool>, tailable: <bool>, oplogReplay: <bool>, noCursorTimeout: <bool>, awaitData: <bool>, allowPartialResults: <bool>, collation: <document>, allowDiskUse : <bool>, let: <document> // Added in MongoDB 5.0 } )
Nota
A partir de MongoDB 4.4, el comando find ignora el indicador oplogReplay. Si el indicador oplogReplay está activado, el servidor lo acepta para la compatibilidad con versiones anteriores, pero no tiene efecto.
Campos de comandos
El comando acepta los siguientes campos:
Campo | Tipo | Descripción | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| string | El nombre de la colección o vista para hacer una query. | ||||||||||
| Documento | Opcional. El predicado de la query. Si no se especifica, entonces todos los documentos de la colección coincidirán con el predicado. | ||||||||||
Documento | Opcional. La especificación del orden para la clasificación de los resultados. | |||||||||||
| Documento | Opcional. La especificación de proyección para determinar qué campos se deben incluir en los documentos devueltos.
| ||||||||||
| string o documento | Opcional. Especificación del índice. Especifica el nombre del índice como una string o el patrón de la clave del índice. Si se especifica, el sistema de query solo considerará los planes que utilicen el índice sugerido. Con la siguiente excepción, | ||||||||||
| Número entero positivo | Opcional. Número de documentos para omitir. Se establece por defecto en 0. | ||||||||||
| Non-negative integer | Opcional. El número máximo de documentos para devolver. Si no se especifica, se establece por defecto en Sin límite. Un límite de 0 es equivalente a no establecer ningún límite. | ||||||||||
| non-negative integer | Opcional. El número máximo de documentos que se pueden devolver en cada lote de un resultado de query. Por defecto, el comando Un A diferencia de la versión anterior del protocolo de conexión, un batchSize de 1 para el comando | ||||||||||
| booleano | Opcional. Determina si se debe cerrar el cursor después del primer lote. Se configura por defecto en false. | ||||||||||
| any | Opcional. Un comentario proporcionado por el usuario para adjuntar a este comando. Una vez configurado, este comentario aparece junto a los registros de este comando en las siguientes ubicaciones:
Un comentario puede ser de cualquier tipo BSON válido (string, objeto, arreglo, etc.). Cualquier comentario establecido en un comando | ||||||||||
| non-negative integer | Opcional. Especifica un límite de tiempo en milisegundos. Si no especifica un valor para MongoDB finaliza las operaciones que exceden su límite de tiempo asignado utilizando el mismo mecanismo que Al especificar | ||||||||||
| Documento | Opcional. Especifica el nivel de consistencia de lectura. La opción Los posibles niveles de consistencia de lectura son estos:
Para obtener más información sobre los niveles de consistencia de lectura, consulta Nivel de consistencia de lectura. El comando | ||||||||||
| Documento | Opcional. El límite superior exclusivo para un índice específico. Consulta Para utilizar el campo | ||||||||||
| Documento | Opcional. El límite inferior inclusivo para un índice específico. Consulta Para utilizar el campo | ||||||||||
| booleano | Opcional. Si es verdadero, devuelve únicamente las claves de índice en los documentos resultantes. El valor por defecto es falso. Si returnKey es verdadero y el comando | ||||||||||
| booleano | Opcional. Determina si se debe devolver el identificador del registro para cada documento. Si es verdadero, se agrega un campo $recordId a los documentos devueltos. | ||||||||||
| booleano | Opcional. Devuelve un cursor con seguimiento para una colección con tamaño fijo. | ||||||||||
| booleano | |||||||||||
| booleano | Opcional. Impide que el servidor agote los cursores inactivos que no son parte de una sesión después de un periodo de inactividad de 30 minutos. Se ignora para los cursores que son parte de una sesión. Para obtener más información, consulta Tiempo de espera de inactividad de la sesión. | ||||||||||
booleano | Opcional. Para las queries sobre una colección particionada, permite que el comando (o los comandos Si | |||||||||||
| Documento | Opcional. Especifica la intercalación a utilizar para la operación. La intercalación permite a los usuarios especificar reglas propias del lenguaje para la comparación de strings, como reglas para el uso de mayúsculas y minúsculas y marcas de acento. La opción de intercalación tiene la siguiente sintaxis: Al especificar la intercalación, el campo Si no se especifica la intercalación, pero la colección tiene una intercalación por defecto (ver Si no se especifica ninguna intercalación para la colección o para las operaciones, MongoDB utiliza la comparación binaria simple usada en versiones anteriores para las comparaciones de strings. No puedes especificar varias intercalaciones para una operación. Por ejemplo, no puedes especificar diferentes intercalaciones por campo, o si realizas una búsqueda con un ordenamiento, no puedes usar una intercalación para la búsqueda y otra para el ordenamiento. | ||||||||||
booleano | Opcional. Usa esta opción para anular
A partir de MongoDB 6.0, si Para obtener más detalles, consulte
Para acceder una documentación más completa sobre Para obtener más información sobre las restricciones de memoria para grandes ordenaciones en memoria, consulta Uso de ordenación e índice. | |||||||||||
Documento | Opcional. Especifica un documento que contiene una lista de variables. Esto le permite mejorar la legibilidad de los comandos al separar las variables del texto de la query. La sintaxis del documento es: La variable se establece en el valor devuelto por la expresión y no puede modificarse posteriormente. Para acceder al valor de una variable en el comando, se debe usar el prefijo de doble signo de dólar ( Para usar una variable para los resultados del filtro, debes acceder a la variable dentro del operador Para un ejemplo completo usando Nuevo en la versión 5.0. |
Salida
El comando devuelve un documento que contiene la información del cursor, incluyendo el ID del cursor y la primera agrupación de documentos. Por ejemplo, el comando devuelve el siguiente documento cuando se ejecuta en una colección particionada:
{ "cursor" : { "firstBatch" : [ { "_id" : ObjectId("5e8e2ca217b5324fa9847435"), "zipcode" : "20001", "x" : 1 }, { "_id" : ObjectId("5e8e2ca517b5324fa9847436"), "zipcode" : "30001", "x" : 1 } ], "partialResultsReturned" : true, "id" : Long("668860441858272439"), "ns" : "test.contacts" }, "ok" : 1, "operationTime" : Timestamp(1586380205, 1), "$clusterTime" : { "clusterTime" : Timestamp(1586380225, 2), "signature" : { "hash" : BinData(0,"aI/jWsUVUSkMw8id+A+AVVTQh9Y="), "keyId" : Long("6813364731999420435") } } }
Campo | Descripción |
|---|---|
| Contiene la información del cursor, incluyendo el cursor Si la operación contra una colección particionada devuelve resultados parciales debido a la indisponibilidad de las particiones consultadas, el documento Si los fragmentos consultados están inicialmente disponibles para el comando |
| Indica si el comando ha tenido éxito ( |
Además de los campos específicos de find que se mencionaron anteriormente, db.runCommand() incluye la siguiente información para Set de réplicas y clústeres particionados:
$clusterTimeoperationTime
Consulta los Resultados de db.runCommand() para obtener más detalles.
Si no requieres una respuesta de comando sin procesar, utiliza los métodos del asistente db.collection.find() o db.collection.findOne().
Comportamiento
La siguiente sección describe las consideraciones de comportamiento del comando find().
Orden de operaciones
MongoDB generalmente produce el resultado de una operación find() con el siguiente orden de operaciones:
coincidencia
sort
Omitir
limit
Proyecto
MongoDB puede ejecutar componentes en un orden diferente para optimizar el rendimiento de los queries, manteniendo el orden de operaciones mencionado anteriormente.
$regex Las queries de búsqueda ya no ignoran regex no válidas
A partir de MongoDB 5.1, las opciones $regex options inválidas ya no se ignoran. Este cambio hace que $regex options sea más coherente con el uso de $regex en el comando aggregate y las queries de proyección.
Sesiones
Para los cursores creados dentro de una sesión, no puedes llamar a getMore fuera de la sesión.
De manera similar, para los cursores creados fuera de una sesión, no puedes llamar a getMore dentro de una sesión.
Tiempo de espera de inactividad de la sesión
Los drivers de MongoDB y mongosh asocian todas las operaciones con una sesión de servidor, con la excepción de las operaciones de escritura no reconocidas. Para las operaciones no asociadas explícitamente a una sesión (es decir, mediante Mongo.startSession()), los drivers de MongoDB y mongosh crean una sesión implícita y la asocian con la operación.
Si una sesión está inactiva durante más de 30 minutos, MongoDB Server marca esa sesión como expirada y puede cerrarla en cualquier momento. Cuando MongoDB Server cierra la sesión, también finaliza cualquier operación en curso y cierra los cursores abiertos asociados con la sesión. Esto incluye cursores configurados con noCursorTimeout() o un maxTimeMS() mayor a 30 minutos.
Para las operaciones que devuelven un cursor, si el cursor puede estar inactivo durante más de 30 minutos, emita la operación dentro de una sesión explícita usando Mongo.startSession() y actualice periódicamente la sesión usando el comando refreshSessions. Consulte Tiempo de espera de inactividad de la sesión para obtener más información.
Transacciones
find puede usarse dentro de transacciones distribuidas.
Para los cursores creados fuera de una transacción, no puedes llamar a
getMoredentro de la transacción.Para los cursores creados en una transacción, no puedes llamar a
getMorefuera de la transacción.
Importante
En la mayoría de los casos, una transacción distribuida incurre en un costo de rendimiento mayor que las escrituras de documentos individuales, y la disponibilidad de transacciones distribuidas no debería ser un sustituto para un diseño de esquema efectivo. Para muchos casos, el modelo de datos desnormalizado (documento incrustado y matrices) seguirá siendo óptimo para tus datos y casos de uso. Es decir, en muchos casos, modelar tus datos de forma adecuada minimizará la necesidad de transacciones distribuidas.
Para consideraciones adicionales sobre el uso de transacciones (como el límite de tiempo de ejecución y el límite de tamaño del oplog), consulta también las consideraciones de producción.
Desconexión del cliente
Si el cliente que emitió find se desconecta antes de que la operación se complete, MongoDB marca find para su terminación usando killOp.
Stable API
Al utilizar la Stable API V1, los siguientes campos de comando find no son compatibles:
awaitDatamaxminnoCursorTimeoutreturnKeyshowRecordIdtailable
Intercalaciones y filtros de índices
A partir de MongoDB 6.0, un filtro de índice utiliza la intercalación establecida previamente mediante el comando planCacheSetFilter.
A partir de MongoDB 8.0, utiliza la configuración del query en lugar de añadir filtros de índice. Los filtros de índices están en desuso a partir de MongoDB 8.0.
La configuración de queries tiene más funcionalidades que los filtros de índices. Además, los filtros de índice no son persistentes y no puedes crear fácilmente filtros de índice para todos los nodos del clúster. Para añadir ajustes de query y explorar ejemplos, consulta setQuerySettings.
Encuentre el comportamiento del cursor en las vistas
A partir de MongoDB 7.3, cuando utilizas un comando de búsqueda en una vista con las opciones singleBatch: true y batchSize: 1, ya no se devuelve un cursor. En las versiones anteriores de MongoDB, estas consultas de búsqueda devolverían un cursor incluso cuando establezcas la opción de lote único en true.
Configuración de query
Nuevo en la versión 8.0.
Puedes utilizar la configuración de query para establecer sugerencias de índice, fijar filtros de rechazo de operación y otros campos. Los ajustes se aplican a la forma de la query en todo el clúster. El clúster retiene la configuración después del apagado.
El optimizador de query utiliza la configuración del query como entrada adicional durante la planificación del query, lo que afecta al plan seleccionado para ejecutar el query. También puedes usar la configuración del query para bloquear una forma del query.
Para añadir configuraciones de query y explorar ejemplos, consulte setQuerySettings.
Puedes agregar configuraciones de query para los comandos find, distinct y aggregate.
La configuración de query tiene más funcionalidades y se prefiere sobre los filtros de índice en desuso.
Para remover la configuración del query, utilice removeQuerySettings. Para obtener la configuración del query, utilice una etapa de $querySettings en una canalización de agregación.
Ejemplos
Especifica un orden de clasificación y un límite
El siguiente comando ejecuta el comando find filtrando en el campo rating y en el campo cuisine. El comando incluye projection para devolver solo los siguientes campos en los documentos coincidentes: _id, name, rating y address.
El comando ordena los documentos en el conjunto de resultados por el campo name y limita el conjunto de resultados a 5 documentos.
db.runCommand( { find: "restaurants", filter: { rating: { $gte: 9 }, cuisine: "italian" }, projection: { name: 1, rating: 1, address: 1 }, sort: { name: 1 }, limit: 5 } )
Anular el nivel de consistencia de lectura por defecto
Para anular el nivel de consistencia de lectura por defecto de "local", usa la opción readConcern.
La siguiente operación en un Set de réplicas especifica un nivel de consistencia de lectura de "majority" para leer la copia más reciente de los datos confirmados como están escritos en la mayoría de los nodos.
db.runCommand( { find: "restaurants", filter: { rating: { $lt: 5 } }, readConcern: { level: "majority" } } )
Independientemente del nivel de consistencia de lectura, es posible que los datos más recientes de un nodo no reflejen la versión más reciente de los datos en el sistema.
El comando getMore usa el nivel readConcern especificado en el comando de origen find.
Se puede especificar readConcern para el método mongosh db.collection.find() usando el método cursor.readConcern():
db.restaurants.find( { rating: { $lt: 5 } } ).readConcern("majority")
Para obtener más información sobre los niveles de consistencia de lectura disponibles, consulta Nivel de consistencia de lectura.
Especificar la intercalación
La intercalación permite a los usuarios especificar reglas propias del lenguaje para la comparación de strings, como reglas para el uso de mayúsculas y minúsculas y marcas de acento.
La siguiente operación ejecuta el comando find con la intercalación especificada:
db.runCommand( { find: "myColl", filter: { category: "cafe", status: "a" }, sort: { category: 1 }, collation: { locale: "fr", strength: 1 } } )
mongosh proporciona cursor.collation() para especificar la intercalación para una operación db.collection.find().
Usar variables en let
Nuevo en la versión 5.0.
Para definir variables a las que puedes acceder en otros lugares del comando, utiliza la opción let.
Nota
Para filtrar los resultados usando una variable, debes acceder a la variable dentro del operador $expr.
Cree una colección cakeFlavors:
db.cakeFlavors.insertMany( [ { _id: 1, flavor: "chocolate" }, { _id: 2, flavor: "strawberry" }, { _id: 3, flavor: "cherry" } ] )
El siguiente ejemplo define una variable targetFlavor en let y utiliza la variable para recuperar el sabor del pastel chocolate:
db.cakeFlavors.runCommand( { find: db.cakeFlavors.getName(), filter: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } }, let : { targetFlavor: "chocolate" } } )