findAndModify (comando de base de datos)

lastErrorObject

El documento incrustado lastErrorObject contiene los siguientes campos:

value

Para las operaciones remove, value contiene el documento eliminado si la consulta encuentra un documento. Si la consulta no encuentra un documento para eliminar, value contiene null.

Para las operaciones update, el documento incrustado value contiene lo siguiente:

• Si el parámetro new no está establecido o es false:

  • el documento antes de la modificación si el query coincide con un documento;

  • de lo contrario, null.

• Si new es true:

  • el documento actualizado si el query devuelve una coincidencia;

  • el documento insertado si upsert: true y ningún documento coincide con el query;

  • de lo contrario, null.

Inserción con un índice único

Los upserts pueden crear documentos duplicados, a menos que haya un índice único para evitar duplicados.

Considere un ejemplo en el que no existe ningún documento con el nombre Andy y varios clientes emiten el siguiente comando aproximadamente al mismo tiempo:

db.runCommand(
   {
     findAndModify: "people",
     query: { name: "Andy" },
     update: { $inc: { score: 1 } },
     upsert: true
   }
)

Si todas las operaciones findAndModify terminan la fase de query antes de que algún cliente inserte correctamente los datos y no hay un índice único en el campo name, cada operación findAndModify puede ocasionar una inserción, creando múltiples documentos con name: Andy.

Un índice único en el campo name asegura que solo se cree un documento. Con un índice único en su lugar, las múltiples findAndModify operaciones ahora muestran el siguiente comportamiento:

• Exactamente una findAndModify operación insertará exitosamente un nuevo documento.

• Otras findAndModify operaciones actualizan el documento recién insertado o fallan debido a una colisión de clave única.

  Para que otras operaciones de findAndModify actualicen el documento recién insertado, todas las siguientes condiciones deben cumplirse:

  • La colección objetivo tiene un índice único que causaría un error de clave duplicada.

  • La operación de actualización no es updateMany o multi es false.

  • La condición de coincidencia de actualización es:

    • Un único predicado de igualdad. Por ejemplo { "fieldA" : "valueA" }

    • Un AND lógico de predicados de igualdad. Por ejemplo { "fieldA" : "valueA", "fieldB" : "valueB" }

  • Los campos del predicado de igualdad coinciden con los campos del patrón de clave del índice único.

  • La operación de actualización no modifica ningún campo en el patrón de clave de índice único.

La siguiente tabla muestra ejemplos de operaciones de upsert que, cuando ocurre una colisión de clave, se actualizan o fallan.

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

Colecciones fragmentadas

Para usar findAndModify en una colección fragmentada:

• Si solo apunta a una partición, puede usar una clave de partición parcial en el campo query o

• Puede proporcionar una condición de igualdad en una clave de partición completa en el campo query.

Es posible que a los documentos de una colección fragmentada les falten los campos de clave de fragmento. Para identificar un documento que no tenga la clave de fragmento, puede usar la null coincidencia de igualdad. Junto con otra condición de filtro (como en el _id campo). Por ejemplo:

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

Validación de esquema

El comando findAndModify añade compatibilidad con la opción bypassDocumentValidation, que le permite omitir la validación de esquema al insertar o actualizar documentos en una colección con reglas de validación.

Comparaciones con el update método

Al actualizar un documento, findAndModify y el método updateOne() operan de manera diferente:

• Si varios documentos cumplen con los criterios de actualización, para findAndModify, puedes especificar un sort que proporcione cierto control sobre qué documento actualizar.

  updateOne() actualiza el primer documento que coincide.

• Por defecto, findAndModify devuelve un objeto que contiene la versión premodificada del documento, así como el estado de la operación. Para obtener el documento actualizado, utilice la new opción.

  El método updateOne() devuelve un objeto WriteResult() que contiene el estado de la operación.

  Para devolver el documento actualizado, utilice el método find(). Sin embargo, es posible que otras actualizaciones hayan modificado el documento entre su actualización y la recuperación del documento. Además, si la actualización modificó solo un documento, pero varios documentos coincidieron, necesitará usar lógica adicional para identificar el documento actualizado.

Al modificar un solo documento, tanto el método findAndModify como updateOne() actualizan el documento atómicamente. Consulte Atomicidad y transacciones para obtener más información sobre las interacciones y el orden de las operaciones de estos métodos.

Transacciones

findAndModify puede usarse dentro de transacciones distribuidas.

Actualizar y devolver

El siguiente comando actualiza un documento existente en la colección people donde el documento coincide con los criterios query:

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

Este comando realiza las siguientes acciones:

