db.watch()

Definição

db.watch( pipeline, options )

Somente para conjuntos de réplica e clusters fragmentados

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

Parâmetro	Tipo	Descrição
pipeline	variedade	Opcional. Um pipeline de agregação que consiste em um ou mais dos seguintes estágios de agregação : $addFields $match $project $replaceRoot $replaceWith (Disponível a partir do MongoDB 4.2) $redact $set (Disponível a partir do MongoDB 4.2) $unset (Disponível a partir do MongoDB 4.2) 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. Direciona db.watch() para tentar retomar as notificações a partir da operação especificada no token de retomada. Cada documento de evento de fluxo de alteração inclui um token de currículo como o campo _id. Passe todo o _id campo do documento do evento de alteração que representa a operação que você deseja retomar depois. resumeAfter é mutuamente exclusivo com startAfter e startAtOperationTime.
startAfter	documento	Opcional. Direciona db.watch() para tentar iniciar um novo fluxo de alterações após a operação especificada no token de retomada. Permite que as notificações sejam retomadas após um evento de invalidação. Cada documento de evento de fluxo de alteração inclui um token de currículo como o campo _id. Passe todo o _id campo do documento do evento de alteração que representa a operação que você deseja retomar depois. startAfter é mutuamente exclusivo com resumeAfter e startAtOperationTime. Novidades na versão 4.2.
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() a procurar a versão mais atual confirmada por maioria do documento atualizado. db.watch() retorna um campo fullDocument com a pesquisa do 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

• Você não pode 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() para um banco de dados que não existe. No entanto, assim que o banco de dados for criado e você soltar o banco de dados, o cursor de fluxo de alteração 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.