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 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 findAndModify 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 findAndModify agora apresentam 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 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 fragmentadas

Para usar findAndModify em uma coleção 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.

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 comando findAndModify traz suporte para a opção bypassDocumentValidation, que permite ignorar a validação do documento ao inserir ou atualizar documentos em uma coleção com regras de validação.

Comparações com o update método

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 fornecer 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, assim como 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.

Se modificar um único documento, ambos o 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 findAndModify() auxiliar. Utilizando o assistente 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

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.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

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

Especificar hint para findAndModify operações

No mongosh, crie uma coleção 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" }
} )