db.collection.findOne() (método mongosh)

MongoDB con controladores

Esta página documenta una mongosh . Para ver el método equivalente en un driver de MongoDB, se debe consultar la página correspondiente al lenguaje de programación:

C#Java Sync Node.js PyMongo C C++Go Java RS Kotlin Coroutine Kotlin Sync PHP Mongoid Rust Scala

Definición

db.collection.findOne(query, projection, options)

Devuelve un documento que satisface los criterios de consulta especificados en la colección o vista.

El documento devuelto puede variar según la cantidad de documentos que coinciden con los criterios del query, y el plan del query utilizado:

Número de documentos coincidentes	plan del query	Resultado
0	Any	El método devuelve `null`
1	Any	El método devuelve el documento que cumple con los criterios de query especificados.
2 o más	Escaneo de colección	El método devuelve el primer documento según el orden natural. En colecciones con tamaño fijo, el orden natural es el mismo que el orden de inserción.
2 o más	Exploración de índice	El método devuelve el primer documento recuperado del índice.

Importante

Si el plan de la query cambia para utilizar un índice diferente, el método puede devolver un documento diferente. Si el caso de uso requiere que se elija un registro concreto de forma consistente, se debe usar el documento options para especificar un orden. Para obtener detalles sobre cómo usar findOne() con un documento options, se debe consultar el ejemplo.

Si se especifica un parámetro projection, findOne() devuelve un documento que solo contiene los campos projection. El campo _id siempre se incluye a menos que se lo excluya explícitamente.

Nota

Aunque es similar al método find(), el método findOne() devuelve un documento en lugar de un cursor.

Compatibilidad

Este método está disponible en implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

Nota

Este comando es compatible con todos los clústeres de MongoDB Atlas. Para obtener información sobre el soporte de Atlas para todos los comandos, 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 método findOne() tiene la siguiente forma:

db.collection.findOne( <query>, <projection>, <options> )

El método findOne() toma los siguientes parámetros:

Parameter	Tipo	Descripción
`query`	Documento	Opcional. Especifica los criterios de selección utilizando operadores del query.
`projection`	Documento	Opcional. Especifica los campos que se deben devolver utilizando operadores de proyección. Se debe omitir este parámetro para que se devuelvan todos los campos en el documento coincidente. Para más detalles, consultar Proyección.
`options`	Documento	Opcional. Especifica opciones adicionales para la consulta. Estas opciones modifican el comportamiento de la consulta y la forma en que se devuelven los resultados. Para ver las opciones disponibles, consulte FindOptions.

Comportamiento

Desconexión del cliente

Si el cliente que emitió db.collection.findOne() se desconecta antes de que la operación se complete, MongoDB marca db.collection.findOne() para su terminación usando killOp.

Proyección

Importante

Consistencia del lenguaje

Para hacer que la proyección de find() y findAndModify() sea coherente con la etapa de agregación de $project:

Las proyecciones find() y la findAndModify() pueden aceptar expresiones y sintaxis de agregación.
MongoDB aplica restricciones adicionales con respecto a las proyecciones. Consulta restricciones de proyección para obtener más detalles.

El parámetro projection determina qué campos se devuelven en los documentos coincidentes. El parámetro projection acepta un documento con el siguiente formato:

{ field1: <value>, field2: <value> ... }

Proyección	Descripción
`<field>: <1 or true>`	Especifica la inclusión de un campo. Si especificas un entero distinto de cero para el valor de proyección, la operación trata el valor como `true`.
`<field>: <0 or false>`	Especifica la exclusión de un campo.
`"<field>.$": <1 or true>`	Utiliza el operador de proyección de arreglo `$` para devolver el primer elemento que coincide con la condición de query en el campo de arreglo. Si especificas un entero distinto de cero para el valor de proyección, la operación trata el valor como `true`. No disponible para las vistas.
`<field>: <array projection>`	Utiliza los operadores de proyección de arreglos (`$elemMatch`, `$slice`) para especificar los elementos del arreglo que se deben incluir. No disponible para las vistas.
`<field>: <$meta expression>`	Utilice la expresión del operador `$meta` para especificar la inclusión de `per-document metadata`disponibles. No disponible para las vistas.
`<field>: <aggregation expression>`	Especifica el valor del campo proyectado. Con el uso de expresiones y sintaxis de agregación, incluido el uso de literales y variables de agregación, se pueden proyectar campos nuevos o proyectar campos existentes con valores nuevos. Si se especifica un literal no numérico, no booleano (como una cadena de caracteres, un arreglo o una expresión de operador) para el valor de proyección, el campo se proyecta con el nuevo valor, por ejemplo: `{ field: [ 1, 2, 3, "$someExistingField" ] }` `{ field: "New String Value" }` `{ field: { status: "Active", total: { $sum: "$existingArray" } } }` Para proyectar un valor literal para un campo, utiliza la expresión de agregación `$literal`; por ejemplo: `{ field: { $literal: 5 } }` `{ field: { $literal: true } }` `{ field: { $literal: { fieldWithValue0: 0, fieldWithValue1: 1 } } }`

