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 gerenciamento de banco de dados (DBMS) que, por causa de sua abordagem NoSQL e de sua escalabilidade acentuada, consegue armazenar e gerenciar grandes volumes de dados sem qualquer dificuldade. Embora essa seja sua grande vantagem, o MongoDB exige que seus usuários adotem métodos robustos para manter a organização dos bancos de dados.

O MongoDB é capaz de armazenar dados de qualquer tipo no formato BSON (JSON binário) e de agrupar esses documentos em coleções. Para buscar e exibir um desses documentos, você pode utilizar-se de diferentes métodos: alternativamente ao MongoDB find que é mais geral, adote o método extremamente eficaz MongoDB findOne para filtrar até mesmo bancos de dados extensos com precisão.

O findOne consegue realizar pesquisas em todos os documentos e coleções a serem considerados, com base nos critérios especificados pelo usuário. O principal diferencial desse método é que ele sempre retorna um único documento que corresponda aos critérios inseridos. Assim, se apenas um documento corresponder à consulta, este será retornado. Contudo, se vários documentos forem encontrados, o findOne retornará somente o primeiro que estiver na ordem natural do banco de dados. Por fim, se nenhum documento for encontrado pela busca, a saída exibida será “null”.

Sintaxe e diferencial 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 especificar os parâmetros de busca que o método utilizará para filtrar os documentos — essa entrada é opcional. As entradas sob <projection> determinarão os campos do documento a serem exibidos: os valores suportados pela saída são os booleanos 1 (verdadeiro) 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, recomendamos que configure um ambiente de teste primeiro, para somente depois começar a usar o método MongoDB findOne. Para realizar esse tipo de configuração e obter uma melhor ideia de como mexer nesse sistema de banco de dados, acesse o nosso tutorial introdutório sobre o MongoDB.

No exemplo que elaboramos, criamos um banco de dados de funcionários contendo cinco entradas, que incluem informações como o nome, o gênero e a idade de cada um. Além disso, registramos a data de início da pessoa na empresa. Assim ficou essa coleção:

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 parâmetros 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 consideradas. Como nenhum documento será excluído dessa pesquisa, todos os cinco funcioná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 ( "529ete7300of4002bme148om" ),
    name : "Santos",
    gender : "Female",
    age : 56,
    year : 2002
}

Pesquisar entradas por ID com o MongoDB findOne

Na maioria das vezes, você vai querer especificar sua busca para obter o documento exato que precisa, em vez de qualquer documento. O MongoDB findOne também oferece as ferramentas certas para isso. Um jeito certeiro de se pesquisar por documentos é especificando o respectivo ID. O campo _id é único em cada documento e, portanto, sempre fará referência a um funcionário específico, no nosso exemplo. Então, ao aplicarmos o método MongoDB findOne ao ID do objeto, obteremos o resultado desejado, como mostra o nosso exemplo:

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

A saída será esta:

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

Encontrar campos específicos com o MongoDB findOne

Se você não souber o ID que procura ou se deseja pesquisar sua coleção utilizando outros parâmetros, ainda pode usar o MongoDB findOne, já que ele é capaz de realizar buscas por outros critérios. Novamente, se houver apenas um documento que corresponda ao parâmetro, este será exibido. No entanto, se vários documentos corresponderem aos critérios da pesquisa, o sistema exibirá apenas a primeira ocorrência do registro. No nosso exemplo, estamos procurando por todos os registros de funcionários do gênero masculino (Male). Teoricamente, dois resultados correspondem a esse critério. No entanto, apenas o primeiro é exibido. Observe o funcionamento do comando:

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

Neste caso, a saída indicará o funcionário de sobrenome Schmidt:

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

Especificar uma busca com o MongoDB findOne

Obviamente, 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, necessária. Contudo, se estivéssemos lidando com centenas ou milhares de entradas, certamente faríamos uso dessa opção. O método MongoDB findOne permite que você especifique vários critérios de pesquisa. Veja o que fizemos para identificar um funcionário específico, com base no gênero (Male) e na idade (40).

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

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

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

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

Também é possível especificar 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 consideradas:

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

Por causa dessa especificação, o funcionário de sobrenome Fernandes é excluído. Como a funcionária Santos atende ao critério e é a primeira pessoa da lista, ela é indicada como resultado:

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

Excluir campos com o MongoDB findOne

Particularmente em coleções extensas, que também contêm muitas informações, a saída exibida pode ser um tanto quanto confusa. Em casos como esse, você pode excluir campos individuais 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 informaçõ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 resultados compatíveis com a busca realizada, o método MongoDB findOne lhe avisará. No exemplo abaixo, procuramos pelo funcionário de sobrenome Lemos, que não está listado na coleção:

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

Assim será o resultado apresentado:

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