atualizar (comando de banco de dados)

Atualizar declarações

Cada elemento de array updates é um documento de instrução de atualização. Cada documento contém os seguintes campos:

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

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 comando retorna um documento que contém o status da operação. Por exemplo:

{
   "ok" : 1,
   "nModified" : 0,
   "n" : 1,
   "upserted" : [
      {
         "index" : 0,
         "_id" : ObjectId("52ccb2118908ccd753d65882")
      }
   ]
}

Para obter detalhes sobre os campos de saída, consulte Saída.

Limitações

Se você definir multi: true, use o comando update apenas para operações idempotentes.

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

O campo de instrução de atualização u pode aceitar um documento que contenha apenas expressões de operador de atualização. Por exemplo:

updates: [
   {
     q: <query>,
     u: { $set: { status: "D" }, $inc: { quantity: 2 } },
      ...
   },
   ...
]

Em seguida, o comando update atualiza somente os campos correspondentes no documento.

Atualizar com um documento de substituição

O campo u da declaração de atualização pode aceitar um documento de substituição, ou seja, o documento contém apenas expressões field:value. Por exemplo:

updates: [
   {
      q: <query>,
      u: { status: "D", quantity: 4 },
      ...
   },
   ...
]

Em seguida, o comando update substitui o documento correspondente pelo documento de atualização. O comando update só pode substituir um único documento correspondente; ou seja, o campo multi não pode ser true. O comando update não substitui o valor _id.

Falhas em múltiplas atualizações

Se um único documento não for atualizado em um comando de atualização com o parâmetro multi definido como true, nenhum outro documento será atualizado como parte desse comando.

Por exemplo, a coleção sample_mflix.movies contém filmes com campos imdb.rating. Crie um validador de documento na coleção movies com uma regra de que o valor imdb.rating deve ser menor ou igual a 10:

db.runCommand( 
   { 
      update: "movies",
      updates: [
      {
         q: { 
            year: { $gte: 2000, $lte: 2005 },
            "imdb.rating": { $type: "number" }
         }, 
         u: { $inc: { "imdb.rating": 1 } },
         multi: true
      }
      ]
   }
)

Se algum filme já tiver uma classificação de 10, incrementá-lo violaria a regra de validação (classificação > 10). Quando isso acontece, a atualização é interrompida e nenhum outro documento é atualizado, mesmo que milhares de documentos correspondam à query.

Atualize com um pipeline de agregação.

O campo u da instrução de atualização 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).

Por exemplo:

updates: [
   {
      q: <query>,
      u: [
        { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ] } },
        { $unset: [ "misc1", "misc2" ] }
      ],
      ...
   },
   ...
]

Para obter exemplos, consulte Atualizar com pipeline de agregação.

Upsert com índice exclusivo

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

Considere um exemplo em que nenhum documento com o nome Andy existe e vários clientes emitem o seguinte comando ao mesmo tempo:

db.runCommand(
   {
     update: "people",
     updates: [
       { q: { name: "Andy" }, u: { $inc: { score: 1 } }, multi: true, upsert: true }
     ]
   }
)

Se todas as operações update terminarem a fase de query antes que qualquer cliente insira dados com êxito e não houver nenhum índice exclusivo no campo name, cada operação update poderá resultar em uma inserção, criando vários documentos com name: Andy.

Um índice exclusivo no campo name garante que somente um documento seja criado. Com um índice único em vigor, as múltiplas operações update agora apresentam o seguinte comportamento:

• Exatamente uma operação update inserirá com êxito um novo documento.

• Outras operações update atualizam o documento recém-inserido ou falham devido a uma colisão de chave exclusiva.

  Para que outras operações update 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 duplicado.

  • 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" }

  • O campo no predicado de igualdade correspondem ao campo 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.

A tabela a seguir mostra exemplos de operações upsert que, quando ocorre uma colisão de chaves, resultam em uma atualização ou falha.

{ name : 1 }

db.people.updateOne(
   { name: "Andy" },
   { $inc: { score: 1 } },
   { upsert: true }
)

{ name : 1 }

db.people.updateOne(
   { name: { $ne: "Joe" } },
   { $set: { name: "Andy" } },
   { upsert: true }
 )

