MongoDB findOne: ins­tru­ções com exemplos

O método MongoDB findOne é muito eficaz quando é ne­ces­sá­rio pesquisar dentro de uma coleção. No entanto, ele retorna apenas um resultado, portanto não é adequado para todas as ne­ces­si­da­des.

O que é MongoDB findOne?

O MongoDB é um sistema de gestão de bases de dados capaz de lidar com grandes quan­ti­da­des de dados de forma eficiente, graças à sua abordagem NoSQL e à sua es­ca­la­bi­li­dade. Apesar de oferecer grandes vantagens, também requer métodos sólidos para que os uti­li­za­do­res possam manter a vi­si­bi­li­dade sobre a base de dados ao trabalhar com ela.

O sistema armazena dados de todos os tipos na forma de do­cu­men­tos BSON (JSON binário) e agrupa esses do­cu­men­tos como coleções. Se você deseja pesquisar e obter um desses do­cu­men­tos, há várias pos­si­bi­li­da­des. Além do mais comum MongoDB find, o MongoDB findOne é um método par­ti­cu­lar­mente eficaz para filtrar com precisão até mesmo bases de dados extensas.

O MongoDB findOne realiza pesquisas em todos os do­cu­men­tos e coleções con­si­de­ra­dos de acordo com critérios que podem ser es­pe­ci­fi­ca­dos pelo uti­li­za­dor. A par­ti­cu­la­ri­dade do método é que ele sempre retorna um único documento que cor­res­ponde aos pa­râ­me­tros ar­ma­ze­na­dos. Se houver apenas um documento que cor­res­ponda à pesquisa, esse documento será se­le­ci­o­nado. Se houver vários do­cu­men­tos cor­res­pon­den­tes, o MongoDB findOne retornará o documento que aparece em primeiro lugar na ordem natural do banco de dados. Se nenhum documento for en­con­trado na pesquisa, o resultado será “zero”.

Sintaxe e par­ti­cu­la­ri­da­des do MongoDB findOne

A sintaxe básica do MongoDB findOne é simples. O método é sempre utilizado da seguinte forma:

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

Em <query> são indicados os pa­râ­me­tros de pesquisa segundo os quais o método deve filtrar os do­cu­men­tos. Esta entrada é opcional. As entradas em <projection> de­ter­mi­nam quais campos devem ser con­si­de­ra­dos para o documento exibido. Os valores per­mi­ti­dos para o resultado são os booleanos 1 (ver­da­deiro) e 0 (falso). Se este dado for deixado em branco, todos os campos serão exibidos. Também é opcional. <options>, também opcional, permite modificar ainda mais a pesquisa e alterar a vi­su­a­li­za­ção.

Criar uma coleção de teste

Se instalou o MongoDB no Linux, Windows ou Mac e deseja utilizar o MongoDB findOne, vale a pena con­fi­gu­rar um ambiente de teste para a primeira vez que utilizar o método. Mostramos os primeiros passos com a base de dados no nosso tutorial do MongoDB. No nosso exemplo, vamos imaginar uma base de dados de fun­ci­o­ná­rios que contém cinco entradas e in­for­ma­ções sobre o nome, sexo, idade do fun­ci­o­ná­rio e há quanto tempo trabalha na empresa. Esta coleção tem a seguinte aparência:

# 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: pesquisa sem pa­râ­me­tros

Se agora utilizar o método findOne do MongoDB sem nenhum parâmetro, o sistema pes­qui­sará na sua base de dados e en­con­trará cinco entradas que deverá se­le­ci­o­nar. Como não são excluídos do­cu­men­tos, os cinco fun­ci­o­ná­rios são elegíveis. Por isso, o MongoDB findOne se­le­ci­o­na­ria a primeira pessoa in­tro­du­zida na base de dados, porque o método apenas retorna um resultado. Esta seria a aparência no nosso exemplo:

db.empleados.findOne ( )

E este é o resultado cor­res­pon­dente:

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

Pesquisar entradas por ID

No entanto, o normal é que queira es­pe­ci­fi­car a sua pesquisa para não acabar com qualquer documento e obter aquele que realmente precisa. O MongoDB findOne também oferece fer­ra­men­tas adequadas para isso. Um método muito seguro é realizar uma pesquisa por ID. O campo _id é único em cada documento e, portanto, pode sempre ser atribuído exa­ta­mente a um fun­ci­o­ná­rio ou fun­ci­o­ná­ria no nosso exemplo. Assim, ao executar o MongoDB findOne uti­li­zando o ID do objeto, obterá o resultado correto. No nosso exemplo, ficaria assim:

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

O resultado deve ser este:

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

Pesquisar campos especiais com MongoDB findOne

Se não souber o ID ou preferir pesquisar a sua coleção uti­li­zando outros pa­râ­me­tros, também pode pesquisar filtrando por campos especiais graças ao MongoDB findOne. Neste caso, ocorre o mesmo: se houver apenas um documento que cor­res­ponda ao parâmetro, ele será exibido. No entanto, se vários do­cu­men­tos cor­res­pon­de­rem aos critérios de pesquisa, o sistema exibirá apenas a primeira entrada. No nosso exemplo, portanto, pro­cu­ra­mos todas as entradas que indiquem «Male» (homem) como sexo. Em teoria, teríamos dois re­sul­ta­dos, mas apenas o primeiro é apre­sen­tado. É assim que o comando deve aparecer:

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

No resultado aparece o fun­ci­o­ná­rio Ruiz:

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

MongoDB findOne: es­pe­ci­fi­car pesquisa

É claro que também pode refinar ainda mais a pesquisa para evitar so­bre­po­si­ções. Isso talvez não seja ne­ces­sá­rio em uma coleção pequena como a do nosso exemplo, mas é uma ótima opção quando tem que trabalhar com várias centenas ou até milhares de entradas. O MongoDB findOne permite usar vários campos na pesquisa. Se optar por iden­ti­fi­car um fun­ci­o­ná­rio por género (homem) e idade, ficará assim:

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

O resultado volta a mostrar o fun­ci­o­ná­rio Ruiz, que é a única pessoa da coleção que é homem e tem 40 anos. A fun­ci­o­ná­ria Murillo teria a mesma idade, mas é mulher. O resultado teria a seguinte aparência:

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

Definir condições para um campo

Também é possível definir condições para um campo es­pe­cí­fico e utilizá-las como critério de pesquisa. No exemplo a seguir, con­si­de­ra­mos apenas pessoas com mais de 30 anos.

Escrever-se-ia assim:

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

Neste caso, o fun­ci­o­ná­rio Jacobo é excluído. Como a Sra. Ortiz cumpre o critério e é a primeira pessoa da lista, ela volta a ser exibida:

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

Excluir campos com MongoDB findOne

O resultado pode ser confuso em alguns casos, es­pe­ci­al­mente em coleções extensas que também contêm muitas in­for­ma­ções. Por isso, o MongoDB findOne oferece a pos­si­bi­li­dade de excluir campos in­di­vi­du­ais do resultado. No exemplo a seguir, não queremos que o ID, o sexo e a idade sejam exibidos.

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

Como todos os outros dados são exibidos, obterá este resultado:

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

Exemplo de uma pesquisa sem sucesso

Se não houver re­sul­ta­dos para a pesquisa com MongoDB findOne, isso também será indicado. Vamos procurar, por exemplo, o fun­ci­o­ná­rio Sanz, que não consta na coleção:

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

Este será o resultado:

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