MongoDB findOne: in­s­tru­c­cio­nes con ejemplos

El método MongoDB findOne es muy eficaz cuando hay que buscar dentro de una colección. Sin embargo, devuelve un solo resultado, por lo que no es adecuado para todas las ne­ce­si­da­des.

¿Qué es MongoDB findOne?

MongoDB es un sistema gestor de bases de datos capaz de manejar grandes ca­n­ti­da­des de datos de manera eficiente gracias a su enfoque NoSQL y su es­ca­la­bi­li­dad. Pese a ofrecer grandes ventajas, también requiere métodos sólidos para que los usuarios puedan mantener la vi­si­bi­li­dad sobre la base de datos al trabajar con ella.

El sistema almacena datos de todo tipo en forma de documento BSON (JSON binario) y agrupa estos do­cu­me­n­tos como co­le­c­cio­nes. Si quieres buscar y obtener uno de estos do­cu­me­n­tos, tienes varias po­si­bi­li­da­des. Además de la más habitual MongoDB find, MongoDB findOne es un método pa­r­ti­cu­la­r­me­n­te eficaz para filtrar con precisión incluso bases de datos extensas.

MongoDB findOne realiza búsquedas en todos los do­cu­me­n­tos y co­le­c­cio­nes co­n­si­de­ra­dos según criterios que puede es­pe­ci­fi­car el usuario. La pa­r­ti­cu­la­ri­dad del método es que siempre devuelve un solo documento que co­rre­s­po­n­de a los pa­rá­me­tros al­ma­ce­na­dos. Si solo hay un documento que coincide con la búsqueda, se toma ese documento. Si hay varios do­cu­me­n­tos que coinciden, MongoDB findOne devuelve el documento que aparece en primer lugar en el orden natural de la base de datos. Si no se encuentra ningún documento en la búsqueda, el resultado es “cero”.

Sintaxis y pa­r­ti­cu­la­ri­da­des de MongoDB findOne

La sintaxis básica de MongoDB findOne es sencilla. El método se utiliza siempre de la siguiente manera:

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

En <query> se indican los pa­rá­me­tros de búsqueda según los que el método debe filtrar los do­cu­me­n­tos. Esta entrada es opcional. Las entradas en <projection> de­te­r­mi­nan qué campos deben tenerse en cuenta para el documento mostrado. Los valores pe­r­mi­ti­dos para el resultado son los booleanos 1 (verdadero) y 0 (falso). Si este dato se deja en blanco, se mostrarán todos los campos. También es opcional. <options>, también opcional, permite modificar aún más la búsqueda y cambiar la vi­sua­li­za­ción.

Crear una colección de prueba

Si has instalado MongoDB en Linux, Windows o Mac y quieres utilizar MongoDB findOne, vale la pena co­n­fi­gu­rar un entorno de prueba para la primera vez que utilices el método. Te mostramos los primeros pasos con la base de datos en nuestro tutorial de MongoDB. En nuestro ejemplo, vamos a imaginar una base de datos de empleados que contiene cinco entradas e in­fo­r­ma­ción sobre el nombre, el sexo, la edad del empleado y cuánto tiempo lleva tra­ba­ja­n­do en la empresa. Esta colección tiene el siguiente aspecto:

# Create Collection
db.empleados.insertMany ( [
    {
    name : "Ortiz",
    gender : "Female",
    age : 56,
    year : 2002
    },
    {
    name : "Murillo",
    gender : "Female",
    age : 40,
    year : 2017,
    },
    {
    name : "Ruiz",
    gender : "Male",
    age : 40,
    year : 2019
    },
    {
    name : "Muñoz",
    gender : "Female",
    age : 44,
    year : 2015
    },
    name : "Jacobo",
    gender : "Male",
    age : 22,
    year : 2022
    }
]
)

MongoDB findOne: búsqueda sin pa­rá­me­tros

Si ahora utilizas el método findOne de MongoDB sin ningún parámetro, el sistema buscará en su base de datos y en­co­n­tra­rá cinco entradas que deberá tomar. Como no se excluyen do­cu­me­n­tos, los cinco empleados son elegibles. Por ello, MongoDB findOne se­le­c­cio­na­ría a la primera persona in­tro­du­ci­da en la base de datos, porque el método solo devuelve un resultado. Esta es la apa­rie­n­cia que tendría en nuestro ejemplo:

db.empleados.findOne ( )

Y este es el resultado co­rre­s­po­n­die­n­te:

db.empleados.findOne ( )
{
    _id : ObjectID ( "529ete7300of4002bme148om" ),
    name : "Ortiz",
    gender : "Female",
    age : 56,
    year : 2002
}

Buscar entradas por ID

