MongoDB\Collection::watch()

Nesta página

Definição

Parâmetros
Return Values
Erros/exceções
Exemplos
Veja também

Novidade na versão 1.3.

Definição

MongoDB\Collection::watch()

Executa uma operação dechange stream na collection. O fluxo de alterações pode ser observado para alterações no nível da coleção.

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

Parâmetros

$pipeline : array|object

O pipeline de estágios a ser anexado a um estágio $changeStream inicial.

$options : array

Uma array especificando as opções desejadas.

Nome	Tipo	Descrição
batchSize	inteiro	Especifica o tamanho do lote para o cursor, que se aplicará ao comando `aggregate` inicial e quaisquer comandos `getMore` subsequentes. Isso determina o número máximo de eventos de alteração para retornar em cada resposta do servidor. Independentemente da opção `batchSize`, a resposta inicial do comando `aggregate` para um change stream geralmente não inclui nenhum documento, a menos que outra opção seja usada para configurar seu ponto de partida (por exemplo `startAfter`).
Codec	MongoDB\Codec\DocumentCodec	Ocodec a ser usado para codificar ou decodificar documentos. Esta opção é mutuamente exclusiva com a opção `typeMap` . O padrão é o codec da coleção. A herança de uma opção `codec` padrão tem precedência sobre a da opção `typeMap`. Novidade na versão 1.17.
agrupamento	array\|object	A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de string , como regras para letras maiúsculas e marcas de acento. Ao especificar agrupamento, o campo `locale` é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento. A partir do MongoDB 4.2, o padrão é comparação binária simples se for omitido. Nas versões anteriores, o change stream aberto em uma única collection herdariam o agrupamento padrão da collection.
comment	misto	Permite ao usuário especificar um comentário arbitrário para ajudar a rastrear a operação por meio do profiler de banco de dados, da saída currentOp e dos registros. O comentário pode ser qualquer tipo de BSON válido desde o MongoDB 4.4. As versões anteriores do servidor suportam apenas valores de string. Novidade na versão 1.13.
Documento completo	string	Determina como o campo de resposta `fullDocument` será preenchido para operações de atualização. Por padrão, os change stream retornam apenas o delta dos campo (por meio de um campo `updateDescription` ) para operações de atualização e `fullDocument` é omitido. As operações de inserção e substituição sempre incluem o campo `fullDocument` . As operações de exclusão omitem o campo, pois o documento não existe mais. Especifique "updateLookup" para retornar a versão atual do documento atualizado com o compromisso da maioria. O MongoDB 6.0+ permite retornar a pós-imagem do documento modificado se a collection tiver `changeStreamPreAndPostImages` habilitado. Especifique "whenAvailable" para retornar a pós-imagem, se disponível, ou um valor nulo, se não. Especifique "obrigatório" para retornar a pós-imagem, se disponível, ou gere um erro, se não. Os seguintes valores são aceitos: `MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP` `MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE` `MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED` Esta é uma opção do estágio do pipeline `$changeStream` .
fullDocumentBeforeChange	string	Determina como o campo de resposta `fullDocumentBeforeChange` será preenchido. Por padrão, o campo é omitido. O MongoDB 6.0+ permite retornar a pré-imagem do documento modificado se a collection tiver `changeStreamPreAndPostImages` habilitado. Especifique "whenAvailable" para retornar a pré-imagem, se disponível, ou um valor nulo, se não. Especifique "obrigatório" para retornar a pré-imagem, se disponível, ou gere um erro, se não. Os seguintes valores são aceitos: `MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE` `MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED` Esta é uma opção do estágio do pipeline `$changeStream` . Novidade na versão 1.13.
maxAwaitTimeMS	inteiro	Inteiro positivo que indica o limite de tempo em milissegundos para o servidor bloquear uma operação getMore se nenhum dado estiver disponível.
readConcern	MongoDB\Driver\ReadConcern	Preocupação de leitura a ser usada para a operação. O padrão é a preocupação de leitura da coleção.
readPreference	MongoDB\Driver\ReadPreference	Preferência de leitura a ser usada na operação. O padrão é a preferência de leitura da coleção. Isso é usado tanto para a agregação inicial do change stream quanto para a seleção do servidor durante uma retomada automática.
resumeAfter	array\|object	Especifica o ponto de partida lógico para o novo change stream. O campo `_id` em documentos retornados pelo change stream pode ser usado aqui. Usar essa opção em conjunto com `startAfter` e/ou `startAtOperationTime` resultará em um erro no servidor. As opções são mutuamente exclusivas. Esta é uma opção do estágio do pipeline `$changeStream` .
session	MongoDB\Driver\Session	Sessão do cliente a ser associada à operação.
showExpandedEvents	booleano	Se verdadeiro, instrui o servidor a incluir eventos DDL adicionais no change stream. Os eventos adicionais que podem ser incluídos são: `createIndexes` `dropIndexes` `modify` `create` `shardCollection` `reshardCollection` (servidor 6.1+) `refineCollectionShardKey` (servidor 6.1+) Isto não é suportado para versões de servidor anteriores à 6.0 e resultará em uma exceção no tempo de execução se utilizado. Esta é uma opção do estágio do pipeline `$changeStream` . Novidade na versão 1.13.
startAfter	array\|object	Especifica o ponto de partida lógico para o novo change stream. O campo `_id` em documentos retornados pelo change stream pode ser usado aqui. Ao contrário `resumeAfter`, essa opção pode ser usada com um token de retomada de um evento de "invalidação". Usar essa opção em conjunto com `resumeAfter` e/ou `startAtOperationTime` resultará em um erro no servidor. As opções são mutuamente exclusivas. Isto não é suportado para versões de servidor anteriores à 4.2 e resultará em uma exceção no tempo de execução se utilizado. Esta é uma opção do estágio do pipeline `$changeStream` . Novidade na versão 1.5.
startAtOperationTime	MongoDB\BSON\TimestampInterface	Se especificado, o change stream fornecerá apenas as alterações que ocorreram no ou após o registro de data/hora especificado. As respostas de comando de um servidor MongoDB 4.0+ incluem um `operationTime` que pode ser utilizado aqui. Por padrão, o `operationTime` retornado pelo comando `aggregate` inicial será utilizado se disponível. Usar essa opção em conjunto com `resumeAfter` e/ou `startAfter` resultará em um erro no servidor. As opções são mutuamente exclusivas. Isto não é suportado para versões de servidor anteriores à 4.0 e resultará em uma exceção no tempo de execução se utilizado. Esta é uma opção do estágio do pipeline `$changeStream` .
typeMap	array	O mapa de tipos para aplicar aos cursores, que determina como os documentos BSON são convertidos para valores PHP. O padrão é o mapa de tipos da coleção.

