update Evento

Imágenes previas y posteriores al documento

A partir de MongoDB 6.0, verás un documento fullDocumentBeforeChange con los campos que tenía el documento antes de ser cambiado (o eliminado) si realizas los siguientes pasos:

1. Habilite el nuevo campo changeStreamPreAndPostImages para una colección usando db.createCollection(), create, o collMod.

2. Configura fullDocumentBeforeChange en "required" o "whenAvailable" en db.collection.watch().

Ejemplo fullDocumentBeforeChange documento en la salida del flujo de cambios:

"fullDocumentBeforeChange" : {
   "_id" : ObjectId("599af247bb69cd89961c986d"),
   "userName" : "alice123",
   "name" : "Alice Smith"
}

Para obtener ejemplos completos con la salida del flujo de cambios, consulta Flujos de cambio con imágenes previas y posteriores de documentos.

Las imágenes previas y posteriores no están disponibles para un evento de flujo de cambios si las imágenes fueron:

• No está habilitado en la colección en el momento de la operación de actualización o eliminación de un documento.

• Eliminado después del tiempo de retención de imágenes previas y posteriores establecido en expireAfterSeconds.

  • El siguiente ejemplo configura expireAfterSeconds en 100 segundos en todo el clúster:

    use admin
    db.runCommand( {
       setClusterParameter:
          { changeStreamOptions: {
             preAndPostImages: { expireAfterSeconds: 100 }
          } }
    } )

    Nota

    El comando setClusterParameter no es compatible en los clústeres de MongoDB Atlas. Para obtener información sobre el soporte de Atlas para todos los comandos, consulta Comandos no admitidos en Atlas.

  • El siguiente ejemplo devuelve la configuración actual de changeStreamOptions, incluyendo expireAfterSeconds:

    db.adminCommand( { getClusterParameter: "changeStreamOptions" } )

  • Configurar expireAfterSeconds en off utiliza la política de retención por defecto: las imágenes previas y posteriores se conservan hasta que los eventos correspondientes del flujo de cambios se eliminan del oplog.

  • Si se elimina un evento de flujo de cambios del oplog, las imágenes previas y posteriores correspondientes también se eliminan independientemente del tiempo de retención de las imágenes previas y posteriores expireAfterSeconds.

Consideraciones adicionales:

• Habilitar las imágenes previas y posteriores consume espacio de almacenamiento y aumenta el tiempo de procesamiento. Habilita solo las imágenes previas y de publicación si las necesitas.

• Limita el tamaño del evento del flujo de cambios a menos de 16 mebibytes. Para limitar el tamaño del evento, puedes:

  • Limita el tamaño del documento a 8 megabytes. Puedes solicitar imágenes previas y posteriores simultáneamente en la salida del flujo de cambios si otros campos de eventos del flujo de cambios como updateDescription no son grandes.

  • Solicita solo imágenes posteriores en la salida del flujo de cambios para documentos de hasta 16 mebibytes si otros campos de eventos del flujo de cambios como updateDescription no son grandes.

  • Solicita solo imágenes previas en la salida del flujo de cambios para documentos de hasta 16 mebibytes si:

    • las actualizaciones de documento afectan solo a una pequeña fracción de la estructura o el contenido del documento, y

    • no cause un evento de cambio replace. Un evento replace siempre incluye la imagen de publicación.

• Para realizar una solicitud de imagen previa, debes establecer fullDocumentBeforeChange en required o whenAvailable en db.collection.watch(). Para solicitar una imagen posterior, establece fullDocument mediante el mismo método.

• Las imágenes previas se escriben en la colección config.system.preimages.

  • La colección config.system.preimages puede agrandarse. Para limitar el tamaño de la colección, puedes establecer el tiempo a expireAfterSeconds para las imágenes previas como se mostró antes.

  • Para supervisar el tamaño de config.system.preimages, conecta a un nodo de partición en un clúster o a un nodo mongod en un set de réplicas. A continuación, ejecuta los siguientes comandos:

    use config
    db.system.preimages.totalSize()
    db.system.preimages.stats()

  • Las imágenes previas se eliminan de forma asincrónica mediante un proceso en segundo plano.

Desambiguación de ruta

El campo updateDescription anota los cambios realizados en campos específicos de los documentos mediante una operación. Estos descriptores de campo utilizan puntos (.) como separadores de ruta y números como índices de arreglo, lo que conduce a cierta ambigüedad cuando contienen nombres de campo que utilizan puntos o números.

Cuando un evento update informa cambios que involucran campos ambiguos, el documento disambiguatedPaths proporciona la clave de ruta con un arreglo que lista cada componente de la ruta.

Por ejemplo, considera un documento que enumera a las personas y las ciudades en las que viven:

{
   "name": "Anthony Trollope",
   "home.town": "Oxford",
   "residences": [
      {"0": "Oxford"},
      {"1": "Sunbury"}
   ]
}

