db.collection.findAndModify() (método mongosh)

Parámetros

El método db.collection.findAndModify() toma un parámetro de documento con los siguientes campos de documento incrustado:

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

// INVALID
[
  { "x.a": { $gt: 85 } },
  { "x.b": { $gt: 80 } }
]

// Example 1
[
  { $or: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 2
[
  { $and: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 3
[
  { "x.a": { $gt: 85 }, "x.b": { $gt: 80 } }
]

{
  <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n>
}

Rendimiento

Para las escrituras reintentables, el método findAndModify() debe copiar todo el documento en una colección paralela especial para cada nodo de un set de réplicas antes de realizar la actualización. Esto puede hacer que findAndModify() sea una operación costosa cuando se trata de documentos grandes o sets de réplicas grandes.

fields Proyección

La opción fields acepta un documento en la siguiente forma:

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

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

Si todas las operaciones findOneAndUpdate() finalizan la fase del query antes de que cualquier cliente inserte datos correctamente, y no hay un índice único en el campo name, cada operación findOneAndUpdate() puede tener como resultado una inserción, lo que crea múltiples documentos con name: Andy.

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

• Exactamente una findOneAndUpdate() operación insertará correctamente un nuevo documento.

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

  Para que otras operaciones findOneAndUpdate() puedan actualizar el documento recién insertado, se deben cumplir todas las condiciones siguientes:

  • 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 particionada:

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

• A partir de la versión 7.1, no es necesario indicar la clave de partición ni el campo _id en la especificación de la 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 método db.collection.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, db.collection.findAndModify() y el método updateOne() operan de manera diferente:

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

  updateOne() actualiza el primer documento que coincide.

• Por defecto, db.collection.findAndModify() devuelve la versión premodificada del documento. Para obtener el documento actualizado, utiliza la opción new.

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

db.collection.findAndModify() puede usarse dentro de transacciones distribuidas.

Entradas de OpLog

Si una operación db.collection.findAndModify() encuentra y modifica correctamente un documento, la operación agrega una entrada en el oplog (registro de operaciones). Si la operación falla o no encuentra un documento para modificar, la operación no agrega una entrada en el oplog.

Errores de nivel de confirmación de escritura

En versiones de MongoDB anteriores a 6.0, si el comando findAndModify se ejecuta en un clúster particionado, mongos descarta el documento writeConcernError si la respuesta de la partición contiene un error. En MongoDB 6.0 y versiones posteriores, mongos devuelve writeConcernError.

Actualizar y devolver

El siguiente método actualiza y devuelve un documento existente en la colección de personas en la que el documento coincide con los criterios del query:

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

Este método 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. sort ordena los resultados del query en orden ascendente. Si varios documentos cumplen con la condición query, el método seleccionará la modificación del primer documento según el orden de este sort.

3. La actualización increments incrementa el valor del campo score en 1.

4. El método devuelve el documento original (es decir, previo a la modificación) seleccionado para esta actualización:

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

   Para devolver el documento actualizado, agregue la opción new:true al método.

   Si ningún documento cumple con la condición query, el método devuelve null.

Inserción

El siguiente método incluye la opción upsert: true para la operación update con el fin de actualizar un documento coincidente o, si no existe ningún documento coincidente, crear un nuevo documento:

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

Si el método encuentra un documento coincidente, hace una actualización.

Si el método no encuentra un documento coincidente, el método crea un nuevo documento. Debido a que el método incluía la opción sort, devuelve un documento vacío { } como el documento original (previo a la modificación):

{ }

Si el método no incluye una opción sort, el método devuelve null.

null

Devolver nuevo documento

El siguiente método incluye tanto la opción upsert: true como la opción new:true. El método actualiza un documento coincidente y devuelve el documento actualizado o, si no existe ningún documento coincidente, inserta un documento y devuelve el documento recién insertado en el campo value.

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

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

El método devuelve el documento recién insertado:

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

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

El método devuelve el documento borrado:

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

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

La operación devuelve el siguiente documento:

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

Especifique arrayFilters para una operación de actualización de matriz

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

Utiliza una canalización de agregación para actualizaciones

db.collection.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.students2.findAndModify( {
   query: {  "_id" : 1 },
   update: [ { $set: { "total" : { $sum: "$grades.grade" } } } ],  // The $set stage is an alias for ``$addFields`` stage
   new: true
} )

La operación devuelve el documento actualizado:

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

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

Roles de usuario y actualizaciones de documentos

A partir de MongoDB 7.0, puedes usar la nueva variable de sistema USER_ROLES para devolver los roles de usuario.

El ejemplo en esta sección muestra actualizaciones de campos en una colección que contiene información médica. El ejemplo lee los roles de usuario actuales de la variable de sistema USER_ROLES y solo realiza las actualizaciones si el usuario tiene un rol específico.

Para usar una variable del sistema, agrega $$ al inicio del nombre de la variable. Especifica la variable del sistema USER_ROLES como $$USER_ROLES.

El ejemplo crea a estos usuarios:

• James con un rol Billing.

• Michelle con un rol Provider.

Realiza los siguientes pasos para crear los roles, los usuarios y la colección:

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

Inicia sesión como Michelle, quien tiene el rol Provider, y realiza una actualización:

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

El ejemplo anterior utiliza $setIntersection para devolver documentos donde la intersección entre la string "Provider" y los roles de usuario de $$USER_ROLES.role no está vacía. Michelle tiene el rol Provider, por lo tanto, se realiza la actualización.

A continuación, inicia sesión como James, que no tiene el rol de Provider, e intenta volver a actualizar:

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

El ejemplo anterior no actualiza ningún documento.