db.collection.update() (método mongosh)

Parâmetros

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

{
  <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n>
}

Devoluções

O método retorna um documento WriteResult que contém o status da operação.

Limitações

Se você definir multi: true, utilize o método update() apenas para operações idempotente.

Usando $expr em uma atualização com Upsert

A tentativa de usar o operador $expr com o sinalizador upsert definido como true gerará um erro.

Coleções fragmentadas

Para usar db.collection.update() com multi: false em uma coleção fragmentada, é necessário incluir uma correspondência exata no campo _id ou direcionar um único fragmento (por exemplo, incluindo a chave do fragmento).

Quando o db.collection.update() executar operações de atualização (e não documentar operações de substituição), o db.collection.update() poderá direcionar vários fragmentos.

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

Transações

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

Entradas de oplog

Se uma operação db.collection.update() atualizar um ou mais documentos com êxito, a operação adicionará uma entrada no oplog (log de operações). Se a operação falhar ou não encontrar nenhum documento para atualizar, a operação não adicionará uma entrada no oplog.

Upsert com _id query pontilhada

Quando você executar um update() com upsert: true e a query não corresponder a nenhum documento existente, o MongoDB irá se recusar a inserir um novo documento se a query especificar condições no campo _id usando notação de ponto.

Essa restrição garante que a ordem dos campos inseridos no documento _id seja bem definida e não esteja vinculada à ordem especificada na consulta.

Se você tentar inserir um documento dessa forma, o MongoDB gerará um erro.

Upsert com valores duplicados

Os upserts podem criar documentos duplicados, a menos que haja um índice único para evitar duplicatas.

Se todas as db.collection.update() operações concluírem a fase de query antes que qualquer cliente insira dados com êxitoe não houver nenhum índice único no name campo, cada db.collection.update() operação poderá resultar em uma inserção, criando vários documentos name: Andy com.

Um índice único no campo name garante que apenas um documento seja criado. Com um índice único em vigor, as operações múltiplas db.collection.update() agora exibem o seguinte comportamento:

• Exatamente uma operação db.collection.update() inserirá com sucesso um novo

  documento.

• Outras operações db.collection.update() atualizam o recém-inserido

  documento ou falha devido a uma colisão de chave exclusiva.

  Para que outras db.collection.update() operações atualizem o documento recém-inserido, todas as seguintes condições devem ser atendidas:

  • A collection de destino tem um índice único que causaria um

    erro de chave duplicada.

  • A operação de atualização não é updateMany ou multi é

    false.

  • A condição de correspondência de atualização é:

    • Um único predicado de igualdade. Por exemplo { "fieldA" : "valueA" }

    • Um E lógico de predicados de igualdade. Por exemplo { "fieldA" : "valueA", "fieldB" : "valueB" }

  • Os campos no predicado de igualdade correspondem aos campos no

    padrão de chave de índice único .

  • A operação de atualização não modifica nenhum campo no

    padrão de chave de índice único .

Operações de atualização de array

No documento de atualização, use o operador posicional filtrado $[<identifier>] para definir um identificador, que você então faz referência nos documentos de filtro de array. Você não pode ter um documento de filtro de array para um identificador se o identificador não estiver incluído no documento de atualização.

O <identifier> deve começar com uma letra minúscula e conter apenas caracteres alfanuméricos.

Você pode incluir o mesmo identificador várias vezes no documento de atualização; no entanto, para cada identificador distinto$[identifier] () no documento de atualização, você deve especificar exatamente um documento de filtro de matriz correspondente. Ou seja, não é possível especificar vários documentos de filtro de matriz para o mesmo identificador. No entanto, você pode especificar condições compostas no mesmo identificador em um único documento de filtro

Resultados bem-sucedidos

O método db.collection.update() retorna um objeto que contém o WriteResult() WriteResult() status da operação. Após o sucesso, o objeto contém o número de documentos que corresponderam à condição de consulta, o número de documentos inseridos pela atualização e o número de documentos modificados.

Erros de preocupação de gravação