No obstante, lo normal es que quieras es­pe­ci­fi­car tu búsqueda para no acabar con cualquier documento y obtener el que realmente necesitas. MongoDB findOne también ofrece he­rra­mie­n­tas adecuadas para ello. Un método muy seguro es realizar una búsqueda por ID. El campo _id es único en cada documento y, por tanto, siempre puede asignarse exac­ta­me­n­te a un empleado o una empleada en nuestro ejemplo. Por lo tanto, al ejecutar MongoDB findOne uti­li­za­n­do el ID del objeto, obtendrás el resultado correcto. En nuestro ejemplo, se vería así:

db.empleados.findOne ( { _id : ObjectID ( "582pfh773813tw982qj411l0" ) } )

El resultado debería ser este:

db.empleados.findOne ( { _id : ObjectID ( "582pfh773813tw982qj411l0" ) } )
{
    _id : ObjectID ( "582pfh773813tw982qj411l0"
    name : "Jacobo",
    gender : "Male",
    age : 22,
    year : 2022
}

Buscar campos es­pe­cia­les con MongoDB findOne

Si no conoces el ID o prefieres buscar tu colección uti­li­za­n­do otros pa­rá­me­tros, también puedes buscar filtrando por campos es­pe­cia­les gracias a MongoDB findOne. En este caso, ocurre lo mismo: si solo hay un documento que coincida con el parámetro, se mostrará. Sin embargo, si varios do­cu­me­n­tos coinciden con los criterios de búsqueda, el sistema solo mostrará la primera entrada. En nuestro ejemplo, por tanto, buscamos todas las entradas que indiquen “Male” (hombre) como sexo. En teoría, te­n­dría­mos dos re­su­l­ta­dos, pero solo se muestra el primero. Así es como debe figurar el comando:

db.empleados.findOne ( { gender : "Male" } )

En el resultado aparece el empleado Ruiz:

db.empleados.findOne ( { gender : "Male" } )
{
    _id : ObjectID ( "498p0t173mv489fh63th00kh"
    name : "Ruiz",
    gender : "Male",
    age : 40,
    year : 2019
}

MongoDB findOne: es­pe­ci­fi­car búsqueda

Por supuesto, también puedes acotar más la búsqueda para evitar so­la­pa­mie­n­tos. Esto quizá no sea necesario en una colección pequeña como la de nuestro ejemplo, pero sí es muy buena opción cuando tienes que trabajar con varios cientos o incluso miles de entradas. MongoDB findOne te permite utilizar varios campos en la búsqueda. Si eliges ide­n­ti­fi­car a un empleado por género (hombre) y edad, este es el aspecto que tendrá:

db.empleados.findOne ( { gender : "Male", age: 40 } )

El resultado vuelve a mostrar al empleado Ruiz, que es la única persona de la colección que es hombre y tiene 40 años. La empleada Murillo tendría la misma edad, pero es mujer. El resultado tendría el siguiente aspecto:

db.empleados.findOne ( { gender : "Male", age: 40 } )
{
    _id : ObjectID ( "498p0t173mv489fh63th00kh"
    name : "Ruiz",
    gender : "Male",
    age : 40,
    year : 2019
}

Es­ta­ble­cer co­n­di­cio­nes para un campo

También es posible es­ta­ble­cer co­n­di­cio­nes para un campo es­pe­cí­fi­co y uti­li­zar­las como criterio de búsqueda. En el siguiente ejemplo, solo tenemos en cuenta a las personas mayores de 30 años.

Se es­cri­bi­ría así:

db.empleados.findOne ( { age : { $gt : 30 } } )

En este caso, el empleado Jacobo queda excluido. Como la señora Ortiz cumple el criterio y es la primera persona de la lista, vuelve a mostrarse:

db.empleados.findOne ( { age : { $gt : 30 } } )
{
    _id : ObjectID ( "529ete7300of4002bme148om" ),
    name : "Ortiz",
    gender : "Female",
    age : 56,
    year : 2002
}

Excluir campos con MongoDB findOne

El resultado puede resultar confuso en algunos casos, es­pe­cia­l­me­n­te en co­le­c­cio­nes extensas que además contienen mucha in­fo­r­ma­ción. Por eso, MongoDB findOne ofrece la po­si­bi­li­dad de excluir campos in­di­vi­dua­les del resultado. En el siguiente ejemplo, no queremos que se muestren el ID, el sexo ni la edad.

db.empleados.findOne ( { name : "Ortiz" }, { _id : 0, gender : 0, age : 0 } )

Dado que se muestran todos los otros datos, obtendrás este resultado:

db.empleados.findOne ( { name : "Ortiz" }, { _id : 0, gender : 0, age : 0 } )
{
    name : "Ortiz",
    year : 2002
}

Ejemplo de una búsqueda fallida

Si no hay re­su­l­ta­dos para la búsqueda con MongoDB findOne, esto también se indicará. Busquemos, por ejemplo, al empleado Sanz, que no figura en la colección:

db.empleados.findOne ( { name : "Sanz" }  )

Este será el resultado:

db.empleados.findOne ( { name : "Sanz" }  )
null