1. El query encuentra un documento en la colección people donde el campo name tiene el valor Tom, el campo state tiene el valor active y el campo rating tiene un valor de greater than 10.

2. El sort ordena los resultados de la consulta en orden ascendente. Si varios documentos cumplen la condición query, el comando seleccionará para su modificación el primer documento ordenado por este sort.

3. El update increments el valor del score campo 1 por.

4. El comando devuelve un documento con los siguientes campos:

   • El campo lastErrorObject que contiene los detalles del comando, incluido el campo updatedExisting que es true, y

   • El campo value que contiene el documento original (es decir, anterior a la modificación) seleccionado para esta actualización:

     {
       "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 devolver el documento actualizado en el campo value, agregue la opción new:true al comando.

Si ningún documento coincide con la condición query, el comando devuelve un documento que contiene null en el campo value:

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

mongosh y muchos controladores proporcionan un método auxiliar. Con el auxiliar del shell, esta operación previa puede adoptar la siguiente findAndModify() forma:

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

Sin embargo, el método auxiliar de shell solo devuelve el documento sin modificar findAndModify() o,new si true es, el documento actualizado.

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

upsert: true

El siguiente comando incluye findAndModify la upsert: true opción para la update operación para actualizar un documento coincidente o, si no existe ningún documento coincidente, crear un nuevo documento:

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

Si el comando encuentra un documento coincidente, realiza una actualización.

Si el comando no encuentra un documento coincidente, la operación update con upsert: true genera una inserción y devuelve un documento con los siguientes campos:

• El campo lastErrorObject que contiene los detalles del comando, incluido el campo upserted que contiene el valor _id del documento recién insertado, y

• El campo value que contiene null.

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

Devolver nuevo documento

El siguiente comando findAndModify incluye upsert: true las opciones new:true y. El comando actualiza un documento coincidente y devuelve el documento actualizado o, si no existe ningún documento coincidente, inserta un documento y devuelve el nuevo documento insertado en el value campo.

En el siguiente ejemplo, ningún documento de la colección people cumple con la condición query:

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

El comando devuelve el documento recién insertado en el 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
}

Ordenar y remover

Al incluir una especificación sort en el campo rating, el siguiente ejemplo remueve de la colección people un único documento que tiene el valor state de active y el rating más bajo entre los documentos coincidentes:

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

El comando devuelve el documento eliminado:

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

Especificar la intercalación

La intercalación permite a los usuarios especificar reglas propias del lenguaje para la comparación de strings, como reglas para el uso de mayúsculas y minúsculas y marcas de acento.

Una colección myColl tiene los siguientes documentos:

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

La siguiente operación incluye la opción de intercalación:

db.runCommand(
   {
     findAndModify: "myColl",
     query: { category: "cafe", status: "a" },
     sort: { category: 1 },
     update: { $set: { status: "Updated" } },
     collation: { locale: "fr", strength: 1 }
   }
)

La operación devuelve el siguiente documento:

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

Operaciones de actualización de arreglos con arrayFilters

Al actualizar el campo de un arreglo, puede especificar arrayFilters que determinen qué elementos del arreglo actualizar.

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

Utiliza una canalización de agregación para actualizaciones

findAndModify puede aceptar un pipeline de agregación para la actualización. El pipeline puede constar de las siguientes etapas:

• $addFields y su alias $set

• $project y su alias $unset

• $replaceRoot y su alias $replaceWith

El uso de un pipeline de agregación permite una instrucción de actualización más expresiva, como expresar actualizaciones condicionales basadas en los valores actuales de los campos o actualizar un campo con el valor de otros campos.

Por ejemplo, cree una colección students2 con los siguientes 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 }
      ]
   }
] )

La siguiente operación encuentra un documento donde el campo _id es igual a 1 y utiliza una canalización de agregación para calcular un nuevo campo total a partir del campo grades:

db.runCommand(
   {
     findAndModify: "students2",
     query: {  "_id" : 1 },
     update: [ { $set: { "total" : { $sum: "$grades.grade" } } } ],
     new: true
   }
)

Después de la operación, la colección tiene los siguientes 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 hint para findAndModify operaciones

En mongosh, crea una colección de members con los siguientes 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" }
] )

Cree los siguientes índices en la colección:

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

La siguiente operación sugiere explícitamente utilizar el índice { status: 1 }:

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

Para ver el índice utilizado, ejecuta explain en la operación:

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

Usar variables en let

Para definir variables a las que puedes acceder en otros lugares del comando, utiliza la opción let.

Cree una colección cakeFlavors:

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

El siguiente ejemplo define una variable targetFlavor en let y utiliza la variable para cambiar el sabor del pastel de cereza a naranja:

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