Definición
$addToSetEl operador
$addToSetagrega un valor a una matriz a menos que el valor ya esté presente, en cuyo caso$addToSetno hace nada a esa matriz.
Nota
Desambiguación
Esta página describe $addToSet cuando se utiliza como operador de actualizar.
También puede usar $addToSet en estos otros contextos:
$addToSet (accumulator), que devuelve un único valor agregado basado en un número variable de documentos de entrada.$addToSet (window function), que se utiliza en la$setWindowFieldsetapa para devolver un arreglo de valores únicos de documentos en una ventana determinada.
Compatibilidad
Puedes usar $addToSet para implementaciones alojadas en los siguientes entornos:
- MongoDB Atlas: El servicio totalmente administrado para implementaciones de MongoDB en la nube.
MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.
Sintaxis
El operador $addToSet tiene la forma:
{ $addToSet: { <field1>: <value1>, ... } }
Para especificar un <field> en un documento incrustado o en un arreglo, utiliza notación de puntos.
Comportamiento
A partir de MongoDB 5.0, los operadores de actualización procesan los campos de documentos con nombres basados en cadenas en orden lexicográfico. Los campos con nombres numéricos se procesan en orden numérico. Consulta Comportamiento del operador de actualización para obtener más información.
$addToSet solo garantiza que no se agreguen elementos duplicados al conjunto y no afecta a los elementos duplicados existentes. $addToSet no garantiza un orden particular de los elementos en el conjunto modificado.
A partir de MongoDB, 5.0, mongod ya no genera un error cuando se utiliza un operador de actualización como $addToSet con una expresión de operando vacía ( { } ). Una actualización vacía no produce cambios y no se crea ninguna entrada en el oplog (lo que significa que la operación no tiene efecto).
Campo ausente
Si utiliza $addToSet en un campo que no está presente en el documento que desea actualizar, $addToSet crea el campo de matriz con el valor especificado como su elemento.
El campo no es un arreglo
Si utiliza $addToSet en un campo que no es una matriz, la operación fallará.
Por ejemplo, cree la colección pigments:
db.pigments.insertOne( { _id: 1, colors: "blue, green, red" } )
El campo colors no es una matriz. La siguiente operación $addToSet falla:
db.pigments.updateOne( { _id: 1 }, { $addToSet: { colors: "mauve" } } )
El valor a añadir es un arreglo
Si el valor es una matriz, $addToSet agrega toda la matriz como un solo elemento.
Crear la colección alphabet:
db.alphabet.insertOne( { _id: 1, letters: ["a", "b"] } )
La siguiente operación agrega el arreglo [ "c", "d" ] al campo letters:
db.alphabet.updateOne( { _id: 1 }, { $addToSet: { letters: [ "c", "d" ] } } )
El arreglo [ "c", "d" ] se añade como un único elemento:
{ _id: 1, letters: [ 'a', 'b', [ 'c', 'd' ] ] }
Tip
Para agregar cada elemento del valor por separado, use el modificador $each con $addToSet. Consulte el modificador $each para obtener más detalles.
El valor a agregar es un documento
Si el valor es un documento, MongoDB determina que el documento es un duplicado si un documento existente en el arreglo coincide exactamente con el documento que se va a agregar. Es decir, el documento existente tiene exactamente los mismos campos y valores y los campos están en el mismo orden. El orden de los campos es importante y no puede especificar que MongoDB compare solo un subconjunto de los campos del documento para determinar si el documento es un duplicado de un elemento existente en el arreglo.
Ejemplos
Crear la colección inventory:
db.inventory.insertOne( { _id: 1, item: "polarizing_filter", tags: [ "electronics", "camera" ] } )
Agregar al arreglo
La siguiente operación añade el elemento "accessories" al arreglo tags dado que "accessories" no existe en el arreglo:
db.inventory.updateOne( { _id: 1 }, { $addToSet: { tags: "accessories" } } )
El valor ya existe
La siguiente operación $addToSet no tiene efecto porque "camera" ya es un elemento del array tags:
db.inventory.updateOne( { _id: 1 }, { $addToSet: { tags: "camera" } } )
$each Modifier
Puedes usar el operador $addToSet con el modificador $each. El modificador $each permite que el operador $addToSet agregue múltiples valores al campo de matriz.
Una colección inventory tiene el siguiente documento:
db.inventory.insertOne ( { _id: 2, item: "cable", tags: [ "electronics", "supplies" ] } )
Luego, la siguiente operación utiliza el operador $addToSet con el modificador $each para agregar múltiples elementos al array tags:
db.inventory.updateOne( { _id: 2 }, { $addToSet: { tags: { $each: [ "camera", "electronics", "accessories" ] } } } )
La operación solo agrega "camera" y "accessories" al arreglo tags. "electronics" ya estaba en el arreglo:
{ _id: 2, item: "cable", tags: [ "electronics", "supplies", "camera", "accessories" ] }