findOneAndReplace() (Substituir e Retornar um Documento)
Última atualização: 2026-10-09
findOneAndReplace() (Substituir e Retornar um Documento)
findOneAndReplace() troca o primeiro documento que corresponder a um filtro por um documento de substituição e retorna o documento antes ou depois da troca, ex.: `db.users.findOneAndReplace({ name: 'Bob' }, { name: 'Bob', age: 26 }, { returnDocument: 'after' })`. Diferente de replaceOne(), ele lê o documento de volta, adequando-se a fluxos que precisam do resultado da substituição. Todos os campos, exceto _id, são sobrescritos.
| Categoria | Escrita |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
db.<collection>.findOneAndReplace(<filter>, <replacement>, { returnDocument: 'after', upsert: <bool> })⚙️ Parâmetros
| filtro | Predicado que corresponde ao documento a substituir. |
|---|---|
| novo documento | A substituição completa; sobrescreve todos os campos exceto _id. |
| returnDocument | Opcional. 'before' ou 'after'; o padrão é 'before'. |
Retorno：O documento antes (ou depois) da substituiçã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):
// findOneAndReplace: troca o doc de Bob, retorna o novo
const doc = db.users.findOneAndReplace(
{ name: 'Bob' }, { name: 'Bob', age: 26, vip: true },
{ returnDocument: 'after' }
)
docSaída：
{
_id: ObjectId('64c8a1b20000000000000002'),
name: 'Bob',
age: 26,
vip: true
}📌 Notas
- A substituição deve manter o _id original ou um erro é lançado
- O _id retornado é sempre o original (mesmo quando upsert insere)
- A substituição sobrescreve por completo — garanta que o novo documento carregue todos os campos necessários
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença entre findOneAndReplace e replaceOne?
AreplaceOne() retorna contadores; findOneAndReplace() retorna o documento antes ou depois da troca.
QO findOneAndReplace pode alterar o _id?
ANão — a substituição deve manter o _id original ou a operação falha.
QO que findOneAndReplace retorna com upsert ligado?
AQuando nada corresponde, um novo documento é inserido e retornado, carregando o _id recém-gerado.
