MongoDB\Database::watch()

Definición

MongoDB\Database::watch()

Ejecuta una Operación deflujo de cambios en la base de datos. Se puede supervisar el flujo de cambios para detectar cambios a nivel de base de datos.

function watch(
    array $pipeline = [],
    array $options = []
): MongoDB\ChangeStream

Parámetros

$pipeline : matriz|objeto

La secuencia de etapas que se agregarán a una etapa inicial $changeStream.

$options : matriz

Una matriz que especifica las opciones deseadas.

Nombre	Tipo	Descripción
tamaño del lote	entero	El número máximo de documentos dentro de cada lote devuelto en un flujo de cambios, que se aplica al comando aggregate. De forma predeterminada, el comando aggregate tiene un tamaño de lote inicial de 101 documentos y un tamaño máximo de 16 mebibytes (MiB) para cada lote posterior. Esta opción puede imponer un límite inferior a 16 MiB, pero no superior. Si se establece batchSize en un límite que resulte en lotes superiores a 16 MiB, esta opción no tiene efecto. Independientemente de la opción batchSize, la respuesta del comando aggregate inicial para un flujo de cambios generalmente no incluye ningún documento a menos que se utilice otra opción para configurar su punto de inicio (por ejemplo, startAfter).
codec	MongoDB\Códec\DocumentCodec	El Codificar datos con códecs de tipo para codificar o decodificar documentos. Esta opción es mutuamente excluyente con la typeMap opción. Nuevo en la versión 1.17.
intercalación	matriz|objeto	Laintercalación permite a los usuarios especificar reglas específicas del idioma para la comparación de cadenas, como el uso de mayúsculas y minúsculas y tildes. Al especificar la intercalación, el locale campo es obligatorio; todos los demás campos son opcionales. Para obtener descripciones de los campos, consulte el documento de intercalación.
comment	mixto	Permite a los usuarios especificar un comentario arbitrario para ayudar a rastrear la operación a través del generador de perfiles de base de datos, la salidacurrentOp y los registros. El comentario puede ser cualquier tipo BSON válido a partir de MongoDB 4.4. Las versiones anteriores del servidor solo admiten valores de cadena. Novedades en la versión 1.13.
documento completo	string	Determina cómo se completará el campo de respuesta fullDocument para las operaciones de actualización. De forma predeterminada, los flujos de cambio solo devuelven la delta de los campos (mediante un campo updateDescription) para las operaciones de actualización, y se omite fullDocument. Las operaciones de inserción y reemplazo siempre incluyen el campo fullDocument. Las operaciones de eliminación omiten el campo, ya que el documento ya no existe. Especifique "updateLookup" para devolver la versión mayoritariamente confirmada actual del documento actualizado. A partir de MongoDB 6.0, puede acceder a la imagen posterior del documento modificado si la colección tiene habilitado changeStreamPreAndPostImages. Especifique whenAvailable para devolver la imagen posterior si está disponible o un valor nulo si no lo está. Especifique "required" para devolver la imagen posterior si está disponible o generar un error si no lo está. Se admiten los siguientes valores: MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED Esta es una opción de la etapa de canalización $changeStream.
Documento completo antes del cambio	string	Determina cómo se rellenará el campo de respuesta fullDocumentBeforeChange. Por defecto, este campo se omite. MongoDB 6.0+ permite devolver la preimagen del documento modificado si la colección tiene changeStreamPreAndPostImages habilitado. Especifique "whenAvailable" para devolver la preimagen si está disponible o un valor nulo si no lo está. Especifique "required" para devolver la preimagen si está disponible o generar un error si no lo está. Se admiten los siguientes valores: MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED Esta es una opción de la etapa de canalización $changeStream. Novedades en la versión 1.13.
maxAwaitTimeMS	entero	Entero positivo que indica el límite de tiempo en milisegundos para que el servidor bloquee una operación getMore si no hay datos disponibles.
readConcern	MongoDB\Driver\ReadConcern	Preocupación de lectura para la operación. El valor predeterminado es la preocupación de lectura de la base de datos.
readPreference	MongoDB\Controlador\Preferencia de lectura	Preferencia de lectura para la operación. El valor predeterminado es la preferencia de lectura de la base de datos. Esto se utiliza tanto para la agregación del flujo de cambio inicial como para la selección del servidor durante una reanudación automática.
reanudarDespués	matriz|objeto	Especifica el punto de inicio lógico para el nuevo flujo de cambios. Aquí se puede usar el campo _id en los documentos devueltos por el flujo de cambios. Usar esta opción junto con startAfter o startAtOperationTime provocará un error del servidor. Las opciones son mutuamente excluyentes. Esta es una opción de la etapa de canalización $changeStream.
sesión	MongoDB\Controlador\Sesión	Sesión de cliente para asociar a la operación.
mostrarEventosExpandidos	booleano	Si es verdadero, indica al servidor que incluya eventos DDL adicionales en el flujo de cambios. Los eventos adicionales que se pueden incluir son: createIndexes dropIndexes modify create shardCollection reshardCollection (servidor 6.1+) refineCollectionShardKey (servidor 6.1+) Esto no es compatible con versiones de servidor anteriores a 6.0 y generará una excepción en el momento de ejecución si se utiliza. Esta es una opción de la etapa de canalización $changeStream. Novedades en la versión 1.13.
empezarDespués	matriz|objeto	Especifica el punto de inicio lógico para el nuevo flujo de cambios. El campo _id en los documentos devueltos por el flujo de cambios puede usarse aquí. A diferencia de resumeAfter, esta opción puede utilizarse con un token de reanudación de un evento de "invalidación". Usar esta opción junto con resumeAfter o startAtOperationTime provocará un error del servidor. Las opciones son mutuamente excluyentes. Esta es una opción de la etapa de canalización $changeStream. Nuevo en la versión 1.5.
iniciarEnTiempoDeOperación	MongoDB\BSON\TimestampInterface	Si se especifica, el flujo de cambios solo proporcionará los cambios ocurridos en la fecha y hora especificadas o después. De forma predeterminada, se usará el valor operationTime devuelto por el comando aggregate inicial, si está disponible. Usar esta opción junto con resumeAfter o startAfter provocará un error del servidor. Las opciones son mutuamente excluyentes. Para usar esta opción, debe conectarse a MongoDB 6.0 o una versión posterior. Si está conectado a una versión anterior, el servidor devuelve una excepción durante la ejecución. Esta es una opción de la etapa de canalización $changeStream.
typeMap	arreglo	El mapa de tipos que se aplica a los cursores y que determina cómo se convierten los documentos BSON a valores PHP. El valor predeterminado es el mapa de tipos de la base de datos.

