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 de los métodos auxiliaresdb.collection.find()odb.collection.findOne().Los métodos auxiliares son prácticos para los usuarios de
mongosh, pero es posible que no proporcionen el mismo nivel de información que los comandos de la base de datos. En los casos en que no se necesite esta comodidad o se requieran los campos de retorno adicionales, utilice el comando de la base de datos.
Compatibilidad
Este comando está disponible en implementaciones alojadas en los siguientes entornos:
- MongoDB Atlas: El servicio totalmente administrado para implementaciones de MongoDB en la nube.
Importante
Este comando tiene soporte limitado en clústeres M0 y Flex. Para obtener más información, consulte 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:
Cambiado 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 } )
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 cable, 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 solo las claves de índice en los documentos resultantes. El valor predeterminado 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 | Opcional. Úselo junto con la opción tailable para bloquear temporalmente un comando | ||||||||||
| booleano | Opcional. Impide que el servidor cierre los cursores inactivos que no pertenecen a una sesión tras un período de inactividad de 30 minutos. Se ignora para los cursores que forman parte de una sesión. Para obtener más información, consulte Tiempo de espera de inactividad de sesión. | ||||||||||
booleano | Opcional. Para las queries sobre una colección particionada, permite que el comando (o los comandos Si | |||||||||||
| Documento | Opcional. Opcional. Especifica la intercalación que se debe 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 ver un ejemplo completo que utilice 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 sobre una colección fragmentada devuelve resultados parciales debido a la indisponibilidad de los fragmentos consultados, el documento Si los fragmentos consultados están disponibles inicialmente para el comando |
| Indica si el comando ha tenido éxito ( |
Además de los campos específicos de find mencionados anteriormente, el db.runCommand() incluye la siguiente información para conjuntos de réplicas y clústeres fragmentados:
$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 controladores de MongoDB y mongosh asocian todas las operaciones con una sesión de servidor, con la excepción de las operaciones de escritura no confirmadas. Para las operaciones que no están explícitamente asociadas con una sesión (es decir, usando Mongo.startSession()), los controladores 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 se puede utilizar 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 finalice, MongoDB marca find para su terminación usando killOp.
Stable API
Al utilizar la API estable V1, los siguientes campos de comando find no son compatibles:
awaitDatamaxminnoCursorTimeoutoplogReplayreturnKeyshowRecordIdtailable
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, al usar el comando find en una vista con las opciones singleBatch: true y batchSize: 1, ya no se devuelve un cursor. En versiones anteriores de MongoDB, estas consultas find devolvían un cursor incluso cuando se configuraba 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 consulta 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
Los ejemplos de esta página utilizan datos del conjunto de datos sample_mflix. Para obtener más información sobre cómo cargar este conjunto de datos en la implementación autogestionada de MongoDB, consultar Cargar el conjunto de datos de muestra. Si realizó alguna modificación en las bases de datos de muestra, es posible que deba descartar y volver a crear las bases de datos para ejecutar los ejemplos de esta página.
Especifica un orden de clasificación y un límite
El siguiente comando utiliza find en la colección movies para encontrar películas con una calificación de IMDB de 9 o superior que pertenezcan al género Drama. El comando incluye un projection para devolver sólo los campos title, imdb.rating, y year en los documentos coincidentes.
El comando ordena los documentos en el conjunto de resultados por el campo title y limita el conjunto de resultados a 5 documentos.
db.runCommand( { find: "movies", filter: { "imdb.rating": { $gte: 9 }, genres: "Drama" }, projection: { title: 1, "imdb.rating": 1, year: 1 }, sort: { title: 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.
Este ejemplo de código realiza las siguientes operaciones en la colección movies en un set de réplicas:
encuentra películas con una calificación IMDB inferior a 5
limita los resultados a 5 documentos
especifica un nivel de consistencia de lectura de
"majority"para leer la copia más reciente de los datos que MongoDB ha escrito en la mayoría de los nodos.
db.runCommand( { find: "movies", filter: { "imdb.rating": { $lt: 5 } }, limit: 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 utiliza el nivel readConcern especificado en el comando find de origen.
Se puede especificar un readConcern para el método mongosh db.collection.find() utilizando el método cursor.readConcern():
db.movies.find( { "imdb.rating": { $lt: 2 } } ).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.
Este ejemplo realiza las siguientes operaciones:
encuentra películas con el título
Les Misérablesy la fecha de2012ordena los documentos coincidentes por
titleejecuta
findutilizando una intercalación francesa (locale: "fr") y una coincidencia insensible a los acentos (strength: 1):
db.runCommand( { find: "movies", filter: { title: "les misérables", year: 2012 }, sort: { title: 1 }, collation: { locale: "fr", strength: 1 } } )
mongosh proporciona el cursor.collation() para especificar la intercalación para una operación db.collection.find().
Usar variables en let
El siguiente ejemplo define una variable targetTitle y la utiliza para encontrar películas comparando el campo title con el valor de la variable. Este ejemplo encuentra todas las películas con el título “El Padrino”:
db.movies.runCommand( { find: db.movies.getName(), filter: { $expr: { $eq: [ "$title", "$$targetTitle" ] } }, let : { targetTitle: "The Godfather" } } )