db.collection.updateOne()

Parâmetros

O método db.collection.updateOne() utiliza os seguintes parâmetros:

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

// INVALID
[
  { "x.a": { $gt: 85 } },
  { "x.b": { $gt: 80 } }
]

// Example 1
[
  { $or: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 2
[
  { $and: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 3
[
  { "x.a": { $gt: 85 }, "x.b": { $gt: 80 } }
]

Devoluções

O método retorna um documento que contém:

• matchedCount contendo o número de documentos correspondentes

• modifiedCount contendo o número de documentos modificados

• upsertedId contendo o _id para o documento atualizado

• upsertedCount contendo o número de documentos upserted

• Um valor booleano acknowledged como true se a operação for executada com referência de escritarefer ou false se a referência de escrita estiver desativada

Atualiza um único documento

db.collection.updateOne() encontra o primeiro documento que corresponde ao filtro e aplica as modificações de atualização especificadas.

Atualizar com um Documento de Expressões do Operador de Atualização

Para as especificações de atualização, o método db.collection.updateOne() pode aceitar um documento que contém apenas expressões de operador de atualização .

Por exemplo:

db.collection.updateOne(
   <query>,
   { $set: { status: "D" }, $inc: { quantity: 2 } },
   ...
)

Atualize com um pipeline de agregação.

A partir do MongoDB 4.2, o método db.collection.updateOne() pode aceitar um aggregation pipeline [ <stage1>, <stage2>, ... ] que especifica as modificações a serem executadas. O pipeline pode consistir nas seguintes etapas:

• $addFields e seu alias $set

• $project e seu alias $unset

• $replaceRoot e seu nome alternativo $replaceWith.

O uso do aggregation pipeline permite uma instrução de atualização mais expressiva, como atualizações condicionais Express com base em valores de campo atuais ou atualização de um campo usando o valor de outro(s) campo(s).

Por exemplo:

db.collection.updateOne(
   <query>,
   [
      { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ] } },
      { $unset: [ "misc1", "misc2" ] }
   ]
   ...
)

Para obter exemplos, consulte Atualizar com o aggregation pipeline.

Upsert

Se upsert: true e nenhum documento corresponder ao critério filter, db.collection.updateOne() cria um novo documento com base nos critérios filter e nas modificações update . Consulte Atualizar com Upsert.

Se você especificar upsert: true em uma coleção fragmentada, você deverá incluir a chave de shard completa no filtro. Para comportamento adicional db.collection.updateOne() em uma coleção fragmentada, consulte Coleções fragmentadas.

Coleção limitada

Se uma operação de atualização alterar o tamanho do documento, a operação falhará.

Coleções partilhadas

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

Explicabilidade

updateOne() não é compatível com db.collection.explain().

Transações

db.collection.updateOne() pode ser usado dentro de transações distribuídas.

Entradas Oplog

Se uma operação db.collection.updateOne() atualizar um documento com êxito, a operação adicionará uma entrada no oplog (registro de operações). Se a operação falhar ou não localizar um documento para atualizar, a operação não adicionará uma entrada no oplog.

Atualize usando expressões do operador de atualização

A coleção restaurant contém os seguintes documentos:

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan" },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }

A operação a seguir atualiza um único documento onde name: "Central Perk Cafe" com o campo violations:

try {
   db.restaurant.updateOne(
      { "name" : "Central Perk Cafe" },
      { $set: { "violations" : 3 } }
   );
} catch (e) {
   print(e);
}

A operação retorna:

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

Se nenhuma correspondência for encontrada, a operação retornará:

{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0 }

A configuração upsert: true inseriria o documento se nenhuma correspondência fosse encontrada. Consulte Atualizar com Upsert

Atualização com aggregation pipeline

A partir do MongoDB 4.2, o db.collection.updateOne() pode usar um aggregation pipeline para a atualização. O pipeline pode consistir nas seguintes etapas:

• $addFields e seu alias $set

• $project e seu alias $unset

• $replaceRoot e seu nome alternativo $replaceWith.

O uso do aggregation pipeline permite uma instrução de atualização mais expressiva, como atualizações condicionais Express com base em valores de campo atuais ou atualização de um campo usando o valor de outro(s) campo(s).

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") }
] )

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

