$setOnInsert (Definir na Inserção)
Última atualização: 2026-10-09
$setOnInsert (Definir na Inserção)
$setOnInsert define valores de campo apenas quando um upsert insere um novo documento; ele é ignorado quando um documento existente é correspondido. `{ $setOnInsert: { createdAt: new Date() } }`. Combinado com upsert: true, registra timestamps de criação e inicializa padrões — semântica de definir-na-criação, deixar-na-atualização.
| Categoria | Atualização de Campo |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $setOnInsert: { <campo>: <valor> } }⚙️ Parâmetros
| campo | O campo definido apenas na inserção. |
|---|---|
| valor | O valor inicial, por exemplo um horário de criação. |
Retorno：O resultado da atualização
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $setOnInsert: createdAt definido apenas na inserção
db.users.updateOne(
{ email: 'alice@example.com' },
{
$set: { name: 'Alice' },
$setOnInsert: { createdAt: new Date() }
},
{ upsert: true }
)Saída：
// createdAt é registrado na primeira inserção; atualizações posteriores o deixam intacto📌 Notas
- Aplica-se apenas quando o upsert insere
- Use junto com $set para que inicialização e atualização façam cada uma seu papel
- Ótimo para campos imutáveis como createdAt
🏷️ Tags Relacionados
💡 Casos Relacionados
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQuando $setOnInsert entra em vigor?
AApenas quando o upsert realmente insere; ignorado ao atualizar um documento existente.
Q$setOnInsert e $set podem ser usados juntos?
ASim; $set se aplica toda vez, $setOnInsert apenas na inserção.
Qupsert: true deve estar definido?
ASim, caso contrário ele nunca dispara em cenários de atualização pura.