Return Values

Um objeto , que permite a iteração de MongoDB\ChangeStream eventos no fluxo de alterações por meio do Iterador interface.

Erros/exceções

MongoDB\Exception\UnexpectedValueException se a resposta do comando do servidor estiver malformada.

MongoDB\Exception\UnsupportedException se as opções forem usadas e não aceitas pelo servidor selecionado (p. ex., collation, readConcern, writeConcern).

MongoDB\Exception\InvalidArgumentException para erros relacionados à análise de parâmetros ou opções.

MongoDB\Driver\Exception\RuntimeException para outros erros no nível da extensão (por exemplo erros de conexão).

Exemplos

Este exemplo relata eventos enquanto itera um change stream.

<?php
$uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
$collection = (new MongoDB\Client($uri))->test->inventory;
$changeStream = $collection->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;
    }
}

Supondo que um documento tenha sido inserido, atualizado e excluído enquanto o script acima iterava o change stream, a saída seria semelhante a:

Inserted new document in test.user
{"_id":{"$oid":"5b329c4874083047cc05e60a"},"username":"bob"}
Inserted new document in test.products
{"_id":{"$oid":"5b329c4d74083047cc05e60b"},"name":"Widget","quantity":5}
Updated document in test.user with _id: {"$oid":"5b329a4f74083047cc05e603"}
{"updatedFields":{"username":"robert"},"removedFields":[]}

Veja também

MongoDB\Client::watch()
MongoDB\Database::watch()
Documentação do aggregation pipeline no Manual do MongoDB
Documentação do Change Streams no Manual do MongoDB
Documentação de eventos de alterações no manual do MongoDB

Voltar

updateSearchIndex()

withOptions()