Tutorial: Como usar MongoDB findOne

MongoDB findOne é muito eficiente para realizar buscas dentro de uma coleção. Por outro lado, ele sempre retorna um único resultado, o que pode não ser adequado em todas as situações. Acompanhe o nosso tutorial e aprenda a aplicar o método nos seus bancos de dados.

O que é o método MongoDB findOne?

MongoDB é um sistema de ge­ren­ci­a­mento de banco de dados (DBMS) que, por causa de sua abordagem NoSQL e de sua es­ca­la­bi­li­dade acentuada, consegue armazenar e gerenciar grandes volumes de dados sem qualquer di­fi­cul­dade. Embora essa seja sua grande vantagem, o MongoDB exige que seus usuários adotem métodos robustos para manter a or­ga­ni­za­ção dos bancos de dados.

O MongoDB é capaz de armazenar dados de qualquer tipo no formato BSON (JSON binário) e de agrupar esses do­cu­men­tos em coleções. Para buscar e exibir um desses do­cu­men­tos, você pode utilizar-se de di­fe­ren­tes métodos: al­ter­na­ti­va­mente ao MongoDB find que é mais geral, adote o método ex­tre­ma­mente eficaz MongoDB findOne para filtrar até mesmo bancos de dados extensos com precisão.

O findOne consegue realizar pesquisas em todos os do­cu­men­tos e coleções a serem con­si­de­ra­dos, com base nos critérios es­pe­ci­fi­ca­dos pelo usuário. O principal di­fe­ren­cial desse método é que ele sempre retorna um único documento que cor­res­ponda aos critérios inseridos. Assim, se apenas um documento cor­res­pon­der à consulta, este será retornado. Contudo, se vários do­cu­men­tos forem en­con­tra­dos, o findOne retornará somente o primeiro que estiver na ordem natural do banco de dados. Por fim, se nenhum documento for en­con­trado pela busca, a saída exibida será “null”.

Sintaxe e di­fe­ren­cial do MongoDB findOne

A sintaxe básica do MongoDB findOne é bastante simples. O método deve ser sempre aplicado da seguinte forma:

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

Sob <query>, você deve es­pe­ci­fi­car os pa­râ­me­tros de busca que o método utilizará para filtrar os do­cu­men­tos — essa entrada é opcional. As entradas sob <projection> de­ter­mi­na­rão os campos do documento a serem exibidos: os valores su­por­ta­dos pela saída são os booleanos 1 (ver­da­deiro) e 0 (falso) — se esta entrada for deixada em branco, todos os campos serão exibidos. Assim sendo, essa parte também é opcional. Em <options>, você pode modificar a busca, além de alterar a exibição — essa entrada também é opcional.

Criar uma coleção de teste

Se você instalou o MongoDB no Linux, no Windows ou no Mac, re­co­men­da­mos que configure um ambiente de teste primeiro, para somente depois começar a usar o método MongoDB findOne. Para realizar esse tipo de con­fi­gu­ra­ção e obter uma melhor ideia de como mexer nesse sistema de banco de dados, acesse o nosso tutorial in­tro­du­tó­rio sobre o MongoDB.

No exemplo que ela­bo­ra­mos, criamos um banco de dados de fun­ci­o­ná­rios contendo cinco entradas, que incluem in­for­ma­ções como o nome, o gênero e a idade de cada um. Além disso, re­gis­tra­mos a data de início da pessoa na empresa. Assim ficou essa coleção:

// Create Collection
db.employee.insertMany ( [
   {
   name : "Santos",
   gender : "Female",
   age : 56,
   year : 2002
   },
   {
   name : "Barros",
   gender : "Female",
   age : 40,
   year : 2017,
   },
   {
   name : "Schmidt",
   gender : "Male",
   age : 40,
   year : 2019
   },
   {
   name : "Barbosa",
   gender : "Female",
   age : 44,
   year : 2015
   },
   {
   name : "Fernandes",
   gender : "Male",
   age : 22,
   year : 2022
   }
]
)

Pesquisar sem pa­râ­me­tros com o MongoDB findOne

Se você inserir o método findOne sem nenhum parâmetro, ele realizará buscas no seu banco de dados até encontrar as cinco entradas, já que todas serão con­si­de­ra­das. Como nenhum documento será excluído dessa pesquisa, todos os cinco fun­ci­o­ná­rios serão elegíveis. No entanto, o MongoDB findOne exibirá a primeira pessoa inserida no banco de dados, já que o método é capaz de retornar somente um resultado. Observe o que ocorre no exemplo:

db.employee.findOne ( )

Esta seria a saída retornada:

db.employee.findOne ( )
{
   _id : ObjectId ( "529ede7300af4002bce148ac" ),
   name : "Santos",
   gender : "Female",
   age : 56,
   year : 2002
}

Pesquisar entradas por ID com o MongoDB findOne

