replaceOne() (Substituir um Documento)
Última atualização: 2026-10-09
replaceOne() (Substituir um Documento)
replaceOne() troca o primeiro documento que corresponder a um filtro por um documento totalmente novo. Diferente de updateOne(), cujo segundo argumento usa operadores de atualização, aqui o segundo argumento é o próprio documento de substituição — todos os campos, exceto _id, são sobrescritos. O resultado inclui matchedCount e modifiedCount. É a ferramenta certa quando a estrutura de um documento precisa ser reescrita por completo.
| Categoria | Escrita |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
db.<collection>.replaceOne(<filter>, <replacement>, { upsert: <bool> })⚙️ Parâmetros
| filtro | Predicado que corresponde ao documento a substituir. |
|---|---|
| novo documento | O documento de substituição completo; sobrescreve todos os campos exceto _id. |
| upsert | Opcional. Insere quando nada corresponde; padrão false. |
Retorno：UpdateResult: { acknowledged, matchedCount, modifiedCount, upsertedId }.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// replaceOne: substitui o documento de Bob por completo
db.users.replaceOne(
{ name: 'Bob' },
{ name: 'Bob', age: 26, city: 'Shanghai', vip: true }
)Saída：
{ acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null }📌 Notas
- A substituição deve manter o _id (ou omiti-lo para o original sobreviver), caso contrário um erro é lançado
- Operadores de atualização como {$set: ...} não são interpretados aqui — seriam armazenados como campos literais
- Apenas a primeira correspondência é substituída; faça loop ou use updateMany() para trabalhos em lote
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença entre replaceOne e updateOne?
AupdateOne() altera campos incrementalmente com operadores; replaceOne() troca por um documento inteiramente novo, sobrescrevendo todos os campos exceto _id.
QO replaceOne pode alterar o _id?
ANão. _id é imutável; a substituição deve manter o _id original ou um erro é lançado.
QOperadores de atualização podem ir no segundo argumento de replaceOne?
ANão. O segundo argumento é o documento de substituição; {$set: ...} seria armazenado literalmente como um campo.