• Cuando una actualización modifica el campo home.town de Oxford a London, produce una descripción de actualización que se ve así:

  "updateDescription": {
     "updatedFields": {
        "home.town": "London"
     },
     "disambiguatedPaths": {
        "home.town": [ "home.town" ]
     }
  }

  Debido a que el campo home.town contiene un punto, el campo disambiguatedPaths muestra un arreglo con un único valor, para indicar que town no es un subcampo de home.

• Cuando una actualización modifica un valor en el arreglo residences para realizar el mismo cambio, se produce una descripción de actualización que se ve así:

  "updateDescription": {
     "updatedFields": {
        "residences.0.0": "London"
     },
     "disambiguatedPaths": { "residences.0.0": [ "residences", 0, "0" ] }
  }

  Los caminos desambiguados incluyen un entero 0 para indicar el índice del arreglo y la cadena "0" para indicar el nombre del campo dentro del documento anidado.

Hay dos casos en los que disambiguatedPath no incluye un campo numérico:

• Cuando el primer campo en la ruta es una string numérica (es decir, 0.name). Esto no es ambiguo, ya que el primer campo no puede ser un índice de arreglo.

• Cuando el campo de string numérica tiene ceros a la izquierda (es decir, 0001). Esto no es ambiguo, ya que un entero no puede tener ceros a la izquierda.

Operaciones de actualizar

El comando update puede producir diferentes eventos de cambio (no solo update) dependiendo de los cambios reales que realiza en la colección.

Comparación de actualizaciones estándar y actualizaciones por pipeline

En algunos escenarios, las actualizaciones estándar y las actualizaciones del pipeline pueden generar diferentes eventos de cambio para el mismo cambio lógico. Si cambias entre la sintaxis estándar y la de actualización de pipeline, puede que observes eventos de cambio inesperados en tu aplicación.

El siguiente ejemplo muestra cómo las diferentes sintaxis de actualización producen diferentes eventos de cambio al remover subcampos de documentos incrustados. Este es solo uno de los muchos escenarios en los que los eventos de cambio difieren según la sintaxis de actualización utilizada.

• Actualizaciones estándar: Cuando se eliminan subcampos de un objeto incrustado, las rutas eliminadas siempre están en el arreglo removedFields.

• Pipeline Updates: Cuando se eliminan subcampos de un objeto incrustado, el evento de cambio resultante muestra la descripción más concisa de la actualización. Por ejemplo:

  • Si se eliminan una pequeña cantidad de subcampos (por ejemplo, removiendo 1 de 3 subcampos), el cambio se muestra en el arreglo removedFields.

  • Si se remueven la mayoría de los subcampos (por ejemplo, eliminar 2 de 3 subcampos), el cambio se muestra en el arreglo updatedFields y el objeto principal refleja el nuevo estado.

El siguiente script de ejemplo muestra los diferentes eventos de cambio generados por actualizaciones estándar y actualizaciones de pipeline que remueven subcampos de un objeto:

// 1. Setup collection and insert documents for test cases
let contactMethods = {
   email: "user@example.com",
   phone: "555-0100",
   mobile: "555-0101"
};
db.cstest.drop();
db.cstest.insertMany([
   // Case 1: Remove 1 of 3 subfields
   { _id: "standard_remove_1_of_3", contactMethods: contactMethods },
   { _id: "pipeline_remove_1_of_3", contactMethods: contactMethods },
   // Case 2: Remove 2 of 3 subfields
   { _id: "standard_remove_2_of_3", contactMethods: contactMethods },
   { _id: "pipeline_remove_2_of_3", contactMethods: contactMethods }
]);
// 2. Open a Change Stream
const csCursor = db.cstest.watch();
// --- CASE 1: Remove 1 out of 3 subfields ---
db.cstest.updateOne({ _id: "standard_remove_1_of_3" }, { $unset: { "contactMethods.email": "" } });
db.cstest.updateOne({ _id: "pipeline_remove_1_of_3" }, [{ $unset: "contactMethods.email" }]);
// --- CASE 2: Remove 2 out of 3 subfields ---
db.cstest.updateOne({ _id: "standard_remove_2_of_3" }, { $unset: { "contactMethods.email": "", "contactMethods.phone": "" } });
db.cstest.updateOne({ _id: "pipeline_remove_2_of_3" }, [{ $unset: ["contactMethods.email", "contactMethods.phone"] }]);
// 3. Print the change stream updateDescriptions
print("\n--- Change Stream Results ---");
for (let i = 0; i < 4; i++) {
   if (csCursor.hasNext()) {
      let event = csCursor.next();
      print(`\nOperation: ${event.documentKey._id}`);
      print(JSON.stringify(event.updateDescription));
   }
}
csCursor.close();

