db.watch() (método mongosh)

Definición

db.watch( pipeline, options )

Solo para Sets de réplicas y clústeres fragmentados

Abre un cursor de streaming de cambios para una base de datos que informe sobre todas sus colecciones no system.

Parameter	Tipo	Descripción
pipeline	arreglo	Opcional. Una canalización de agregación que consiste en una o más de las siguientes etapas de agregación: $addFields $match $project $replaceRoot $replaceWith $redact $set $unset Especifica un pipeline para filtrar o modificar la salida de los eventos de cambio. A partir de MongoDB 4.2, los flujos de cambios lanzarán una excepción si la pipeline de agregación de flujos de cambios modifica el campo _id de un evento.
options	Documento	Opcional. Opciones adicionales que modifican el comportamiento de db.watch().

El documento options puede contener los siguientes campos y valores:

Campo	Tipo	Descripción
resumeAfter	Documento	opcional. Especifica un token de reanudación (resume token) como el punto de partida lógico para el flujo de cambios. No se puede usar para reanudar el flujo de cambios después de un invalidate evento. resumeAfter es mutuamente excluyente con startAfter y startAtOperationTime.
startAfter	Documento	Opcional. Especifica un token de reanudación como el punto de inicio lógico para el flujo de cambios. A diferencia de resumeAfter, startAfter puede reanudar las notificaciones después de un evento invalidate creando un nuevo flujo de cambios. startAfter es mutuamente excluyente con resumeAfter y startAtOperationTime.
fullDocument	string	Opcional. Por defecto, db.watch() devuelve el delta de los campos modificados por una operación de actualización, en lugar del documento actualizado completo. Establezca fullDocument en "updateLookup" para dirigir db.watch() a buscar la versión más reciente confirmada por la mayoría del documento actualizado. db.watch() devuelve un campo fullDocument con la búsqueda del documento además del delta updateDescription. A partir de MongoDB 6.0, puede configurar fullDocument para: "whenAvailable" para mostrar el documento después de la imagen, si está disponible, después de insertar, reemplazar o actualizar el documento. "required" para generar la imagen del documento después de que se haya insertado, reemplazado o actualizado. Genera un error si la imagen de publicación no está disponible.
fullDocumentBeforeChange	string	Opcional. El valor por defecto es "off". A partir de MongoDB 6.0, puede usar el nuevo campo fullDocumentBeforeChange y configurarlo en: "whenAvailable" para mostrar la imagen anterior del documento, si está disponible, antes de que el documento sea reemplazado, actualizado o borrado. "required" para mostrar la imagen previa del documento antes de que el documento fuera reemplazado, actualizado o borrado. Genera un error si la pre-imagen no está disponible. "off" para suprimir la imagen anterior del documento. "off" es el valor por defecto.
batchSize	Int	opcional. Especifica el número máximo de eventos de cambio a devolver en cada agrupar de la respuesta del clúster de MongoDB. Tiene la misma funcionalidad que cursor.batchSize().
maxAwaitTimeMS	Int	Opcional. El tiempo máximo en milisegundos que el servidor espera para que los nuevos cambios de datos se informen al cursor del flujo de cambios antes de devolver una agrupación vacía. Se establece por defecto en 1000 milisegundos.
collation	Documento	Opcional. Pasa un documento de intercalación para especificar una intercalación para el cursor del flujo de cambios. Si se omite, por defecto se realizará la comparación binaria simple.
startAtOperationTime	Marca de tiempo	Opcional. El punto de inicio para el flujo de cambios. Si el punto de inicio especificado está en el pasado, debe encontrarse dentro del rango de tiempo del oplog. Para comprobar el rango temporal del oplog, consulta rs.printReplicationInfo(). startAtOperationTime es mutuamente excluyente con resumeAfter y startAfter.

Devuelve:	Un cursor sobre los documentos de eventos de cambio. Consultar Eventos de Change Stream para ejemplos de documentos de eventos de cambio.

Tip

db.collection.watch() y Mongo.watch()

Compatibilidad

Este método está disponible en implementaciones alojadas en los siguientes entornos:

• MongoDB Atlas: El servicio totalmente administrado para implementaciones de MongoDB en la nube.

• MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB

• MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

Disponibilidad

Comportamiento

• No puede ejecutar db.watch() en la base de datos admin, local o config.

• db.watch() solo notifica a la mayoría de los miembros portadores de datos sobre cambios en los datos que han persistido.

• El cursor de flujo de cambios permanece abierto hasta que ocurra una de las siguientes situaciones:

  • El cursor se cierra explícitamente.

  • Se produce un evento de invalidación; por ejemplo, un descarte o cambio de nombre de una colección.

  • La conexión a la implementación de MongoDB se cierra o se agota el tiempo de espera. Consulta Comportamiento para obtener más información.

  • Si la implementación es un clúster, la remoción de una partición puede causar que un cursor de flujo de cambios abierto se cierre, y el cursor de flujo de cambios cerrado podría no ser completamente reanudable.

• Puedes ejecutar db.watch() para una base de datos que no existe. Sin embargo, una vez creada la base de datos y eliminada, el cursor de flujo de cambios se cierra.

Control de acceso

Al ejecutar con control de acceso, el usuario debe tener las acciones de privilegio find y changeStream en el recurso de la base de datos. Es decir, un usuario debe tener un rol que otorgue el siguiente privilegio:

{ resource: { db: <dbname>, collection: "" }, actions: [ "find", "changeStream"] }

El rol read incorporado proporciona los privilegios apropiados.

Iteración de cursor

MongoDB ofrece múltiples maneras de iterar sobre un cursor.

El cursor.hasNext() método se bloquea y espera el siguiente evento. Para supervisar el cursor watchCursor e iterar sobre los eventos, utiliza hasNext() de esta manera:

while (!watchCursor.isClosed()) {
   if (watchCursor.hasNext()) {
     firstChange = watchCursor.next();
     break;
   }
}

El cursor.tryNext() método es no bloqueante. Para supervisar el cursor watchCursor e iterar sobre los eventos, utiliza tryNext() de esta manera:

while (!watchCursor.isClosed()) {
  let next = watchCursor.tryNext()
  while (next !== null) {
    printjson(next);
    next = watchCursor.tryNext()
  }
}

Ejemplo

La siguiente operación en mongosh abre un cursor de flujo de cambios en la base de datos hr. El cursor devuelto informa sobre los cambios de datos en todas las colecciones que no sean system en esa base de datos.

watchCursor = db.getSiblingDB("hr").watch()

Itera el cursor para verificar si hay nuevos eventos. Utiliza el método cursor.isClosed() junto con el método cursor.tryNext() para asegurarte de que el bucle solo salga si el cursor del flujo de cambios está cerrado y no quedan objetos en el último grupo:

while (!watchCursor.isClosed()) {
  let next = watchCursor.tryNext()
  while (next !== null) {
    printjson(next);
    next = watchCursor.tryNext()
  }
}

Para obtener la documentación completa sobre la salida del flujo de cambios, consulta Eventos de flujo de cambios.