update Evento

Documentar imágenes previas y posteriores

A partir de MongoDB 6.0, verá un documento fullDocumentBeforeChange con los campos anteriores a que se cambiara (o eliminara) el documento si realiza estos pasos:

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

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

Ejemplo de documento fullDocumentBeforeChange 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 con los clústeres de MongoDB Atlas. Para obtener información sobre el soporte de Atlas para todos los comandos, consulta Comandos no compatibles 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.

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

Desambiguación de ruta

El campo updateDescription indica 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 matriz, lo que genera 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 una matriz que enumera cada componente de la ruta.

Por ejemplo, consideremos un documento que enumera 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 una matriz con un valor, para indicar que town no es un subcampo de home.

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

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

  Las rutas desambiguadas incluyen un entero 0 para indicar el índice de la matriz 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 de la ruta es una cadena numérica (por ejemplo, 0.name). Esto no es ambiguo, ya que el primer campo no puede ser un índice de matriz.

• Cuando el campo de cadena 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 puede producir update update diferentes eventos de cambio (no solo) dependiendo de los cambios reales que realice en la colección.

Array Updates

Las actualizaciones de matrices producen eventos de cambio update, pero updateDescription.updateFields puede mostrar valores diferentes.

Por ejemplo, considere el siguiente documento y sus 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 una matriz vacía. Aquí, produce $push un update evento de cambio donde el campo se reemplaza por una matriz 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, la matriz ahora contiene valores. El añade una nueva entrada a la matriz.$push El update evento de cambio la muestra como un cambio en la nueva posición de la matriz (esscores.1 decir,):

{
  _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 ejecuta la operación de actualización nuevamente para agregar una tercera puntuación al registro del estudiante, producirá un evento de cambio update que modifica scores.2.

La eliminación de elementos de la matriz con el $pull operador produce un evento de cambio que muestra la nueva matriz:

{
  _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 matriz

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 utilizó la $addFields etapa para agregar un valor nuevamente al scores campo, muestra la actualización en el updatedFields campo:

{
  _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: []
  }
}