db.collection.findAndModify()

Desempenho

As gravações com nova tentativa exigem que o método findAndModify() copie o documento inteiro em uma coleção lateral especial para cada nó em um conjunto de réplicas antes de executar a atualização. Isso pode tornar findAndModify() uma operação cara ao lidar com documentos grandes ou grandes conjuntos de réplicas.

fields Projeção

A opção fields usa um documento no seguinte formato:

{ field1: <value>, field2: <value> ... }

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.people.findAndModify(
   {
     query: { name: "Andy" },
     update: { $inc: { score: 1 } },
     upsert: true
   }
)

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

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

• Exatamente uma operação findOneAndUpdate() inserirá com sucesso um novo documento.

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

  Para que outras operações do findOneAndUpdate() 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 }
)

Coleções fragmentadas

Para usar findAndModify em uma collection fragmentada:

• Se você só tiver como alvo um shard, pode usar uma chave de shard parcial no campo query ou,

• Você pode fornecer uma condição de igualdade em uma chave de shard completa no campo query.

• A partir da versão 7.1, não será necessário fornecer a chave de fragmento ou o campo _id na especificação da consulta.

Os documentos em uma coleção fragmentada podem não ter campos de chave de fragmento. Para direcionar um documento que não tem a chave de fragmento, você pode usar a correspondência de igualdade nullem conjunto com outra condição de filtro (como no campo _id). Por exemplo:

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

Validação do documento

O método db.collection.findAndModify() adiciona compatibilidade para a opção bypassDocumentValidation, que permite ignorar a validação de documentos ao inserir ou atualizar documentos em uma coleção com regras de validação.

Comparações com o método update

Ao atualizar um documento, db.collection.findAndModify() e o método updateOne() operam de forma diferente:

• Se vários documentos corresponderem aos critérios de atualização para db.collection.findAndModify(), você poderá especificar uma sort para fornecer alguma medida de controle sobre qual documento atualizar.

  updateOne() atualiza o primeiro documento que corresponde.

• Por padrão, db.collection.findAndModify() retorna a versão pré-modificada do documento. Para obter o documento atualizado, use a opção new.

  O método updateOne() retorna um objeto WriteResult() que contém o status da operação.

  Para retornar o documento atualizado, use o método find(). No entanto, outras atualizações podem ter modificado o documento entre a atualização e a recuperação do documento. Além disso, se a atualização modificou apenas um único documento, mas vários documentos corresponderam, você precisará usar lógica adicional para identificar o documento atualizado.

Se modificar um único documento, ambos o db.collection.findAndModify() e o método updateOne() atualizam atomicamente o documento. Consulte Atomicidade e transações para obter mais detalhes sobre as interações e a ordem das operações desses métodos.

Transações

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

Entradas de oplog

Se uma operação db.collection.findAndModify() conseguir localizar e modificar um documento, ela adicionará uma entrada no oplog (log de operações). Se a operação falhar ou não encontrar um documento para modificar, ela não adicionará uma entrada no oplog.

Atualização e devolução

O método a seguir atualiza e retorna um documento existente na collection de pessoas onde o documento corresponde aos critérios de query:

db.people.findAndModify({
    query: { name: "Tom", state: "active", rating: { $gt: 10 } },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } }
})

Este método executa as seguintes ações:

1. A query localiza um documento na collection people onde o campo name tem o valor Tom, o campo state tem o valor active e o campo rating tem um valor greater than 10.

2. O sort classifica os resultados da query em ordem crescente. Se vários documentos atenderem à condição query, o método selecionará para modificação o primeiro documento conforme ordenado por este sort.

3. A atualização increments do valor do campo score por 1.

4. O método retorna o documento original (ou seja, pré-modificação) selecionado para esta atualização:

   {
     "_id" : ObjectId("50f1e2c99beb36a0f45c6453"),
     "name" : "Tom",
     "state" : "active",
     "rating" : 100,
     "score" : 5
   }

   Para retornar o documento atualizado, adicione a opção new:true ao método.

   Se nenhum documento corresponder à condição query, o método retornará null.

Upsert

O método a seguir inclui a opção upsert: true para a operação update atualizar um documento correspondente ou, se não existir nenhum documento correspondente, criar um novo documento:

db.people.findAndModify({
    query: { name: "Gus", state: "active", rating: 100 },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true
})

Se encontrar um documento correspondente, o método executará uma atualização.

Se não encontrar um documento correspondente, o método criará um novo documento. Como o método incluiu a opção sort, ele retorna um documento vazio { } como o documento original (pré-modificação):