--- Change Stream Results ---
Operation: standard_remove_1_of_3
{"updatedFields":{},"removedFields":["contactMethods.email"],"truncatedArrays":[]}
Operation: pipeline_remove_1_of_3
{"updatedFields":{},"removedFields":["contactMethods.email"],"truncatedArrays":[]}
Operation: standard_remove_2_of_3
{"updatedFields":{},"removedFields":["contactMethods.email","contactMethods.phone"],"truncatedArrays":[]}
Operation: pipeline_remove_2_of_3
{"updatedFields":{"contactMethods":{"mobile":"555-0101"}},"removedFields":[],"truncatedArrays":[]}

Array Updates

Las actualizaciones en los arreglos producen eventos de cambio update, pero el updateDescription.updateFields puede mostrar diferentes valores.

Por ejemplo, considera el siguiente documento y las actualizaciones:

db.students.insertOne( { student_id: 1, scores: [ ] } )
db.students.updateOne(
   { student_id: 1 },
   { $push: { scores: 0.85 } }
)
db.students.updateOne(
   { student_id: 1 },
   { $push: { scores: 0.94 } }
)
db.students.updateOne(
   { student_id: 1 },
   { $pull: { scores: 0.94 } }
)

La primera actualización opera sobre un arreglo vacío. Aquí, $push produce un evento de cambio update en el cual el campo es reemplazado por un arreglo de una sola entrada con el valor dado:

{
   _id: { _data: '82642AD66B000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
   operationType: 'update',
   clusterTime: Timestamp({ t: 1680529003, i: 1 }),
   ns: { db: 'communication_chat', coll: 'students' },
   documentKey: { student_id: 1 },
   updateDescription: {
      updatedFields: { scores: [ 0.85 ] },
      removedFields: [],
      truncatedArrays: []
   }
}

En la segunda operación de actualización, el arreglo ahora contiene valores. El $push añade una nueva entrada en el arreglo. El evento de cambio update lo muestra como un cambio en la nueva posición del arreglo (es decir, scores.1):

{
  _id: { _data: '82642AD673000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
  operationType: 'update',
  clusterTime: Timestamp({ t: 1680529011, i: 1 }),
  ns: { db: 'communication_chat', coll: 'students' },
  documentKey: { student_id: 1 },
  updateDescription: {
    updatedFields: { 'scores.1': 0.94 },
    removedFields: [],
    truncatedArrays: []
  }
}

Si ejecutas la operación de actualización de nuevo para añadir una tercera puntuación al registro del estudiante, se produciría un evento de cambio update que modifica scores.2.

La eliminación de elementos de arreglo con el operador $pull produce un evento de cambio que muestra el nuevo arreglo:

{
  _id: { _data: '82642AD673000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
  operationType: 'update',
  clusterTime: Timestamp({ t: 1680529011, i: 1 }),
  ns: { db: 'communication_chat', coll: 'students' },
  documentKey: { student_id: 1 },
  updateDescription: {
    updatedFields: { scores: [ 0.85 ] },
    removedFields: [],
    truncatedArrays: []
  }
}

Truncamiento de arreglo

Las operaciones de actualización que reducen el número de elementos en los arreglos mediante las actualizaciones por etapas (pipeline), como en las etapas de agregación $addFields o $set, muestran el arreglo actualizado y el nuevo tamaño en el campo truncatedArrays.

db.students.insertOne( { student_id: 2, scores: [ 0.85, 0.94, 0.78 ] } )
db.students.updateOne(
   { student_id: 2 },
   [ { $addFields: { scores: [ 0.85, 0.94 ] } } ]
)
db.students.updateOne(
   { student_id: 2 },
   [ { $addFields: { scores: [ 0.85, 0.94, 0.78 ] } } ]
)

El evento de cambio de la primera actualización, que utilizó la etapa $addFields para remover un valor del campo scores muestra el cambio en el campo truncatedArrays:

{
  _id: { _data: '82642AD673000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
  operationType: 'update',
  clusterTime: Timestamp({ t: 1680529011, i: 1 }),
  ns: { db: 'communication_chat', coll: 'students' },
  documentKey: { student_id: 2 },
  updateDescription: {
    updatedFields: {},
    removedFields: [],
    truncatedArrays: [ { fields: "scores", newSize: 2 } ]
  }
}

El evento de cambio de la segunda actualización, que usó la etapa $addFields para agregar un valor de vuelta al campo scores, muestra la actualización en el campo updatedFields:

{
  _id: { _data: '82642AD673000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
  operationType: 'update',
  clusterTime: Timestamp({ t: 1680529011, i: 1 }),
  ns: { db: 'communication_chat', coll: 'students' },
  documentKey: { student_id: 2 },
  updateDescription: {
    updatedFields: { scores.2: 0.78 },
    removedFields: [],
    truncatedArrays: []
  }
}