/ /

Update

arrays

Página inicial do Docs

Desenvolvimento

Linguagem de query

Update

arrays

$addToSet (operador de atualização)

Definição

$addToSet: The $addToSet operator adds a value to an array unless the value is already present, in which case $addToSet does nothing to that array.

Observação

Desambiguação

Esta página descreve $addToSet quando usado como um operador de atualizar.

Você também pode usar $addToSet nestes outros contextos:

$addToSet (accumulator), que retorna um único valor agregado com base em um número variável de documentos de entrada.
$addToSet (window function), que é usado no $setWindowFields estágio para retornar uma array de valores únicos de documentos em uma janela específica.

Compatibilidade

Você pode utilizar o $addToSet 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 $addToSet operator has the form:

{ $addToSet: { <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.

$addToSet only ensures that there are no duplicate items added to the set and does not affect existing duplicate elements. $addToSet does not guarantee a particular ordering of elements in the modified set.

Starting in MongoDB 5.0, mongod no longer raises an error when you use an update operator like $addToSet 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).

Campo ausente

If you use $addToSet on a field that is absent from the document to update, $addToSet creates the array field with the specified value as its element.

O campo não é uma array

If you use $addToSet on a field that is not an array, the operation fails.

Por exemplo, crie a collection pigments:

db.pigments.insertOne( { _id: 1, colors: "blue, green, red" } )

The colors field is not an array. The following $addToSet operation fails:

db.pigments.updateOne(
   { _id: 1 },
   { $addToSet: { colors: "mauve" } }
)

O valor a ser adicionado é uma array

If the value is an array, $addToSet appends the whole array as a single element.

Crie a coleção alphabet:

db.alphabet.insertOne( { _id: 1, letters: ["a", "b"] } )

A seguinte operação anexa a array [ "c", "d" ] ao campo letters:

db.alphabet.updateOne(
   { _id: 1 },
   { $addToSet: { letters: [ "c", "d" ] } }
)

A array [ "c", "d" ] é adicionada como um único elemento:

{ _id: 1, letters: [ 'a', 'b', [ 'c', 'd' ] ] }

Dica

To add each element of the value separately, use the $each modifier with $addToSet. See $each Modifier for details.

O valor a ser adicionado é um documento

Se o valor for um documento, o MongoDB determinará que o documento é duplicado se um documento existente na array corresponder exatamente ao documento a ser adicionado. Ou seja, o documento existente tem exatamente os mesmos campos e valores e os campos estão na mesma ordem. A ordem dos campos é importante e você não pode especificar que o MongoDB compare apenas um subconjunto dos campos no documento para determinar se o documento é uma duplicata de um elemento de array existente.

Exemplos

Crie a coleção inventory:

db.inventory.insertOne(
   { _id: 1, item: "polarizing_filter", tags: [ "electronics", "camera" ] }
)

Adicionar à array

A operação a seguir adiciona o elemento "accessories" à array tags, uma vez que "accessories" não existe na array:

db.inventory.updateOne(
   { _id: 1 },
   { $addToSet: { tags: "accessories" } }
)

O valor já existe

The following $addToSet operation has no effect because "camera" is already an element of the tags array:

db.inventory.updateOne(
   { _id: 1 },
   { $addToSet: { tags: "camera"  } }
)

`$each` Modifier

You can use the $addToSet operator with the $each modifier. The $each modifier allows the $addToSet operator to add multiple values to the array field.

Uma collection inventory possui o seguinte documento:

db.inventory.insertOne (
   { _id: 2, item: "cable", tags: [ "electronics", "supplies" ] }
)

Then the following operation uses the $addToSet operator with the $each modifier to add multiple elements to the tags array:

db.inventory.updateOne(
   { _id: 2 },
   { $addToSet: { tags: { $each: [ "camera", "electronics", "accessories" ] } } }
 )

A operação só adiciona "camera" e "accessories" à array tags. "electronics" já estava na array:

{
  _id: 2,
  item: "cable",
  tags: [ "electronics", "supplies", "camera", "accessories" ]
}