Na maioria das vezes, você vai querer es­pe­ci­fi­car sua busca para obter o documento exato que precisa, em vez de qualquer documento. O MongoDB findOne também oferece as fer­ra­men­tas certas para isso. Um jeito certeiro de se pesquisar por do­cu­men­tos é es­pe­ci­fi­cando o res­pec­tivo ID. O campo _id é único em cada documento e, portanto, sempre fará re­fe­rên­cia a um fun­ci­o­ná­rio es­pe­cí­fico, no nosso exemplo. Então, ao apli­car­mos o método MongoDB findOne ao ID do objeto, obteremos o resultado desejado, como mostra o nosso exemplo:

db.employee.findOne ( { _id : ObjectId ( "582bfa773813de982cf411b0" ) } )

A saída será esta:

db.employee.findOne ( { _id : ObjectId ( "582bfa773813de982cf411b0" ) } )
{
   _id : ObjectId ( "582bfa773813de982cf411b0" ),
   name : "Fernandes",
   gender : "Male",
   age : 22,
   year : 2022
}

Encontrar campos es­pe­cí­fi­cos com o MongoDB findOne

Se você não souber o ID que procura ou se deseja pesquisar sua coleção uti­li­zando outros pa­râ­me­tros, ainda pode usar o MongoDB findOne, já que ele é capaz de realizar buscas por outros critérios. Novamente, se houver apenas um documento que cor­res­ponda ao parâmetro, este será exibido. No entanto, se vários do­cu­men­tos cor­res­pon­de­rem aos critérios da pesquisa, o sistema exibirá apenas a primeira ocor­rên­cia do registro. No nosso exemplo, estamos pro­cu­rando por todos os registros de fun­ci­o­ná­rios do gênero masculino (Male). Te­o­ri­ca­mente, dois re­sul­ta­dos cor­res­pon­dem a esse critério. No entanto, apenas o primeiro é exibido. Observe o fun­ci­o­na­mento do comando:

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

Neste caso, a saída indicará o fun­ci­o­ná­rio de sobrenome Schmidt:

db.employee.findOne ( { gender : "Male" } )
{
   _id : ObjectId ( "498b0d173ce489fa63da00fa" ),
   name : "Schmidt",
   gender : "Male",
   age : 40,
   year : 2019
}

Es­pe­ci­fi­car uma busca com o MongoDB findOne

Ob­vi­a­mente, você também tem a opção de refinar ainda mais a sua pesquisa para evitar possíveis conflitos. Na nossa coleção de exemplo, que é pequena, a ação não seria, de fato, ne­ces­sá­ria. Contudo, se es­ti­vés­se­mos lidando com centenas ou milhares de entradas, cer­ta­mente faríamos uso dessa opção. O método MongoDB findOne permite que você es­pe­ci­fi­que vários critérios de pesquisa. Veja o que fizemos para iden­ti­fi­car um fun­ci­o­ná­rio es­pe­cí­fico, com base no gênero (Male) e na idade (40).

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

A saída mostrará novamente o fun­ci­o­ná­rio de sobrenome Schmidt, a única pessoa na coleção que é do gênero masculino e que tem 40 anos. A fun­ci­o­ná­ria de sobrenome Barros tem a mesma idade, mas é do gênero feminino:

db.employee.findOne ( { gender : "Male", age: 40 } )
{
   _id : ObjectId ( "498b0d173ce489fa63da00fa" ),
   name : "Schmidt",
   gender : "Male",
   age : 40,
   year : 2019
}

Definir condições para um campo com o MongoDB findOne

Também é possível es­pe­ci­fi­car condições para um campo e aplicá-las como critério de pesquisa, com o método findOne. No exemplo a seguir, ordenamos que apenas pessoas com mais de 30 anos fossem con­si­de­ra­das:

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

Por causa dessa es­pe­ci­fi­ca­ção, o fun­ci­o­ná­rio de sobrenome Fernandes é excluído. Como a fun­ci­o­ná­ria Santos atende ao critério e é a primeira pessoa da lista, ela é indicada como resultado:

db.employee.findOne ( { age : { $gt : 30 } } )
{
   _id : ObjectId ( "529ede7300af4002bce148ac" ),
   name : "Santos",
   gender : "Female",
   age : 56,
   year : 2002
}

Excluir campos com o MongoDB findOne

Par­ti­cu­lar­mente em coleções extensas, que também contêm muitas in­for­ma­ções, a saída exibida pode ser um tanto quanto confusa. Em casos como esse, você pode excluir campos in­di­vi­du­ais do resultado com o MongoDB findOne. No exemplo a seguir, desejamos que ID, gênero e idade não sejam exibidos.

db.employee.findOne ( { name : "Santos" }, { _id : 0, gender : 0, age : 0 } )

Como todas as outras in­for­ma­ções serão exibidas, assim ficará o resultado da busca:

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

Exemplo de pesquisa sem sucesso

Se não encontrar re­sul­ta­dos com­pa­tí­veis com a busca realizada, o método MongoDB findOne lhe avisará. No exemplo abaixo, pro­cu­ra­mos pelo fun­ci­o­ná­rio de sobrenome Lemos, que não está listado na coleção:

db.employee.findOne ( { name : "Lemos" }  )

Assim será o resultado apre­sen­tado:

db.employee.findOne ( { name : "Lemos" }  )
null