Se o db.collection.update() método encontrar erros de preocupação de gravação , os resultados incluirão o campo.WriteResult.writeConcernError

A tabela a seguir explica os possíveis valores de WriteResult.writeConcernError.provenance:

Erros não relacionados a preocupação de gravação

Se o db.collection.update() método encontrar um erro que não seja preocupação de gravação , os resultados incluirão o WriteResult.writeError campo.

Inserir um novo documento se não houver correspondênciaUpsert ()

Quando você especifica a opção upsert: true:

• Se o(s) documento(s) corresponder(em) aos critérios de query, db.collection.update() executará uma atualização.

• Se nenhum documento corresponder aos critérios de query, db.collection.update() insere um único documento.

  Observação

  Se vários upserts idênticos forem emitidos aproximadamente ao mesmo tempo, é possível que update() usado com upsert: true crie documentos duplicados. Consulte Upsert com valores duplicados para obter mais informações.

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

As abas a seguir mostram uma variedade de usos do modificador upsert com update()..

db.movies.update(
   { title: "Test Movie 12345" },
   { 
      $set: {
         title: "Test Movie 12345", 
         year: 2024, 
         genres: [ "Documentary" ],
         rated: "NR"
      }
   },
   { upsert: true }
)

db.movies.update(
   { title: "Test Movie 67890" },   // Query parameter
   {                                // Update document
      $set: { rated: "PG" },
      $setOnInsert: { year: 2024, type: "movie" }
   },
   { upsert: true }                 // Options
)

db.movies.update(
   { title: "Test Movie ABC123" },  // Query parameter
   [                                // Aggregation pipeline
      { $set: { 
         year: 2024, 
         type: "movie",
         rated: "NR",
         lastModified: "$$NOW" 
      } }
   ],
   { upsert: true }   // Options
)

db.movies.update(
   { title: { $in: ["The Godfather", "The Matrix"] } },
   { $set: { test_upsert_field: true } },
   { upsert: true, multi: true }
)

db.movies.update(
   { "title": "Test Movie Unique789" },
   { $set: { year: 2024, type: "movie" } },
   { upsert: true, multi: true }
)

Atualização com aggregation pipeline

O método db.collection.update() pode aceitar um pipeline de agregação [ <stage1>, <stage2>, ... ] que especifica as modificações a serem realizadas. O pipeline pode consistir nas seguintes etapas:

• $addFields e seu alias $set

• $project e seu alias $unset

• $replaceRoot e seu alias $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.movies.update(
   { title: "The Godfather" },
   [
      { $set: { 
            displayTitle: { $concat: [ "$title", " (", { $toString: "$year" }, ")" ] },
            lastModified: "$$NOW" 
         } 
      }
   ]
)

db.movies.update(
   { 
      year: 2015,
      "imdb.rating": { $type: "number" },
      "tomatoes.viewer.rating": { $type: "number" }
   },
   [
      { $set: { 
         combinedScore: { 
            $round: [ 
               { $avg: [ 
               { $multiply: [ "$imdb.rating", 10 ] }, 
               { $multiply: [ "$tomatoes.viewer.rating", 10 ] } 
               ] }, 
               1 
            ] 
         }, 
         lastUpdate: "$$NOW" 
         } 
      },
      { $set: { 
         grade: { 
            $switch: {
               branches: [
               { case: { $gte: [ "$combinedScore", 80 ] }, then: "A" },
               { case: { $gte: [ "$combinedScore", 70 ] }, then: "B" },
               { case: { $gte: [ "$combinedScore", 60 ] }, then: "C" },
               { case: { $gte: [ "$combinedScore", 50 ] }, then: "D" }
               ],
               default: "F"
            } 
         } 
         } 
      }
   ],
   { multi: true }
)

Especificar arrayFilters para operações de atualização de array

db.movies.update(
   { languages: "English" },
   { $set: { "languages.$[element]" : "EN" } },
   {
      arrayFilters: [ { "element": "English" } ],
      multi: true
   }
)

