$addToSet
Definição
Compatibilidade
Você pode utilizar o $addToSet para implantações hospedadas nos seguintes ambientes:
MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem
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
O operador $addToSet tem o formato:
{ $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 apenas garante que não haja itens duplicados adicionados ao definir e não afeta os elementos duplicados existentes. $addToSet não garante uma ordenação específica dos elementos no conjunto modificado.
A partir do MongoDB 5.0, mongod não gera mais um erro ao usar um operador de atualização como $addToSet 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).
Campo ausente
Se você usar $addToSet em um campo que não está no documento a ser atualizado, $addToSet criará o campo de array com o valor especificado como seu elemento.
O campo não é uma array
Se você utilizar $addToSet em um campo que não for uma array, a operação falhará.
Por exemplo, crie a collection pigments:
db.pigments.insertOne( { _id: 1, colors: "blue, green, red" } )
O campo colors não é uma array. A seguinte operação $addToSet falha:
db.pigments.updateOne( { _id: 1 }, { $addToSet: { colors: "mauve" } } )
O valor a ser adicionado é uma array
Se o valor for uma array, $addToSet acrescentará a array inteira como um único elemento.
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
Para adicionar cada elemento do valor separadamente, utilize o modificador $each com $addToSet. Consulte $each Modificador para obter detalhes.
O valor a ser adicionado é um documento
Se o valor for um documento, o MongoDB determinará que o documento é uma duplicata 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. Dessa forma, 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
A operação $addToSet a seguir não tem efeito porque "camera" já é um elemento da array tags:
db.inventory.updateOne( { _id: 1 }, { $addToSet: { tags: "camera" } } )
$each Modifier
Você pode utilizar o operador $addToSet com o modificador $each. O modificador $each permite que o operador $addToSet adicione vários valores ao campo de array.
Uma collection inventory possui o seguinte documento:
{ _id: 2, item: "cable", tags: [ "electronics", "supplies" ] }
Em seguida, a operação a seguir usa o operador $addToSet com o modificador $each para adicionar vários elementos à array tags:
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" ] }