Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB
$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 MongoDB na nuvem
MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão 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 quando você usa um operador de atualização como $addToSet com uma expressão de operando vazia ( { } ). Uma atualização vazia não resulta em nenhuma alteração e nenhuma entrada no oplog é criada (o que significa que a operação é um no-op).
Campo ausente
Se você usar $addToSet em um campo ausente do documento para atualizar, $addToSet criará o campo de array com o valor especificado como seu elemento.
O campo não é uma array
Se você usar $addToSet em um campo que não seja 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 Modificador$each 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 seguinte operação $addToSet não tem efeito porque "camera" já é um elemento da array tags :
db.inventory.updateOne( { _id: 1 }, { $addToSet: { tags: "camera" } } )
$each Modificador
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" ] }