findOneAndUpdate() (Atualizar e Retornar um Documento)
Última atualização: 2026-10-09
findOneAndUpdate() (Atualizar e Retornar um Documento)
findOneAndUpdate() atualiza o primeiro documento que corresponder a um filtro e retorna o próprio documento — antes ou depois da atualização, controlado por `returnDocument`: 'before' (padrão) ou 'after', ex.: `db.users.findOneAndUpdate({ name: 'Alice' }, { $set: { age: 22 } }, { returnDocument: 'after' })`. Diferente de updateOne(), que retorna apenas contadores, ele lê o documento de volta, adequando-se a fluxos que precisam do valor atualizado imediatamente, como contadores ou transições de máquinas de estado.
| Categoria | Escrita |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
db.<collection>.findOneAndUpdate(<filter>, <update>, { returnDocument: 'after', upsert: <bool> })⚙️ Parâmetros
| filtro | Predicado que corresponde ao documento a atualizar. |
|---|---|
| atualização | Objeto de operadores de atualização, por exemplo {$inc: {count: 1}}. |
| returnDocument | Opcional. 'before' retorna o documento antes da atualização, 'after' o depois; o padrão é 'before'. |
| upsert | Opcional. Insere quando nada corresponde; padrão false. |
Retorno：O documento antes (ou depois) da atualização; null se nada corresponder e o upsert estiver desativado.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// findOneAndUpdate: atualiza Alice, retorna o novo doc
const doc = db.users.findOneAndUpdate(
{ name: 'Alice' }, { $set: { age: 22 } },
{ returnDocument: 'after' }
)
docSaída：
{
_id: ObjectId('64c8a1b20000000000000001'),
name: 'Alice',
age: 22
}📌 Notas
- Retorna o documento pré-atualização por padrão; defina returnDocument: 'after' para o novo valor
- Drivers legados chamam isso de findAndModify com a opção new em vez de returnDocument
- updateOne() retorna contadores; use este método quando precisar do próprio documento
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QO findOneAndUpdate retorna o documento antes ou depois da atualização?
APor padrão retorna o documento pré-atualização; passe {returnDocument: 'after'} para o pós-atualização.
QQual é a diferença entre findOneAndUpdate e updateOne?
AupdateOne() retorna apenas contadores; findOneAndUpdate() retorna o documento, útil quando você precisa do valor antigo ou novo.
QO que findOneAndUpdate retorna quando nada corresponde?
AEle retorna null (com upsert desligado). Com upsert ligado, um novo documento é inserido e retornado.
