Menu Docs
Página inicial do Docs
/ / /
Manual da Biblioteca PHP
/ /

MongoDB\Database::watch()

Nesta página

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

Novidade na versão 1.4.

MongoDB\Database::watch()

Executa uma operação dechange stream do no banco de dados. O change stream pode ser observado quanto a alterações no nível do banco de dados.

function watch(
array $pipeline = [],
array $options = []
): MongoDB\ChangeStream
$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 .

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.

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

Preocupação de leitura a ser usada para a operação. O padrão é a preocupação de leitura do banco de dados.

readPreference

Preferência de leitura a ser usada na operação. O padrão é a preferência de leitura do banco de dados.

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

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

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 aplicar aos cursores, o que determina como os documentos BSON são convertidos em valores PHP. O padrão é o mapa de tipos do banco de dados.

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

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).

Este exemplo relata eventos enquanto itera um change stream.

<?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;
}
}

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.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"}

Voltar

selectGridFSBucket()