$set (operador de atualização)

Definição

Observação

Desambiguação

The following page refers to the update operator $set. For the aggregation stage, see $set.

$set: The $set operator replaces the value of a field with the specified value.

Compatibilidade

Você pode utilizar o $set para implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

The $set operator expression has the following form:

{ $set: { <field1>: <value1>, ... } }

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.

If the field does not exist, $set adds a new field with the specified value if the new field does not violate a type constraint. If you specify a dotted path for a non-existent field, $set creates the embedded documents as needed to fulfill the dotted path to the field.

If you specify multiple field-value pairs, $set updates or creates each field.

Starting in MongoDB 5.0, mongod no longer raises an error when you use an update operator like $set with an empty operand expression ( { } ). An empty update results in no changes and no oplog entry is created (meaning that the operation is a no-op).

Vantagens de $set

O operador $set oferece as seguintes vantagens em comparação com a substituição completa do documento :

Atualizações Direcionadas: $set modifica somente os campos especificados, garantindo atualizações eficientes, evitando gravações e sobrecarga desnecessárias quando você trabalha com documentos grandes.
Entradas eficientes do Oplog: $set otimiza a replicação gravando apenas os campos atualizados no oplog em vez de todo o documento. Esse processo reduz o tamanho das entradas de oplog e permite que os nós repliquem as alterações com mais eficiência.
Lógica simplificada: os aplicativos que usam o $set não precisam calcular campos alterados antes de enviar uma atualização. O MongoDB reduz a complexidade ao lidar com a computação delta internamente.

Exemplos

Os exemplos nesta página usam dados do conjunto de dados sample_mflix. Para obter detalhes sobre como carregar este conjunto de dados em sua implantação do MongoDB autogerenciado, consulte Carregar o conjunto de dados de amostra. Se você fez alguma modificação nos bancos de dados de amostra, talvez seja necessário descartar e recriar os bancos de dados para executar os exemplos nesta página.

Definir campos de nível superior

The following example uses the $set operator to add the label and status fields to the matching movie document:

db.movies.updateOne(
   { title: "The Dark Knight" },
   {
      $set: {
         label: "Award Winner",
         status: "classic"
      }
   }
)

A operação retorna o seguinte resultado:

{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}

Definir campos em documentos incorporados

O exemplo a seguir usa a notação de ponto para atualizar o campo highlight do documento incorporado imdb no filme correspondente:

db.movies.updateOne(
   { title: "The Dark Knight" },
   { $set: { "imdb.highlight": "Critics' Choice" } }
)

A operação retorna o seguinte resultado:

{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}

Importante

O exemplo anterior usa a notação de ponto para atualizar o campo highlight do documento incorporado imdb. O formato a seguir, em vez disso, substitui todo o documento incorporado, removendo todos os outros campos de imdb:

db.movies.updateOne(
   { title: "The Dark Knight" },
   { $set: { imdb: { highlight: "Critics' Choice" } } }
)

Definir elementos em arrays

The following example uses the $set operator to update the first element (array index 0) of the genres array in the matching movie document:

db.movies.updateOne(
   { title: "The Dark Knight" },
   { $set: { "genres.0": "Thriller" } }
)

A operação retorna o seguinte resultado:

{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}

Para operadores de atualização adicionais para arrays, consulte Operadores de atualização de array.

Dica

Voltar

$renomear

$setOnInsert