# MongoDB findOne: instruções com exemplos O método MongoDB findOne é muito eficaz quando é necessário pesquisar dentro de uma coleção. No entanto, ele retorna apenas um resultado, portanto não é adequado para todas as necessidades. ## O que é MongoDB findOne? [O MongoDB](https://www.ionos.com/pt-pt/digitalguide/paginas-web/desenvolvimento-web/mongodb-apresentacao-e-comparacao-com-o-mysql/) é um sistema de gestão de bases de dados capaz de lidar com grandes quantidades de dados de forma eficiente, graças à sua abordagem NoSQL e à sua escalabilidade. Apesar de oferecer grandes vantagens, também requer métodos sólidos para que os utilizadores possam manter a visibilidade sobre a base de dados ao trabalhar com ela. O sistema armazena dados de todos os tipos na forma de documentos BSON (JSON binário) e agrupa esses documentos como coleções. Se você deseja pesquisar e obter um desses documentos, há várias possibilidades. Além do mais comum MongoDB find, o MongoDB findOne é um **método particularmente eficaz** para filtrar com precisão até mesmo bases de dados extensas. O MongoDB findOne realiza pesquisas em todos os documentos e coleções considerados de acordo com critérios que podem ser especificados pelo utilizador. A particularidade do método é que **ele sempre retorna um único documento** que corresponde aos parâmetros armazenados. Se houver apenas um documento que corresponda à pesquisa, esse documento será selecionado. Se houver vários documentos correspondentes, o MongoDB findOne retornará o documento que aparece em primeiro lugar na ordem natural do banco de dados. Se nenhum documento for encontrado na pesquisa, o resultado será “zero”. ## Sintaxe e particularidades do MongoDB findOne A sintaxe básica do MongoDB findOne é simples. O método é sempre utilizado da seguinte forma: ```shell db.collection.findOne (, , ) ``` Em `` são indicados os parâmetros de pesquisa segundo os quais o método deve filtrar os documentos. Esta entrada é opcional. As entradas em `` determinam quais campos devem ser considerados para o documento exibido. Os valores permitidos para o resultado são os booleanos 1 (verdadeiro) e 0 (falso). Se este dado for deixado em branco, todos os campos serão exibidos. Também é opcional. ``, também opcional, permite modificar ainda mais a pesquisa e alterar a visualização. Nota Para pesquisar coleções com vários parâmetros de pesquisa de forma eficaz, existem as [consultas MongoDB](https://www.ionos.com/pt-pt/digitalguide/paginas-web/desenvolvimento-web/consultas-mongodb/), que explicaremos com mais detalhes em outro artigo. As consultas ou Queries são baseadas no comando MongoDB find. ## Criar uma coleção de teste Se instalou o MongoDB no Linux, Windows ou Mac e deseja utilizar o MongoDB findOne, vale a pena configurar 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 funcionários que contém cinco entradas e informações sobre o nome, sexo, idade do funcionário e há quanto tempo trabalha na empresa. Esta coleção tem a seguinte aparência: ```shell # 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 parâmetros Se agora utilizar o método findOne do MongoDB **sem nenhum parâmetro**, o sistema pesquisará na sua base de dados e encontrará cinco entradas que deverá selecionar. Como não são excluídos documentos, os cinco funcionários são elegíveis. Por isso, o MongoDB findOne selecionaria a primeira pessoa introduzida na base de dados, porque o método apenas retorna um resultado. Esta seria a aparência no nosso exemplo: ```shell db.empleados.findOne ( ) ``` E este é o resultado correspondente: ```shell db.empleados.findOne ( ) { _id : ObjectID ( "529ete7300of4002bme148om" ), name : "Ortiz", gender : "Female", age : 56, year : 2002 } ``` ## Pesquisar entradas por ID No entanto, o normal é que queira especificar a sua pesquisa para não acabar com qualquer documento e obter aquele que realmente precisa. O MongoDB findOne também oferece ferramentas 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 exatamente a um funcionário ou funcionária no nosso exemplo. Assim, ao executar o MongoDB findOne utilizando o ID do objeto, obterá o resultado correto. No nosso exemplo, ficaria assim: ```shell db.empleados.findOne ( { _id : ObjectID ( "582pfh773813tw982qj411l0" ) } ) ``` O resultado deve ser este: ```shell 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 utilizando outros parâmetros, também pode pesquisar filtrando por campos especiais graças ao MongoDB findOne. Neste caso, ocorre o mesmo: se houver apenas um documento que corresponda ao parâmetro, ele será exibido. No entanto, se vários documentos corresponderem aos critérios de pesquisa, o sistema exibirá apenas a primeira entrada. No nosso exemplo, portanto, procuramos todas as entradas que indiquem «Male» (homem) como sexo. Em teoria, teríamos dois resultados, mas apenas o primeiro é apresentado. É assim que o comando deve aparecer: ```shell db.empleados.findOne ( { gender : "Male" } ) ``` No resultado aparece o funcionário Ruiz: ```shell db.empleados.findOne ( { gender : "Male" } ) { _id : ObjectID ( "498p0t173mv489fh63th00kh" name : "Ruiz", gender : "Male", age : 40, year : 2019 } ``` ## MongoDB findOne: especificar pesquisa É claro que também pode refinar ainda mais a pesquisa para evitar sobreposições. Isso talvez não seja necessá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 identificar um funcionário por género (homem) e idade, ficará assim: ```shell db.empleados.findOne ( { gender : "Male", age: 40 } ) ``` O resultado volta a mostrar o funcionário Ruiz, que é a única pessoa da coleção que é homem e tem 40 anos. A funcionária Murillo teria a mesma idade, mas é mulher. O resultado teria a seguinte aparência: ```shell 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 específico e utilizá-las como critério de pesquisa. No exemplo a seguir, consideramos apenas pessoas com mais de 30 anos. Escrever-se-ia assim: ```shell db.empleados.findOne ( { age : { $gt : 30 } } ) ``` Neste caso, o funcionário Jacobo é excluído. Como a Sra. Ortiz cumpre o critério e é a primeira pessoa da lista, ela volta a ser exibida: ```shell 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, especialmente em coleções extensas que também contêm muitas informações. Por isso, o MongoDB findOne oferece a possibilidade de **excluir campos individuais do resultado**. No exemplo a seguir, não queremos que o ID, o sexo e a idade sejam exibidos. ```shell db.empleados.findOne ( { name : "Ortiz" }, { _id : 0, gender : 0, age : 0 } ) ``` Como todos os outros dados são exibidos, obterá este resultado: ```shell 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 resultados para a pesquisa com MongoDB findOne, isso também será indicado. Vamos procurar, por exemplo, o funcionário Sanz, que não consta na coleção: ```shell db.empleados.findOne ( { name : "Sanz" } ) ``` Este será o resultado: ```shell db.empleados.findOne ( { name : "Sanz" } ) null ``` Dica Para gerir facilmente a sua base de dados, pode utilizar a interface gráfica de utilizador gratuita [MongoDB Compass](https://www.ionos.com/pt-pt/digitalguide/paginas-web/desenvolvimento-web/mongodb-compass/), sobre a qual falamos noutro artigo. This is a markdown version of: [https://www.ionos.com/pt-pt/digitalguide/paginas-web/desenvolvimento-web/mongodb-findone/](https://www.ionos.com/pt-pt/digitalguide/paginas-web/desenvolvimento-web/mongodb-findone/) for AI/LLM consumption.