{ }

Se o método não incluiu uma opção sort , o método retorna null.

null

Retornar novo documento

O método seguinte inclui a opção upsert: true e a opção new:true. O método atualiza um documento correspondente e retorna o documento atualizado ou, se não existir nenhum documento correspondente, insere um documento e retorna o documento recém-inserido no campo value.

No exemplo a seguir, nenhum documento na collection people corresponde à condição query:

db.people.findAndModify({
    query: { name: "Pascal", state: "active", rating: 25 },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true,
    new: true
})

O método retorna o documento recém-inserido:

{
   "_id" : ObjectId("50f49ad6444c11ac2448a5d6"),
   "name" : "Pascal",
   "rating" : 25,
   "score" : 1,
   "state" : "active"
}

Classificar e remover

Ao incluir uma especificação sort no campo rating, o exemplo seguinte remove da collection people um único documento com o valor state de active e o menor rating entre os documentos correspondentes:

db.people.findAndModify(
   {
     query: { state: "active" },
     sort: { rating: 1 },
     remove: true
   }
)

O método retorna o documento excluído:

{
   "_id" : ObjectId("52fba867ab5fdca1299674ad"),
   "name" : "XYZ123",
   "score" : 1,
   "state" : "active",
   "rating" : 3
}

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.findAndModify({
    query: { category: "cafe", status: "a" },
    sort: { category: 1 },
    update: { $set: { status: "Updated" } },
    collation: { locale: "fr", strength: 1 }
});

A operação retorna o seguinte documento:

{ "_id" : 1, "category" : "café", "status" : "A" }

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.students.insertMany( [
   { "_id" : 1, "grades" : [ 95, 92, 90 ] },
   { "_id" : 2, "grades" : [ 98, 100, 102 ] },
   { "_id" : 3, "grades" : [ 95, 110, 100 ] }
] )

db.students.findAndModify({
   query: { grades: { $gte: 100 } },
   update: { $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.findAndModify({
   query: { _id : 1 },
   update: { $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 }
   ]
}

Usar um aggregation pipeline para atualizações

db.collection.findAndModify() pode aceitar 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 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, criar 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 }
      ]
   }
] )

A operação a seguir localiza um documento em que o campo _id é igual a 1 e usa um aggregation pipeline para calcular um novo total de campo a partir do campo grades:

db.students2.findAndModify( {
   query: {  "_id" : 1 },
   update: [ { $set: { "total" : { $sum: "$grades.grade" } } } ],  // The $set stage is an alias for ``$addFields`` stage
   new: true
} )

A operação retorna o documento atualizado:

{
   "_id" : 1,
   "grades" : [ { "grade" : 80, "mean" : 75, "std" : 6 }, { "grade" : 85, "mean" : 90, "std" : 4 }, { "grade" : 85, "mean" : 85, "std" : 6 } ],
   "total" : 250
}

Usar variáveis em let

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

Criar uma coleção cakeFlavors:

db.cakeFlavors.insertMany( [
   { _id: 1, flavor: "chocolate" },
   { _id: 2, flavor: "strawberry" },
   { _id: 3, flavor: "cherry" }
] )

O exemplo a seguir define uma variável targetFlavor em let e usa a variável para alterar o sabor do bolo de cereja para laranja:

db.cakeFlavors.findAndModify( {
   query: {
      $expr: { $eq: [ "$flavor", "$$targetFlavor" ] }
   },
   update: { flavor: "orange" },
   let: { targetFlavor: "cherry" }
} )

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 find and modify document
db.medical.findAndModify( {
   query:
      { $and: [
         {
            // Only update the document for Mary Smith
            patientName: { $eq: "Mary Smith" }
         },
         {
            // User must have the Provider role to perform the update
            $expr: { $ne: [ {
               $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ]
            }, [] ] }
         }
      ]
   },
   // Update document
   update: {
      patientName: "Mary Smith",
      diagnosisCode: "ACH 03",
      creditCard: "6541-7534-9637-3456"
   }
} )

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 find and modify document
db.medical.findAndModify( {
   query:
      { $and: [
         {
            // Only update the document for Mary Smith
            patientName: { $eq: "Mary Smith" }
         },
         {
            // User must have the Provider role to perform the update
            $expr: { $ne: [ {
               $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ]
            }, [] ] }
         }
      ]
   },
   // Update document
   update: {
      patientName: "Mary Smith",
      diagnosisCode: "ACH 03",
      creditCard: "6541-7534-9637-3456"
   }
} )

O exemplo anterior não atualiza nenhum documento.