{ "_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") }

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") }
] )

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"
     } } } }
   ]
)

{ "_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" }

Atualize com upsert

A coleção restaurant contém os seguintes documentos:

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : "0" }

A operação a seguir tenta atualizar o documento com name : "Pizza Rat's Pizzaria", enquanto upsert: true:

try {
   db.restaurant.updateOne(
      { "name" : "Pizza Rat's Pizzaria" },
      { $set: {"_id" : 4, "violations" : 7, "borough" : "Manhattan" } },
      { upsert: true }
   );
} catch (e) {
   print(e);
}

Como upsert:true o documento é inserted com base nos critérios filter e update. A operação retorna:

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : 4,
   "upsertedCount": 1
}

A coleção agora contém os seguintes documentos:

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 4 },
{ "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 7 }

O campo name foi preenchido usando os critérios filter, enquanto os operadores update foram usados para criar o restante do documento.

A operação a seguir atualiza o primeiro documento com violations que é maior que 10:

try {
   db.restaurant.updateOne(
      { "violations" : { $gt: 10} },
      { $set: { "Closed" : true } },
      { upsert: true }
   );
} catch (e) {
   print(e);
}

A operação retorna:

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : ObjectId("56310c3c0c5cbb6031cafaea")
}

A coleção agora contém os seguintes documentos:

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 4 },
{ "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "grade" : 7 }
{ "_id" : ObjectId("56310c3c0c5cbb6031cafaea"), "Closed" : true }

Como nenhum documento correspondeu ao filtro, e upsert era true, updateOne() inseriu o documento com um _id gerado e os critérios update apenas.

Atualize com referência de gravação (write concern)

Dado um conjunto de réplicas de três nós, a operação a seguir especifica um w de majority, wtimeout de 100:

try {
   db.restaurant.updateOne(
       { "name" : "Pizza Rat's Pizzaria" },
       { $inc: { "violations" : 3}, $set: { "Closed" : true } },
       { w: "majority", wtimeout: 100 }
   );
} catch (e) {
   print(e);
}

Se o primário e pelo menos um secundário reconhecerem cada operação de gravação dentro de 100 milissegundos, ele retornará:

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

Se a confirmação demorar mais que o limite wtimeout , a exceção será lançada:

WriteConcernError({
   "code" : 64,
   "errmsg" : "waiting for replication timed out",
   "errInfo" : {
     "wtimeout" : true,
     "writeConcern" : {
       "w" : "majority",
       "wtimeout" : 100,
       "provenance" : "getLastErrorDefaults"
     }
   }
})

A tabela a seguir explica os possíveis valores de errInfo.writeConcern.provenance:

Especifique o agrupamento

A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para letras maiúsculas e marcas de acento.

Uma coleção myColl possui os seguintes documentos:

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

A seguinte operação inclui a opção coleção:

db.myColl.updateOne(
   { category: "cafe" },
   { $set: { status: "Updated" } },
   { collation: { locale: "fr", strength: 1 } }
);

Especificar arrayFilters para uma Operação de Atualização de Matriz

A partir do MongoDB 3,6, ao atualizar um campo de array, você pode especificar arrayFilters que determina quais elementos da array devem ser atualizados.

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

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

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

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 }
      ]
   }
] )

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

{
   "_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 }
   ]
}

Especifique hint para operações de atualização

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

