encontrar e modificar

lastErrorObject

The lastErrorObject embedded document contains the following fields:

value

For remove operations, value contains the removed document if the query matches a document. If the query does not match a document to remove, value contains null.

For update operations, the value embedded document contains the following:

• If the new parameter is not set or is false:

  • the pre-modification document if the query matches a document;

  • otherwise, null.

• If new is true:

  • the updated document if the query returns a match;

  • the inserted document if upsert: true and no document matches the query;

  • otherwise, 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 AND 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:

• If you only target one shard, you can use a partial shard key in the query field or,

• You can provide an equality condition on a full shard key in the query field.

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

Documentos em uma coleção fragmentada podem estar faltando os campos de chave de estilhaço. Para direcionar um documento que não tenha a chave de fragmento, você pode usar a correspondência de igualdade null 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 de esquema

O comando findAndModify 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.

Comparisons with the update Method

When updating a document, findAndModify and the updateOne() method operate differently:

• If multiple documents match the update criteria, for findAndModify, you can specify a sort to provide some measure of control on which document to update.

  updateOne() updates the first document that matches.

• By default, findAndModify returns an object that contains the pre-modified version of the document, as well as the status of the operation. To obtain the updated document, use the new option.

  The updateOne() method returns a WriteResult() object that contains the status of the operation.

  To return the updated document, use the find() method. However, other updates may have modified the document between your update and the document retrieval. Also, if the update modified only a single document but multiple documents matched, you will need to use additional logic to identify the updated document.

When modifying a single document, both findAndModify and the updateOne() method atomically update the document. See Atomicidade e Transações for more details about interactions and order of operations of these methods.

Transações

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

Update and Return

The following command updates an existing document in the people collection where the document matches the query criteria:

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

This command performs the following actions:

1. The query finds a document in the people collection where the name field has the value Tom, the state field has the value active and the rating field has a value greater than 10.

2. The sort orders the results of the query in ascending order. If multiple documents meet the query condition, the command will select for modification the first document as ordered by this sort.

3. The update increments the value of the score field by 1.

4. The command returns a document with the following fields:

   • The lastErrorObject field that contains the details of the command, including the field updatedExisting which is true, and

   • The value field that contains the original (i.e. pre-modification) document selected for this update:

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

To return the updated document in the value field, add the new:true option to the command.

If no document match the query condition, the command returns a document that contains null in the value field:

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

mongosh and many drivers provide a findAndModify() helper method. Using the shell helper, this previous operation can take the following form:

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

However, the findAndModify() shell helper method returns only the unmodified document, or if new is true, the updated document.

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

upsert: true

The following findAndModify command includes the upsert: true option for the update operation to either update a matching document or, if no matching document exists, create a new document:

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

If the command finds a matching document, the command performs an update.

If the command does não find a matching document, the update with upsert: true operation results in an insertion and returns a document with the following fields:

• The lastErrorObject field that contains the details of the command, including the field upserted that contains the _id value of the newly inserted document, and

• The value field containing null.

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

Return New Document

The following findAndModify command includes both upsert: true option and the new:true option. The command either updates a matching document and returns the updated document or, if no matching document exists, inserts a document and returns the newly inserted document in the value field.

In the following example, no document in the people collection matches the query condition:

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

The command returns the newly inserted document in the value field:

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

Sort and Remove

By including a sort specification on the rating field, the following example removes from the people collection a single document with the state value of active and the lowest rating among the matching documents:

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

The command returns the deleted document:

{
  "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 can accept an aggregation pipeline for the update. The pipeline can consist of the following stages:

• $addFields e seu apelido $set

• $project e seu apelido $unset

• $replaceRoot e seu apelido $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 } ]
}

Specify hint for findAndModify Operations

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 } )

The following operation explicitly hints to use the index { 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" }
] )

The following example defines a targetFlavor variable in let and uses the variable to change the cake flavor from cherry to orange:

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