{ name : 1 }

db.people.updateOne(
  { name: "Andy", email: "andy@xyz.com" },
  { $set: { active: false } },
  { upsert: true }
)

Limites

Para cada elemento de atualização na array updates, a soma da query e os tamanhos de atualização (ou seja, q e u ) devem ser menores ou iguais ao tamanho máximo do documento BSON.

O número total de instruções de atualização na array updates deve ser menor ou igual ao tamanho máximo em massa.

Validação de esquema

O comando update adiciona suporte para a opção bypassDocumentValidation, que permite ignorar a validação de esquema ao inserir ou atualizar documentos em uma coleção com regras de validação.

Coleções fragmentadas

Transações

update pode ser usado dentro de transações distribuídas.

Atualizar campos específicos de um documento

Use operadores de atualização para atualizar apenas os campos especificados de um documento.

Por exemplo, os documentos na coleção movies do banco de dados sample_mflix contêm campos como title, year e num_mflix_comments.

O comando a seguir usa os operadores de atualização $set e $inc para atualizar os campos year e num_mflix_comments de um documento em que title é igual a "The Godfather":

db.runCommand(
   {
      update: "movies",
      updates: [
         {
            q: { title: "The Godfather" }, u: { $set: { year: 1972 }, $inc: { num_mflix_comments: 1 } }
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

Como <update> documento não especifica o campo de multi opcional, a atualização modifica apenas um documento, mesmo que mais de um documento corresponda à condição de correspondência de q .

Consulte Saída para detalhes.

Atualizar campos específicos de vários documentos

Use operadores de atualização para atualizar apenas os campos especificados de um documento e inclua o campo multi definido como true na instrução update.

Por exemplo, os documentos na coleção movies do banco de dados sample_mflix contêm campos como year e num_mflix_comments.

O comando a seguir usa o operador de atualização $inc para incrementar o campo num_mflix_comments para todos os filmes lançados em 1924:

db.runCommand(
   {
      update: "movies",
      updates: [
         { 
            q: { year: 1924 }, 
            u: { $inc: { num_mflix_comments: 1 }, $set: { classic: true, era: "silent" } }, 
            multi: true 
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

Como o campo multi está configurado para true, a atualização modifica todos os documentos do 6 que correspondem à query especificada no campo q e retorna a seguinte saída:

{ n: 6, nModified: 6, ok: 1, '...': '...' }

Consulte Saída para detalhes.

Atualização com aggregation pipeline

O comando update pode usar um pipeline de agregação para a atualização. 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.runCommand(
   {
      update: "users",
      updates: [
         { 
            q: { name: "Robert Baratheon" },  
            u: [ 
               { $set: { full_info: { $concat: [ "$name", " - ", "$email" ] } } },
               { $set: { status: "active" } }
            ], 
            multi: false
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

db.runCommand(
   {
      update: "movies",
      updates: [
         { 
            q: { title: "The Great Train Robbery" },  
            u: [ 
                  { $set: { age: { $subtract: [ 2026, "$year" ] } } },
                  { $set: { era: { $switch: { 
                                       branches: [
                                             { case: { $lt: [ "$year", 1960 ] }, then: "Classic" },
                                             { case: { $lt: [ "$year", 1980 ] }, then: "Golden Age" },
                                             { case: { $lt: [ "$year", 2000 ] }, then: "Modern" },                                                   
                                             { case: { $gte: [ "$year", 2000 ] }, then: "Contemporary" }
                                       ],
                                       default: "Unknown" 
                  } } } } 
            ], 
            multi: false
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

Atualização em Massa

O exemplo a seguir executa várias operações de atualização em um único comando para atualizar documentos existentes e inserir novos documentos. A operação:

• marca filmes de gênero bem avaliados de 2015 como featured

• categoriza curtas-metragens de ação e sucesso de 2012 como melodrama

• upsert um novo filme de ficção científica de 2024 se não existir

db.runCommand(
   {
      update: "movies",
      updates: [
         // Update highly-rated Horror movies from 2015
         { 
            q: { year: 2015, genres: "Horror", "imdb.rating": { $gte: 7 } }, 
            u: { $set: { featured: true } },
            multi: true
         },
         // Update short Drama/Romance movies from 2012
         { 
            q: { year: 2012, genres: { $all: ["Drama", "Romance"] }, runtime: { $lt: 90 } }, 
            u: { $set: { category: "melodrama" } },
            multi: true
         },
         // Upsert a new movie from 2026
         { 
            q: { title: "A New Movie", year: 2026 }, 
            u: { 
               $set: { 
                  genres: ["Sci-Fi", "Adventure"],
                  runtime: 142,
                  "imdb.rating": 8.5,
                  featured: true
               }
            },
            upsert: true
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

O documento retornado mostra que o comando modificou os documentos existentes e inseriu um novo documento por upsert. Consulte Saída para detalhes.

{
  n: 16,
  upserted: [
    {
      index: 2,
      _id: ObjectId('69861e680e6ea1f51160fe1c')
    }
  ],
  nModified: 15,
  ok: 1,
  '...': '...'
}

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.

Os documentos na coleção movies do banco de dados sample_mflix têm campos como title e year.

A operação a seguir usa agrupamento para executar uma pesquisa sem diferenciação de maiúsculas e minúsculas. A query pesquisa "the godfather" em letras minúsculas, mas com o agrupamento strength: 1, a query corresponde a "The Godfather", independentemente da capitalização:

db.runCommand({
  update: "movies",
  updates: [
    {
      q: { title: "the godfather" },
      u: { $set: { featured: true } },
      collation: { locale: "en", strength: 1 }
    }
  ]
})

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

Ao atualizar um campo de array, você pode especificar arrayFilters que determinam quais elementos de array atualizar.

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

db.runCommand({
   update: "movies",
   updates: [
      { q: { title: "The Godfather" }, u: { $set: { "cast.$[elem]" : "REDACTED" } }, arrayFilters: [ { "elem": "Al Pacino" } ], multi: false }
   ]
})

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

Os documentos na coleção movies do banco de dados sample_mflix têm campos como year e num_mflix_comments.

Crie os seguintes índices na coleção:

[
   db.movies.createIndex( { year: 1 } ),
   db.movies.createIndex( { num_mflix_comments: 1 } )
]

A seguinte operação de atualização incrementa o campo num_mflix_comments para "O grande roubo do trem" e sugere explicitamente o uso do índice { year: 1 }:

db.runCommand({
   update: "movies",
   updates: [
      { q: { title: "The Great Train Robbery" }, u: { $inc: { "num_mflix_comments": 1 } }, hint: { year: 1 }, multi: false }
   ]
})

Para visualizar o índice utilizado, você pode executar o explain em uma operação de atualização. Por exemplo, o seguinte explica uma atualização que incrementa num_mflix_comments para filmes com 5 ou menos comentários lançados em 2000 ou posterior:

db.runCommand(
   {
      explain: {
         update: "movies",
         updates: [ 
         { q: { "num_mflix_comments": { $lte: 5 }, "year": { $gte: 2000 } }, u: { $inc: { "num_mflix_comments": 1 } }, hint: { year: 1 }, multi: true }
         ]
      },
      verbosity: "queryPlanner"
   }
)

O explain não modifica os documentos.

Usar variáveis na opção let ou no campo c

As variáveis podem ser definidas na opção let ou no campo c e acessadas no array updates.

Os documentos na coleção movies do banco de dados sample_mflix têm campos como title e year.

O exemplo seguinte utiliza a opção let para definir variáveis para localizar e adicionar um novo campo a um filme.

db.runCommand( {
   update: "movies",
   updates: [
      { q: { $expr: { $eq: [ "$title", "$$movieTitle" ] } },
         u: [ { $set: { franchise: "$$franchiseName" } } ] }
   ],
   let : { movieTitle: "The Godfather", franchiseName: "The Godfather Trilogy" }
} )

O exemplo a seguir define movieTitle e franchiseName variáveis em c e usa as variáveis para adicionar um campo franchise .

db.runCommand( {
   update: "movies",
   updates: [
      { q: { $expr: { $eq: [ "$title", "$$movieTitle" ] } },
         u: [ { $set: { franchise: "$$franchiseName" } } ],
         c: { movieTitle: "The Godfather", franchiseName: "The Godfather Trilogy" } }
      ]
} )