updateOne() (Atualizar um Único Documento)
Última atualização: 2026-10-09
updateOne() (Atualizar um Único Documento)
updateOne() atualiza o primeiro documento que corresponder a um filtro. Se vários corresponderem, apenas o primeiro (na ordem natural) é atualizado. As modificações são expressas com operadores de atualização ($set/$inc/$push...). O resultado inclui matchedCount, modifiedCount e upsertedId.
| Categoria | Escrita |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
db.<collection>.updateOne(<filter>, <update>, { upsert: <bool> })⚙️ Parâmetros
| filtro | Objeto de predicado que corresponde a documentos; suporta operadores de consulta. |
|---|---|
| atualização | Objeto de operadores de atualização, por exemplo {$set: {age: 22}}. |
| upsert | Opcional. Insere um novo documento quando nada corresponde; o padrão é false. |
Retorno：UpdateResult: { acknowledged, matchedCount, modifiedCount, upsertedId }.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// updateOne: define a idade de Alice para 22
db.users.updateOne(
{ name: "Alice" },
{ $set: { age: 22 } }
)Saída：
{ acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null }📌 Notas
- Atualiza apenas a primeira correspondência; use updateMany() para todas
- O documento de atualização deve usar operadores de atualização — use replaceOne() para substituir por completo
- Com upsert: true, insere um novo documento quando nada corresponde
- Operadores conflitantes no mesmo campo (ex.: $set e $inc) não são permitidos
🏷️ Tags Relacionados
💡 Casos Relacionados
Modelos do Mongoose e projeto de esquemas
Processamento de transações: ACID e consistência entre múltiplos documentos
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença entre updateOne e findOneAndUpdate?
AupdateOne retorna apenas contadores (matched/modifiedCount); findOneAndUpdate retorna o documento antes (ou depois) da atualização, útil quando você precisa do valor antigo/novo.
QO que acontece se updateOne corresponder a vários documentos?
AEle atualiza apenas o primeiro documento correspondente. Use updateMany para atualizar todas as correspondências; se a ordem importar, passe a opção sort para controlar qual documento é tratado como primeiro.
QO updateOne pode combinar $set e $inc?
ASim. O documento de atualização pode conter vários operadores, ex.: { $set: { status: 'active' }, $inc: { visits: 1 } }, aplicados atomicamente em ordem.