db.movies.update(
   { title: "The Godfather" },
   { $set: { "writers.$[elem]" : { $concat: [ "$elem", " - UPDATED" ] } } },
   {
      arrayFilters: [ { "elem": { $regex: /screenplay/ } } ]
   }
)

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

A opção hint permite a você especificar qual índice MongoDB deve utilizar para a operação de atualização. Isso é útil ao atualizar vários documentos e você deseja garantir que um índice específico seja usado para desempenho. Este exemplo utiliza a coleção movies existente do banco de dados sample_mflix.

Primeiro, crie um índice no campo year :

db.movies.createIndex( { year: 1 } )

A seguinte operação de atualização sugere explicitamente o uso do { year: 1 } índice para atualizar todos os filmes 2010de2015 a:

db.movies.update(
   { year: { $gte: 2010, $lte: 2015 } },  // Query parameter
   { $set: { decade: "2010s" } },             // Update document
   { multi: true, hint: { year: 1 } }          // Options
)

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

db.movies.explain().update(
   { title: "The Godfather", year: { $gte: 1970 } },
   { $set: { test_hint_field: true } },
   { hint: { year: 1 } }
)

O db.collection.explain().update() não modifica os documentos.

Usar variáveis em let

Para definir variáveis que você pode acessar em outro lugar no comando, use a opção let .

O exemplo:

• Define duas variáveis na opção let: targetTitle (definido como "A Matriz") e newTitle (definido como "A Matriz Recarregada")

• Usa $expr no filtro de query para comparar o campo title do documento com a variável $$targetTitle

• Utiliza um pipeline de agregação com $set para atualizar o campo title para o valor de $$newTitle

db.movies.update(
   { $expr: { $eq: [ "$title", "$$targetTitle" ] } },
   [ { $set: { sequel: "$$sequelTitle" } } ],
   { let : { targetTitle: "The Matrix", sequelTitle: "The Matrix Reloaded" } }
)

Substituir preocupação de gravação padrão

A operação a seguir para um conjunto de réplicas especifica uma preocupação de gravação de w: 2 com uma wtimeout de 5000 milissegundos. Essa operação retorna depois que a gravação se propaga para o primário e um secundário ou expira após 5 segundos.

db.movies.update(
   { num_mflix_comments: { $lte: 10 } },
   { $set: { featured: true } },
   {
      multi: true,
      writeConcern: { w: 2, j: true, wtimeout: 5000 }
   }
)

A operação é concluída com êxito após a gravação ser confirmada pelo primário e pelo menos um secundário, conforme especificado por w: 2.

Erros de preocupação de gravação em clusters fragmentados

Quando db.collection.update() é executado em mongos em um cluster fragmentado, um writeConcernError é sempre relatado na resposta, mesmo quando ocorre um ou mais erros. Em versões anteriores, outros erros às vezes faziam com que db.collection.update() não relatasse erros de preocupação de gravação.

Por exemplo, se um documento falhar na validação, desencadeando um erro DocumentValidationFailed e também ocorrer um erro de preocupação de gravação , o erro DocumentValidationFailed e o writeConcernError serão retornados no campo de nível superior da resposta.

Especifique o agrupamento

Especifica o agrupamento a ser usado para a operação.

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.

A opção de agrupamento tem a seguinte sintaxe:

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

Ao especificar agrupamento, o campo locale é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento.

Se o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão (consulte db.createCollection()), a operação usará o agrupamento especificado para a coleção.

Se nenhum agrupamento for especificado para a coleção ou para as operações, o MongoDB usa a comparação binária simples usada nas versões anteriores para comparações de strings.

Você não pode especificar vários agrupamentos para uma operação. Por exemplo, você não pode especificar agrupamentos diferentes por campo ou, se estiver realizando uma busca com uma classificação, não poderá usar um agrupamento para a busca e outro para a classificação.

Esta operação atualiza todos os filmes com títulos que começam com night e usa strength: 1 para comparação sem distinção entre maiúsculas e minúsculas:

db.movies.update(
   { title: /^night/i },
   { $set: { updated: true } },
   {
      collation: { locale: "en", strength: 1 },
      multi: true
   }
)