Join us at MongoDB.local London on 7 May to unlock new possibilities for your data. Use WEB50 to save 50%.
Register now >
Docs Menu
Docs Home
/
Desarrollo
/
Métodos mongosh
Docs Home
/
Desarrollo
/
Métodos mongosh
Docs Home
/
Desarrollo
/
Métodos mongosh

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

MongoDB con controladores

Esta página documenta a 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 SyncNode.jsPyMongoCC++GoJava RSKotlin CoroutineKotlin SyncPHPMongoidRustScala

Definición

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

Devuelve un documento que satisface los criterios de query 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 query. Estas opciones modifican el comportamiento de las query y la manera 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:

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 metadatadisponibles.

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

Los ejemplos de esta página utilizan datos del conjunto de datos de ejemplo sample_mflix. Para obtener más información sobre cómo cargar este conjunto de datos en su implementación de MongoDB autogestionada, consulte Cargar el conjunto de datos de ejemplo. Si realizó alguna modificación en las bases de datos de ejemplo, es posible que deba eliminarlas y volver a crearlas para ejecutar los ejemplos de esta página.

Con especificación de query vacía

La siguiente operación devuelve un único documento de la colección movies en la base de datos sample_mflix:

db.movies.findOne()

Con una especificación de query

La siguiente operación devuelve el primer documento coincidente de la movies colección donde el title campo comienza con la letra "T" o el year campo es menor 1950 que:

db.movies.findOne(
   {
      $or: [
            { title: /^T/ },
            { year: { $lt: 1950 } }
            ]
   }
)

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 movies y devuelve solo los campos title, genres y imdb:

db.movies.findOne(
   { },
   { title: 1, genres: 1, imdb: 1 }
)

Devuelva todos los campos excepto los excluidos

La siguiente operación devuelve un documento en la movies colección donde el cast array "Al Pacino" contiene. La proyección devuelve todos los campos excepto el _id campo, el votes campo en el imdb documento incrustado y el fullplot campo:

db.movies.findOne(
   { cast: 'Al Pacino' },
   { _id: 0, 'imdb.votes': 0, fullplot: 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 movies. En este ejemplo, la colección se ordena por year en orden ascendente.

db.movies.findOne(
   { },
   { },
   { sort: { year: 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.movies.findOne();
if (myDocument) {
   var myTitle = myDocument.title;
   print(myTitle);
}

Usa variables en let 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.

El siguiente ejemplo define una variable targetTitle en let y utiliza dicha variable para recuperar la película titulada "The Godfather":

db.movies.findOne(
   { $expr: { $eq: [ "$title", "$$targetTitle" ] } },
   { _id: 0, title: 1, year: 1 },
   { let : { targetTitle: "The Godfather" } }
)
{ year: 1972, title: 'The Godfather' }

Volver

db.collection.findAndModify

Next

db.collection.findOneAndDelete

En esta página