encontrar e modificar

lastErrorObject

O documento incorporado do lastErrorObject contém os seguintes campos:

value

Para operações do remove, o value contém o documento removido se a query corresponder a um documento. Se a query não corresponder a um documento para remover, value conterá null.

Para operações do update, o documento embutido do value contém o seguinte:

• Se o parâmetro new não estiver configurado ou for false:

  • o documento de pré-modificação se a query corresponder a um documento;

  • caso contrário, null.

• Se new for true:

  • o documento atualizado se a query retornar uma correspondência;

  • o documento inserido se upsert: true e nenhum documento corresponder à query;

  • caso contrário, null.

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

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

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

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

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

  Para que outras operações do findAndModify 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 partilhadas

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, você não precisa fornecer a chave de shard ou o campo _id na especificação da query.

documento em uma collection fragmentada podem não ter os campo principais do fragmento. Para direcionar um documento que não tenha a chave de shard, 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

Validação do documento

O comando findAndModify adiciona suporte para a opção bypassDocumentValidation , que permite a você ignorar a validação do documento 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, findAndModify e o método updateOne() operam de forma diferente:

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

  updateOne() atualiza o primeiro documento que corresponde.

• Por padrão, o findAndModify retorna um objeto que contém a versão pré-modificada do documento, como também, o status da operação. 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.

Ao modificar um único documento, 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

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

Atualização e devolução

O comando a seguir atualiza um documento existente na collection people onde o documento corresponde aos critérios do query:

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

Este comando 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. Os sort encomendam os resultados da query em ordem crescente. Se vários documentos atenderem à condição query, o comando selecionará para modificação o primeiro documento conforme ordenado por este sort.

3. O update increments o valor do campo score por 1.

4. O comando retorna um documento com os seguintes campos:

   • O campo lastErrorObject que contém os detalhes do comando, incluindo o campo updatedExisting que é true, e

   • O campo value que contém o original (ou seja, pré-modificação) documento selecionado para esta atualização:

     {
       "lastErrorObject" : {
          "connectionId" : 1,
          "updatedExisting" : true,
          "n" : 1,
          "syncMillis" : 0,
          "writtenTo" : null,
          "err" : null,
          "ok" : 1
       },
       value" : {
         "_id" : ObjectId("54f62d2885e4be1f982b9c9c"),
         "name" : "Tom",
         "state" : "active",
         "rating" : 100,
         "score" : 5
       },
       "ok" : 1
     }

Para retornar o documento atualizado no campo value , adicione a opção new:true ao comando.

Se nenhum documento corresponder à condição query, o comando retornará um documento que contenha null no campo value:

{ "value" : null, "ok" : 1 }

mongosh e muitos drivers fornecem um método auxiliar findAndModify() . Utilizando o auxiliar de shell, esta operação anterior pode assumir o seguinte formulário:

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

No entanto, o assistente de shell findAndModify() retorna somente o documento não modificado ou, se new for true, o documento atualizado.

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

upsert: true

O comando findAndModify a seguir inclui a opção upsert: true para a operação update atualizar um documento correspondente ou, se não houver nenhum documento correspondente, criar um novo documento:

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

Se o comando encontrar um documento correspondente, o comando executará uma atualização.

Se o comando não encontrar um documento correspondente, a operação update com upsert: true resultará em uma inserção e retornará um documento com os seguintes campos:

• O campo lastErrorObject que contém os detalhes do comando, incluindo o campo upserted que contém o valor _id do documento recém-inserido e

• O campo value contendo null.

{
  "value" : null,
  "lastErrorObject" : {
     "updatedExisting" : false,
     "n" : 1,
     "upserted" : ObjectId("54f62c8bc85d4472eadea26f")
  },
  "ok" : 1
}

Retornar novo documento

O comando findAndModify a seguir inclui a opção upsert: true e a opção new:true . O comando 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.runCommand(
   {
     findAndModify: "people",
     query: { name: "Pascal", state: "active", rating: 25 },
     sort: { rating: 1 },
     update: { $inc: { score: 1 } },
     upsert: true,
     new: true
   }
)

O comando retorna o documento recém-inserido no campo value:

{
  "lastErrorObject" : {
     "connectionId" : 1,
     "updatedExisting" : false,
     "upserted" : ObjectId("54f62bbfc85d4472eadea26d"),
     "n" : 1,
     "syncMillis" : 0,
     "writtenTo" : null,
     "err" : null,
     "ok" : 1
  },
  "value" : {
     "_id" : ObjectId("54f62bbfc85d4472eadea26d"),
     "name" : "Pascal",
     "rating" : 25,
     "state" : "active",
     "score" : 1
  },
  "ok" : 1
}

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.runCommand(
   {
     findAndModify: "people",
     query: { state: "active" },
     sort: { rating: 1 },
     remove: true
   }
)

O comando retorna o documento excluído:

{
  "lastErrorObject" : {
     "connectionId" : 1,
     "n" : 1,
     "syncMillis" : 0,
     "writtenTo" : null,
     "err" : null,
     "ok" : 1
  },
  "value" : {
     "_id" : ObjectId("54f62a6785e4be1f982b9c9b"),
     "name" : "XYZ123",
     "score" : 1,
     "state" : "active",
     "rating" : 3
  },
  "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.

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

A operação retorna o seguinte documento:

{
   "lastErrorObject" : {
      "updatedExisting" : true,
      "n" : 1
   },
   "value" : {
      "_id" : 1,
      "category" : "café",
      "status" : "A"
   },
   "ok" : 1
}

Operações de atualização de array com arrayFilters

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.runCommand(
   {
     findAndModify: "students",
     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.runCommand(
   {
     findAndModify: "students2",
     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

A partir do MongoDB 4.2, findAndModify pode aceitar 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).

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.runCommand(
   {
     findAndModify: "students2",
     query: {  "_id" : 1 },
     update: [ { $set: { "total" : { $sum: "$grades.grade" } } } ],
     new: true
   }
)

Após a operação, a coleção conta com os seguintes documentos:

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

Especifique o hint para Operações do findAndModify

No mongosh, crie uma coleção do members com os seguintes documentos:

db.members.insertMany( [
   { "_id" : 1, "member" : "abc123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" },
   { "_id" : 3, "member" : "lmn123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 4, "member" : "pqr123", "status" : "D", "points" : 20,  "misc1" : "Deactivated", "misc2" : null },
   { "_id" : 5, "member" : "ijk123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 6, "member" : "cde123", "status" : "A", "points" : 86,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }
] )

Crie os seguintes índices na coleção:

db.members.createIndex( { status: 1 } )
db.members.createIndex( { points: 1 } )

A operação a seguir sugere explicitamente o uso do índice { status: 1 }:

db.runCommand({
   findAndModify: "members",
   query: { "points": { $lte: 20 }, "status": "P" },
   remove: true,
   hint: { status: 1 }
})

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

db.runCommand(
   {
     explain: {
       findAndModify: "members",
       query: { "points": { $lte: 20 }, "status": "P" },
       remove: true,
       hint: { status: 1 }
     },
     verbosity: "queryPlanner"
   }
)

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.runCommand( {
   findAndModify: db.cakeFlavors.getName(),
   query: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
   update: { flavor: "orange" },
   let: { targetFlavor: "cherry" }
} )