findOneAndDelete() (Excluir e Retornar um Documento)
Última atualização: 2026-10-09
findOneAndDelete() (Excluir e Retornar um Documento)
findOneAndDelete() remove o primeiro documento que corresponder a um filtro e retorna o próprio documento removido, ex.: `db.users.findOneAndDelete({ name: 'Cara' })`. Diferente de deleteOne(), que retorna apenas contadores, ele devolve o documento completo — útil para arquivar ou auditar exclusões. Retorna null quando nada corresponde.
| Categoria | Escrita |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
db.<collection>.findOneAndDelete(<filter>, { projection: <fields> })⚙️ Parâmetros
| filtro | Predicado que corresponde ao documento a excluir. |
|---|---|
| projection | Opcional. Controla quais campos do documento excluído são retornados. |
Retorno：O documento excluído; null quando nada corresponde.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// findOneAndDelete: remove Cara e imprime o registro dela
const removed = db.users.findOneAndDelete({ name: 'Cara' })
removedSaída：
{
_id: ObjectId('64c8a1b20000000000000003'),
name: 'Cara',
age: 30
}📌 Notas
- Retorna o documento removido para arquivamento ou auditoria
- Exclui apenas a primeira correspondência
- Retorna null em vez de lançar erro quando nada corresponde
🏷️ Tags Relacionados
💡 Casos Relacionados
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença entre findOneAndDelete e deleteOne?
AdeleteOne() retorna apenas deletedCount; findOneAndDelete() retorna o documento excluído completo para arquivamento e auditoria.
QO que findOneAndDelete retorna quando nada corresponde?
AEle retorna null sem lançar erro, permitindo saber se o filtro correspondeu a algo.
QO findOneAndDelete pode limitar os campos retornados?
ASim, por meio da opção projection — ex.: {projection: {name: 1}} retorna apenas o nome.
