db.collection.updateOne()

upsert em uma coleção fragmentada

Para usar db.collection.updateOne() em uma coleção fragmentada:

• Se você não especificar upsert: true, deverá incluir uma correspondência exata no campo _id ou direcionar um único fragmento (por exemplo, incluindo a chave de fragmento no filtro).

• Se você especificar upsert: true, o filtro deverá incluir a chave de fragmento.

No entanto, os documentos em uma coleção fragmentada podem estar faltando os campos de chave de fragmento. Para direcionar um documento que não possui a chave de fragmento, você pode usar a null correspondência de igualdade em conjunto com outra condição de filtro (como no campo _id ). Por exemplo:

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key

Modificação da chave de fragmento

Você pode atualizar o valor da chave de fragmento de um documento, a menos que o campo de chave de fragmento seja o campo de _id imutável.

Para modificar o valor da chave de fragmento existente com db.collection.updateOne():

• Você deve executar em um mongos. Não emita a operação diretamente no fragmento.

• Você deve executar em uma transação ou como uma gravação repetível.

• Você deve incluir um filtro de igualdade na chave de fragmento completa.

Consulte também upsert em uma coleção fragmentada.

Chave de fragmento ausente

Os documentos em coleções fragmentadas podem não ter os campos de chave de fragmento. Para usar db.collection.updateOne() a fim de definir a chave de fragmento ausente do documento, é necessário executar em um mongos. Não emita a operação diretamente no fragmento.

Além disso, os seguintes requisitos também se aplicam:

Veja também:

• upsert em uma coleção fragmentada

• Campos de chave de fragmentação ausentes

Inserção nas Transações

Você pode criar coleção e índices dentro de uma transação distribuída se a transação não for uma transação de gravação cross-fragmento.

db.collection.updateOne() com upsert: true pode ser executado em uma coleção existente ou em uma coleção inexistente. Se for executada em uma coleção inexistente, a operação cria a coleção.

Write concerns e transações

Não defina explicitamente a preocupação de gravação para a operação se for executada em uma transação. Para usar write concern com transações, consulte Transações e write concern.

Exemplo 1

Os exemplos a seguir usam o aggregation pipeline para modificar um campo usando os valores de outros campos no documento.

Criar uma coleção students com os seguintes documentos:

db.students.insertMany( [
   { "_id" : 1, "student" : "Skye", "points" : 75, "commentsSemester1" : "great at math", "commentsSemester2" : "loses temper", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") },
   { "_id" : 2, "student" : "Elizabeth", "points" : 60, "commentsSemester1" : "well behaved", "commentsSemester2" : "needs improvement", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }
] )

Suponha que, em vez de campos commentsSemester1 e commentsSemester2 separados no primeiro documento, você deseja uni-los em um campo comments, como o segundo documento. A seguinte operação de atualização usa um pipeline de agregação para:

• adicione o novo campo comments e defina o campo lastUpdate.

• remova os campos commentsSemester1 e commentsSemester2 de todos os documentos da coleção.

Certifique-se de que o filtro no comando de atualização direcione para um documento exclusivo. O campo id no código abaixo é um exemplo desse filtro:

db.students.updateOne(
   { _id: 1 },
   [
      { $set: { status: "Modified", comments: [ "$commentsSemester1", "$commentsSemester2" ], lastUpdate: "$$NOW" } },
      { $unset: [ "commentsSemester1", "commentsSemester2" ] }
   ]
)

Primeira etapa

O estágio $set:

• cria um novo campo de array comments cujos elementos são o conteúdo atual dos campos misc1 e misc2 e

• define o campo lastUpdate para o valor da variável de agregação NOW. A variável de agregação NOW é resolvida para o valor de data e hora atual e permanece a mesma em todo o pipeline. Para acessar variáveis de agregação, prefixe a variável com cifrões duplos $$ e coloque entre aspas.

Segunda etapa

O estágio $unset remove os campos commentsSemester1 e commentsSemester2.

Após o comando, a coleção contém os seguintes documentos:

{ "_id" : 2, "student" : "Elizabeth", "status" : "Modified", "points" : 60, "lastUpdate" : ISODate("2020-01-23T05:11:45.784Z"), "comments" : [ "well behaved", "needs improvement" ] }
{ _id: 1, student: 'Skye', points: 75, commentsSemester1: 'great at math', commentsSemester2: 'loses temper', lastUpdate: ISODate("2019-01-01T00:00:00.000Z") }

Observe que depois de introduzir uma classificação, somente o primeiro documento encontrado na ordem de classificação é modificado e os documentos restantes permanecem intocados.

Exemplo 2

O aggregation pipeline permite que a atualização execute atualizações condicionais com base nos valores de campo atuais, bem como use valores de campo atuais para calcular um valor de campo separado.

Por exemplo, criar uma coleção students3 com os seguintes documentos:

db.students3.insertMany( [
   { "_id" : 1, "tests" : [ 95, 92, 90 ], "average" : 92, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") },
   { "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 91, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") },
   { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }
] )

O _id: 3 do terceiro documento, não possui os campos average e grade. Usando uma pipeline de agregação, você pode atualizar o documento com a média calculada e a nota por letra.

db.students3.updateOne(
   { _id: 3 },
   [
     { $set: { average: { $trunc: [  { $avg: "$tests" }, 0 ] }, lastUpdate: "$$NOW" } },
     { $set: { grade: { $switch: {
                           branches: [
                               { case: { $gte: [ "$average", 90 ] }, then: "A" },
                               { case: { $gte: [ "$average", 80 ] }, then: "B" },
                               { case: { $gte: [ "$average", 70 ] }, then: "C" },
                               { case: { $gte: [ "$average", 60 ] }, then: "D" }
                           ],
                           default: "F"
     } } } }
   ]
)

Primeira etapa

O estágio $set:

• calcula um novo campo average com base na média do campo tests. Consulte $avg para obter mais informações sobre o operador de agregação do $avg e $trunc para obter mais informações sobre o operador de agregação truncada $trunc.

• define o campo lastUpdate para o valor da variável de agregação NOW. A variável de agregação NOW é resolvida para o valor de data e hora atual e permanece a mesma em todo o pipeline. Para acessar variáveis de agregação, prefixe a variável com cifrões duplos $$ e coloque entre aspas.

Segunda etapa

O estágio $set calcula um novo campo grade com base no campo average calculado no estágio anterior. Consulte $switch para obter mais informações sobre o operador de aggregation do $switch.

Após o comando, a coleção contém os seguintes documentos:

{ "_id" : 1, "tests" : [ 95, 92, 90 ], "average" : 92, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") }
{ "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 91, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") }
{ "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2020-01-24T17:33:30.674Z"), "average" : 75, "grade" : "C" }