db.students.insertMany( [
   { "_id" : 1, "student" : "Richard", "grade" : "F", "points" :  0,  "comments1" : null, "comments2" : null },
   { "_id" : 2, "student" : "Jane", "grade" : "A", "points" : 60,  "comments1" : "well behaved", "comments2" : "fantastic student" },
   { "_id" : 3, "student" : "Ronan", "grade" : "F", "points" :  0,  "comments1" : null, "comments2" : null },
   { "_id" : 4, "student" : "Noah", "grade" : "D", "points" : 20,  "comments1" : "needs improvement", "comments2" : null },
   { "_id" : 5, "student" : "Adam", "grade" : "F", "points" :  0,  "comments1" : null, "comments2" : null },
   { "_id" : 6, "student" : "Henry", "grade" : "A", "points" : 86,  "comments1" : "fantastic student", "comments2" : "well behaved" }
] )

Crie os seguintes índices na coleção:

db.students.createIndex( { grade: 1 } )
db.students.createIndex( { points: 1 } )

A seguinte operação de atualização sugere explicitamente o uso do índice { grade: 1 }:

db.students.updateOne(
   { "points": { $lte: 20 }, "grade": "F" },
   { $set: { "comments1": "failed class" } },
   { hint: { grade: 1 } }
)

O comando de atualização retorna o seguinte:

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

Para visualizar o índice utilizado, execute o explain na operação:

db.students.explain().update(
   { "points": { $lte: 20 }, "grade": "F" },
   { $set: { "comments1": "failed class" } },
   { multi: true, hint: { grade: 1 } }
)

Roles de usuário e atualizações de documentos

A partir do MongoDB 7.0, você pode usar a nova variável de sistemaUSER_ROLES para retornar funções de usuário .

O exemplo nesta seção mostra atualizações de campos em uma collection que contém informações médicas. O exemplo lê os roles atuais do usuário da variável de sistema USER_ROLES e só executa as atualizações se o usuário tiver um role específico.

Para usar uma variável do sistema, adicione $$ ao início do nome da variável. Especifique a variável de sistema USER_ROLES como $$USER_ROLES.

O exemplo cria estes usuários:

• James com um role Billing.

• Michelle com um role Provider.

Execute as seguintes etapas para criar os roles, os usuários e a collection:

db.createRole( { role: "Billing", privileges: [ { resource: { db: "test",
   collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )
db.createRole( { role: "Provider", privileges: [ { resource: { db: "test",
   collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )

db.createUser( {
   user: "James",
   pwd: "js008",
   roles: [
      { role: "Billing", db: "test" }
   ]
} )
db.createUser( {
   user: "Michelle",
   pwd: "me009",
   roles: [
      { role: "Provider", db: "test" }
   ]
} )

db.medical.insertMany( [
   {
      _id: 0,
      patientName: "Jack Jones",
      diagnosisCode: "CAS 17",
      creditCard: "1234-5678-9012-3456"
   },
   {
      _id: 1,
      patientName: "Mary Smith",
      diagnosisCode: "ACH 01",
      creditCard: "6541-7534-9637-3456"
   }
] )

Faça login como Michelle, que tem o role Provider, e execute uma atualização:

db.auth( "Michelle", "me009" )

// Attempt to update one document
db.medical.updateOne( {
   // User must have the Provider role to perform the update
   $expr: { $ne: [
      { $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ] }, []
   ] } },
   // Update diagnosisCode
   { $set: { diagnosisCode: "ACH 01"} }
)

O exemplo anterior usa $setIntersection para retornar documentos onde a interseção entre a string "Provider" e os roles de usuário do $$USER_ROLES.role não está vazia. Michelle tem o role Provider, então a atualização é executada.

Em seguida, faça login como James, que não tem o role Provider e tente realizar a mesma atualização:

db.auth( "James", "js008" )

// Attempt to update one document
db.medical.updateOne( {
   // User must have the Provider role to perform the update
   $expr: { $ne: [
      { $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ] }, []
   ] } },
   // Update diagnosisCode
   { $set: { diagnosisCode: "ACH 01"} }
)

O exemplo anterior não atualiza nenhum documento.