$setOnInsert (operador de atualização)

Definição

$setOnInsert

Se uma operação de atualização com upsert: verdadeiro resultar em uma inserção de um documento, então atribuirá os valores especificados aos campos no $setOnInsert documento. Se a operação de atualização não resultar em uma inserção, não fará$setOnInsert nada.

Você pode especificar a opção upsert para:

• db.collection.updateOne()

• db.collection.updateMany()

• db.collection.findOneAndUpdate()

db.collection.updateOne(
   <query>,
   { $setOnInsert: { <field1>: <value1>, ... } },
   { upsert: true }
)

Para especificar um <field> em um documento incorporado ou em uma array, use a notação de ponto.

Comportamento

A partir do MongoDB 5.0, os operadores de atualização processam campos de documento com nomes baseados em cadeia de caracteres em ordem lexicográfica. Os campos com nomes numéricos são processados em ordem numérica. Consulte Atualizar Comportamento de Operadores para detalhes.

A partir do MongoDB 5.0, mongod não gera mais um erro ao usar um operador de atualização como $setOnInsert com uma expressão de operando vazia ( { } ). Uma atualização vazia não resulta em alteração e nenhuma entrada no oplog é criada (o que significa que é sem operação).

Exemplo

A collection products não contém documentos.

Insira um novo documento utilizando o parâmetro upsert: verdadeiro db.collection.updateOne().

db.products.updateOne(
  { _id: 1 },
  {
     $set: { item: "apple" },
     $setOnInsert: { defaultQty: 100 }
  },
  { upsert: true }
)

O MongoDB usa <query> para criar um novo documento com _id: 1. $setOnInsert atualiza o documento conforme especificado.

A collection products contém o documento recém-inserido:

{ "_id" : 1, "item" : "apple", "defaultQty" : 100 }

Quando o parâmetro upsert é true db.collection.updateOne():

• cria um novo documento

• aplica a operação $set

• aplica a operação $setOnInsert

Se db.collection.updateOne() corresponder a um documento existente, o MongoDB aplicará somente a operação $set.