db.watch()

Definição

db.watch( pipeline, options )

Somente para conjuntos de réplica e clusters fragmentados

Abre umcursor de fluxo de alteração para um banco de dados para relatar todas as suas coleções que não sejamsystem .

Parâmetro	Tipo	Descrição
pipeline	array	Opcional. Um pipeline de agregação que consiste em um ou mais dos seguintes estágios de agregação : $addFields $match $project $replaceRoot $replaceWith $redact $set $unset Especifique um pipeline para filtrar/modificar o resultado dos eventos de alteração. A partir do MongoDB 4.2, os fluxos de alteração lançarão uma exceção se o pipeline de agregação do fluxo de alterações modificar o campo _id de um evento.
options	documento	Opcional. Opções adicionais que modificam o comportamento do db.watch().

O documento options pode conter os seguintes campos e valores:

Campo	Tipo	Descrição
resumeAfter	documento	Opcional. Especifica um token de currículo como o ponto de partida lógico para o fluxo de alteração. Não pode ser usado para retomar o fluxo de alterações após um evento invalidate. resumeAfter é mutuamente exclusivo com startAfter e startAtOperationTime.
startAfter	documento	Opcional. Especifica um token de resumo como o ponto de partida lógico para o fluxo de alterações. Ao contrário de resumeAfter, startAfter pode retomar notificações após um evento invalidate criando um novo fluxo de alterações. startAfter é mutuamente exclusivo com resumeAfter e startAtOperationTime.
fullDocument	string	Opcional. Por padrão, db.watch() retorna o delta dos campos modificados por uma operação de atualização, em vez de todo o documento atualizado. Defina fullDocument como "updateLookup" para direcionar db.watch() para procurar a versão mais atual confirmada por maioria do documento atualizado. db.watch() retorna um campo fullDocument com a pesquisa de documento, além do delta updateDescription. A partir do MongoDB 6.0, você pode definir fullDocument como: "whenAvailable" para produzir o documento pós-imagem, se disponível, depois que o documento foi inserido, substituído ou atualizado. "required" para gerar a pós-imagem do documento após o documento ter sido inserido, substituído ou atualizado. Cria um erro se a pós-imagem não estiver disponível.
fullDocumentBeforeChange	string	Opcional. O padrão é "off". A partir do MongoDB 6.0, você pode usar o novo campo fullDocumentBeforeChange e defini-lo como: "whenAvailable" para gerar a pré-imagem do documento, se disponível, antes do documento ser substituído, atualizado ou excluído. "required" para gerar a pré-imagem do documento antes do documento ser substituído, atualizado ou excluído. Gera um erro se a pré-imagem não estiver disponível. "off" para suprimir a pré-imagem do documento. "off" é o padrão.
batchSize	int	Opcional. Especifica o número máximo de eventos de alteração a serem retornados em cada lote da resposta do cluster MongoDB. Tem a mesma funcionalidade que cursor.batchSize().
maxAwaitTimeMS	int	Opcional. A quantidade máxima de tempo em milissegundos que o servidor aguarda por novas alterações de dados para relatar ao cursor do fluxo de alterações antes de retornar um lote vazio. Padrão para 1000 milissegundos.
collation	documento	Opcional. Passe um documento de agrupamento para especificar um agrupamento para o cursor do change stream. Se omitido, o padrão é simple comparação binária.
startAtOperationTime	Timestamp	Opcional. O ponto de partida para o fluxo de alterações. Se o ponto de partida especificado estiver no passado, ele deverá estar no intervalo de tempo do oplog. Para verificar o intervalo de tempo do oplog, consulte rs.printReplicationInfo(). startAtOperationTime é mutuamente exclusivo com resumeAfter e startAfter.

Retorna:	Um cursor sobre os documentos do evento de alteração. Consulte Eventos de mudança para obter exemplos de documentos de eventos de mudança.

Dica

Veja também:

db.collection.watch() e a Mongo.watch()

Disponibilidade

Comportamento

• Não é possível executar db.watch() no banco de dados admin, local ou config.

• db.watch() notifica apenas sobre alterações de dados que persistiram para a maioria dos membros portadores de dados.

• O cursor do fluxo de alterações permanece aberto até que ocorra uma das seguintes situações:

  • O cursor está explicitamente fechado.

  • Ocorre um evento de invalidar; por exemplo, um drop de coleção ou renomear.

  • A conexão com a implantação do MongoDB fecha ou expira. Consulte Comportamentos do cursor para obter mais informações.

  • Se a implantação for um cluster fragmentado, uma remoção de fragmento pode fazer com que um cursor de fluxo de alteração aberto seja fechado e o cursor de fluxo de alterações fechado pode não ser totalmente retomável.

• Você pode executar o db.watch() em relação a um banco de dados que não existe. No entanto, assim que o banco de dados for criado e você descartar o banco de dados, o cursor do fluxo de alterações será fechado.

Controle de acesso

Ao executar com controle de acesso, o usuário deve ter as ações de privilégio do find e changeStream no recurso do banco de dados. Ou seja, um usuário deve ter uma função que conceda o seguinte privilégio:

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

O papel do read embutido fornece os privilégios apropriados.

Iteração do cursor

O MongoDB oferece várias maneiras de iterar em um cursor.

O método cursor.hasNext() bloqueia e aguarda o próximo evento. Para monitorar o cursor watchCursor e iterar sobre os eventos, use hasNext() assim:

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

O método cursor.tryNext() não está bloqueando. Para monitorar o cursor watchCursor e iterar sobre os eventos, use tryNext() assim:

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

Exemplo

A operação a seguir em mongosh abre um cursor de fluxo de alterações no banco de dados hr. O cursor retornado relata as alterações de dados em todas as coleções nãosystem nesse banco de dados.

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

Itere o cursor para verificar novos eventos. Use o método cursor.isClosed() com o método cursor.tryNext() para garantir que o loop só saia se o cursor do fluxo de alteração estiver fechado e não houver objetos restantes no lote mais recente:

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

Para obter a documentação completa sobre a saída do fluxo de alterações, consulte Eventos de alteração.