Return Values

Un objeto que permite la iteración de eventos en el flujo de cambios a través de MongoDB\ChangeStream la interfaz Iterator.

Errores/Excepciones

MongoDB\Exception\UnexpectedValueException si la respuesta del comando del servidor era incorrecta.

MongoDB\Exception\UnsupportedException si se utilizan opciones que no son compatibles con el servidor seleccionado (porcollation readConcernwriteConcernejemplo,,,).

MongoDB\Exception\InvalidArgumentException para errores relacionados con el análisis de parámetros u opciones.

MongoDB\Driver\Exception\RuntimeException para otros errores en el nivel de extensión (por ejemplo, errores de conexión).

Ejemplos

Este ejemplo informa eventos mientras se itera un flujo de cambios.

<?php
$uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
$database = (new MongoDB\Client($uri))->test;
$changeStream = $database->watch();
for ($changeStream->rewind(); true; $changeStream->next()) {
    if ( ! $changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    if ($event['operationType'] === 'invalidate') {
        break;
    }
    $ns = sprintf('%s.%s', $event['ns']['db'], $event['ns']['coll']);
    $id = json_encode($event['documentKey']['_id']);
    switch ($event['operationType']) {
        case 'delete':
            printf("Deleted document in %s with _id: %s\n\n", $ns, $id);
            break;
        case 'insert':
            printf("Inserted new document in %s\n", $ns);
            echo json_encode($event['fullDocument']), "\n\n";
            break;
        case 'replace':
            printf("Replaced new document in %s with _id: %s\n", $ns, $id);
            echo json_encode($event['fullDocument']), "\n\n";
            break;
        case 'update':
            printf("Updated document in %s with _id: %s\n", $ns, $id);
            echo json_encode($event['updateDescription']), "\n\n";
            break;
    }
}

Suponiendo que se insertó, actualizó y eliminó un documento mientras el script anterior iteraba el flujo de cambios, el resultado sería similar a lo siguiente:

Inserted new document in test.inventory
{"_id":{"$oid":"5a81fc0d6118fd1af1790d32"},"name":"Widget","quantity":5}
Updated document in test.inventory with _id: {"$oid":"5a81fc0d6118fd1af1790d32"}
{"updatedFields":{"quantity":4},"removedFields":[]}
Deleted document in test.inventory with _id: {"$oid":"5a81fc0d6118fd1af1790d32"}

Ver también

• MongoDB\Collection::watch()

• MongoDB\Client::watch()

• Documentación de lacanalización de agregación en el Manual de MongoDB

• Documentación de flujos de cambios en el manual de MongoDB

• Documentación de eventos de cambio en el manual de MongoDB