findOne() (Consultar um Único Documento)
Última atualização: 2026-10-09
findOne() (Consultar um Único Documento)
findOne() retorna o primeiro documento que corresponder a um filtro diretamente como documento, não como cursor, ex.: `db.users.findOne({ name: 'Alice' })`. Quando vários correspondem, retorna o primeiro na ordem natural; sem correspondência, retorna null. Ele dispensa a iteração de cursor, sendo ideal para buscas por um campo único como _id ou nome de usuário.
| Categoria | Leitura |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
db.<collection>.findOne(<filter>, <projection>)⚙️ Parâmetros
| filtro | Objeto de predicado; suporta operadores de consulta. |
|---|---|
| projeção | Opcional. Controla os campos retornados: 1 inclui / 0 exclui. |
Retorno：O primeiro documento correspondente; null quando nada corresponde.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// findOne: busca um usuário por _id
const user = db.users.findOne(
{ _id: ObjectId('64c8a1b20000000000000001') },
{ name: 1, age: 1, _id: 0 }
)
userSaída：
{ name: 'Alice', age: 21 }📌 Notas
- Apenas a primeira correspondência é retornada; a ordem natural não é garantidamente estável
- Retorna null quando nada corresponde — proteja com if (doc)
- Mais limpo que find().limit(1) para leituras de um único documento
🏷️ Tags Relacionados
💡 Casos Relacionados
Excluindo documentos e primeiros passos com o Node.js
Documentos e BSON: a base dos dados do MongoDB
Modelos do Mongoose e projeto de esquemas
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QfindOne é o mesmo que find().limit(1)?
ASemelhante, mas findOne() retorna o documento diretamente enquanto find() retorna um cursor para iterar; prefira findOne() para buscas por campo único.
QO que findOne retorna quando nada é encontrado?
AEle retorna null sem lançar erro; normalmente consumido como if (doc) { ... }.
QO findOne pode retornar apenas alguns campos?
ASim — passe uma projeção como segundo argumento, ex.: {name: 1}.