Nota

Puedes especificar la proyección de dos maneras para find() y findOne():

Estableciendo el parámetro projection
Configurando el parámetro options a projection

Si especificas ambos parámetros, el parámetro projection tiene prioridad. Para usar options.projection, establece el parámetro projection en null o undefined.

Especificación de campo embebido

Para campos en documentos incrustados, puedes especificar el campo mediante:

notación de puntos, por ejemplo "field.nestedfield": <value>
formulario anidado, por ejemplo { field: { nestedfield: <value> } }

`_id` Proyección de campo

El campo _id se incluye por defecto en los documentos devueltos, a menos que especifiques explícitamente _id: 0 en la proyección para suprimir el campo.

Inclusión o exclusión

Una projection no puede contener ambas especificaciones de inclusión y exclusión, con la excepción del campo _id:

En las proyecciones que incluyen explícitamente campos, el campo _id es el único campo que puedes excluir explícitamente.
En las proyecciones que excluyen explícitamente campos, el campo _id es el único campo que puedes incluir explícitamente; sin embargo, el campo _id se incluye por defecto.

Para obtener más información sobre la proyección, consulte también:

Ejemplos

Con especificación de query vacía

La siguiente operación devuelve un solo documento de la colección bios:

db.bios.findOne()

Con una especificación de query

La siguiente operación devuelve el primer documento coincidente de la colección bios donde el campo first en el documento incrustado name comienza con la letra G o donde el campo birth es menor que new Date('01/01/1945'):

db.bios.findOne(
   {
     $or: [
            { 'name.first' : /^G/ },
            { birth: { $lt: new Date('01/01/1945') } }
          ]
   }
)

Con una proyección

El parámetro projection especifica qué campos deben devolverse. El parámetro contiene especificaciones de inclusión o exclusión, no ambas, a menos que la exclusión sea para el campo _id.

Especifica los campos a devolver

La siguiente operación encuentra un documento en la colección bios y devuelve solo los campos name, contribs y _id:

db.bios.findOne(
    { },
    { name: 1, contribs: 1 }
)

Devuelva todos los campos excepto los excluidos

La siguiente operación devuelve un documento de la colección bios donde el campo contribs contiene el elemento OOP y devuelve todos los campos excepto el campo _id, el campo first en el documento incrustado name y el campo birth:

db.bios.findOne(
   { contribs: 'OOP' },
   { _id: 0, 'name.first': 0, birth: 0 }
)

Con una opción

La siguiente operación utiliza la opción sort para devolver el primer documento coincidente de la ordenada colección bios. En este ejemplo, la colección se ordena por birth en orden ascendente.

db.bios.findOne(
   { },
   { },
   { sort: { birth: 1 } }
)

El `findOne` documento de resultados

No puede aplicar métodos de cursor al resultado de findOne() porque se devuelve un solo documento. Tienes acceso directo al documento:

var myDocument = db.bios.findOne();
if (myDocument) {
   var myName = myDocument.name;
   print (tojson(myName));
}

Usar variables en `let` la opción

Puedes especificar las opciones de query para modificar el comportamiento de la query e indicar cómo se devuelven los resultados.

Por ejemplo, para definir variables a las que puedas acceder en otras partes del método findOne, utiliza la opción let. Para aplicar un filtro de resultados con 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.findOne(
   { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
   { _id: 0 },
   { let : { targetFlavor: "chocolate" }
} )

Salida:

{ flavor: 'chocolate' }

Para ver todas las opciones de consulta disponibles, consulta FindOptions.

Volver

db.collection.findAndModify

db.collection.findOneAndDelete

Definición

Importante

Nota

Compatibilidad

Nota

Sintaxis

Comportamiento

Desconexión del cliente

Proyección

Importante

Consistencia del lenguaje

Nota

Especificación de campo embebido

_id Proyección de campo

Inclusión o exclusión

Ejemplos

Con especificación de query vacía

Con una especificación de query

Con una proyección

Especifica los campos a devolver

Devuelva todos los campos excepto los excluidos

Con una opción

El findOne documento de resultados

Usar variables en let la opción

`_id` Proyección de campo

El `findOne` documento de resultados

Usar variables en `let` la opción