arrayFilters Atualizar elementos que correspondem aos critérios

Crie uma collection students com os seguintes documentos:

db.students.insertMany( [
   { "_id" : 1, "grades" : [ 95, 92, 90 ] },
   { "_id" : 2, "grades" : [ 98, 100, 102 ] },
   { "_id" : 3, "grades" : [ 95, 110, 100 ] }
] )

Para modificar todos os elementos maiores ou iguais a 100 na array grades, use o operador posicional filtrado $[<identifier>] com a opção arrayFilters no método db.collection.updateOne():

db.students.updateOne(
   { grades: { $gte: 100 } },
   { $set: { "grades.$[element]" : 100 } },
   { arrayFilters: [ { "element": { $gte: 100 } } ] }
)

A operação atualiza o campo grades de um único documento e, após a operação, a coleção tem os seguintes documentos:

{ "_id" : 1, "grades" : [ 95, 92, 90 ] }
{ "_id" : 2, "grades" : [ 98, 100, 100 ] }
{ "_id" : 3, "grades" : [ 95, 110, 100 ] }

Atualizar elementos específicos de uma array de documentos

Crie uma collection students2 com os seguintes documentos:

db.students2.insertMany( [
   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 90, "std" : 4 },
         { "grade" : 85, "mean" : 85, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 75, "std" : 6 },
         { "grade" : 87, "mean" : 90, "std" : 3 },
         { "grade" : 85, "mean" : 85, "std" : 4 }
      ]
   }
] )

Para modificar o valor do campo mean para todos os elementos na array grades onde a nota é maior ou igual a 85, use o operador posicional filtrado $[<identifier>] com o arrayFilters no método db.collection.updateOne():

db.students2.updateOne(
   { },
   { $set: { "grades.$[elem].mean" : 100 } },
   { arrayFilters: [ { "elem.grade": { $gte: 85 } } ] }
)

A operação atualiza a array de um único documento e após a operação, a coleção possui os seguintes documentos:

{
   "_id" : 1,
   "grades" : [
      { "grade" : 80, "mean" : 75, "std" : 6 },
      { "grade" : 85, "mean" : 100, "std" : 4 },
      { "grade" : 85, "mean" : 100, "std" : 6 }
    ]
}
{
   "_id" : 2,
   "grades" : [
      { "grade" : 90, "mean" : 75, "std" : 6 },
      { "grade" : 87, "mean" : 90, "std" : 3 },
      { "grade" : 85, "mean" : 85, "std" : 4 }
   ]
}