Monitorar alterações de dados

Visão geral

Neste guia, você pode aprender como usar um fluxo de alterações para monitorar alterações em tempo real em seus dados. Um change stream é uma funcionalidade do MongoDB Server que permite que seu aplicação se inscreva em alterações de dados em uma collection, banco de dados de dados ou sistema.

Ao usar o driver Ruby, você pode chamar o método watch para retornar um objeto Mongo::Collection::View::ChangeStream. Em seguida, você pode iterar seu conteúdo para monitorar as alterações de dados, como atualizações, inserções e exclusões.

Dados de amostra

Os exemplos neste guia utilizam a restaurants coleção do sample_restaurants no banco de dados do a partir dos conjuntos de dados de amostra do Atlas . Para acessar essa coleção a partir do seu aplicação Ruby, crie um Mongo::Client objeto que se conecte a um Atlas cluster e atribua os seguintes valores às suas variáveis database collection e:

database = client.use('sample_restaurants')
collection = database[:restaurants]

Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o guia Iniciar com Atlas .

Abrir um fluxo de alterações

Para abrir um fluxo de alteração, chame o método watch. O objeto no qual você chama o método watch determina o escopo de eventos que o change stream monitora. Você pode chamar o método watch nos seguintes objetos

Mongo::Client: monitora alterações em todas as collections em todos os bancos de dados em um sistema, excluindo as collections do sistema ou as collections nos admin local config bancos de dados, e
Mongo::Database: Monitora alterações em todas as coleções em um banco de dados
Mongo::Collection: monitora alterações em uma coleção

O exemplo a seguir abre um fluxo de alteração na collection restaurants e gera as alterações conforme elas ocorrem:

stream = collection.watch
stream.each do |doc|
  puts doc
  break if doc['operationType'] == 'invalidate'
end

Para começar a observar as alterações, execute o código anterior. Em seguida, em uma shell separada, modifique a coleção restaurants . O exemplo a seguir atualiza um documento que tem um valor de campo name de 'Blarney Castle':

collection.update_one(
  { 'name' => 'Blarney Castle' },
  { '$set' => { 'cuisine' => 'Irish' } }
)

Quando você atualiza a coleção, o aplicação de fluxo de alterações imprime a alteração conforme ela ocorre. O evento de alteração impresso se assemelha à seguinte saída:

{"_id"=>{"_data"=>"..."}, "operationType"=>"update", "clusterTime"=>#<...>,
"ns"=>{"db"=>"sample_restaurants", "coll"=>"restaurants"}, "documentKey"=>
{"_id"=>BSON::ObjectId('...')}, "updateDescription"=>{"updatedFields"=>
{"cuisine"=>"Irish"}, "removedFields"=>[], "truncatedArrays"=>[]}}

Modificar a saída change stream

Para modificar a saída do change stream, passe os estágios de pipeline em uma array como parâmetro para o método watch . Você pode incluir os seguintes estágios na array:

$addFields ou $set: adiciona novos campos aos documentos
$match: filtra os documentos
$project: projeta um subconjunto dos campos do documento
$replaceWith ou $replaceRoot: substitui o documento de entrada pelo documento especificado
$redact: restringe o conteúdo dos documentos
$unset: remove campos de documentos

O exemplo a seguir passa um pipeline que inclui o estágio $match para o método watch . Isso instrui o método watch a gerar eventos somente quando as operações de atualização ocorrerem:

pipeline = [{ '$match' => { 'operationType' => 'update' } }]
stream = collection.watch(pipeline)
stream.each do |doc|
  puts doc
  break if doc['operationType'] == 'invalidate'
end

Modificar comportamento do relógio

Para modificar o comportamento do método watch, você pode passar um hash de opções como parâmetro para watch. A tabela a seguir descreve algumas das opções que você pode definir:

Opção	Descrição
`full_document`	Specifies whether to show the full document after the change, rather than showing only the changes made to the document. To learn more about this option, see the Include Pre-Images and Post-Images section of this guide.
`full_document_before_change`	Specifies whether to show the full document as it was before the change, rather than showing only the changes made to the document. To learn more about this option, see Include Pre-Images and Post-Images.
`resume_after`	Specifies the logical starting point for the change stream. This option is mutually exclusive with `start_at_operation_time`.
`start_at_operation_time`	Instructs the change stream to only provide changes that occurred at or after the specified timestamp. This option is mutually exclusive with `resume_after`.
`collation`	Sets the collation to use for the change stream cursor.

Para obter uma lista completa das opções watch, consulte watch na documentação da API.

Incluir pré-imagens e pós-imagens

Importante

Você pode habilitar pré-imagens e pós-imagens em collections somente se seu sistema usar MongoDB v6.0 ou posterior.

Por padrão, quando você executa uma operação em uma collection, o evento de alteração correspondente inclui somente os campos modificados e seus valores antes e depois da operação.

Você pode instruir o watch método a retornar a pré-imagem do documento , a versão completa do documento antes das alterações, além dos campos modificados. Para incluir a pré-imagem no evento de fluxo de alteração, passe um hash de opções para watch que define a full_document_before_change opção. Você pode definir esta opção para os seguintes valores de string:

'whenAvailable': o evento de alteração inclui uma pré-imagem do documento modificado para eventos de alteração. Se a pré-imagem não estiver disponível, esse campo de evento de alteração terá um valor nil .
'required': o evento de alteração inclui uma pré-imagem do documento modificado para eventos de alteração. Se a pré-imagem não estiver disponível, o servidor gerará um erro.
'off': (Padrão) O evento de alteração não inclui uma pré-imagem do documento modificado.

Você também pode instruir o método watch a retornar a pós-imagem do documento, a versão completa do documento após as alterações, além dos campos modificados. Para incluir a pós-imagem no evento de fluxo de alteração, passe um hash de opções para watch que define a opção full_document. Você pode definir esta opção para os seguintes valores de string:

'updateLookup': o evento de alteração inclui uma cópia de todo o documento alterado de algum tempo após a alteração.
'whenAvailable': o evento de alteração inclui uma pós-imagem do documento modificado para eventos de alteração. Se a pós-imagem não estiver disponível, esse campo de evento de alteração terá um valor nil .
'required': o evento de alteração inclui uma pós-imagem do documento modificado para eventos de alteração. Se a pós-imagem não estiver disponível, o servidor gerará um erro.
'default': (Padrão) O evento de alteração não inclui uma pós-imagem do documento modificado.

O exemplo a seguir chama o método watch em uma coleção e inclui a pós-imagem de documentos atualizados definindo a opção full_document :

options = { full_document: 'updateLookup' }
stream = collection.watch([], options)
stream.each do |doc|
  puts doc
  break if doc['operationType'] == 'invalidate'
end

Com o aplicação de fluxo de alterações em execução em um shell separado, atualizar um documento na coleção restaurants usando o exemplo de atualização anterior imprime um evento de alteração semelhante à seguinte saída:

{"_id"=>{"_data"=>"..."}, "operationType"=>"update", "clusterTime"=>
#<...1>, "wallTime"=>..., "fullDocument"=>{"_id"=>BSON::ObjectId('...'),
"address"=>{"building"=>"202-24", "coord"=>[-73.9250442, 40.5595462],
"street"=>"Rockaway Point Boulevard", "zipcode"=>"11697"},
"borough"=>"Queens", "cuisine"=>"Irish", "grades"=>[...],
"name"=>"Blarney Castle", "restaurant_id"=>"40366356"}, "ns"=>
{"db"=>"sample_restaurants", "coll"=>"restaurants"}, "documentKey"=>
{"_id"=>BSON::ObjectId('...')}, "updateDescription"=>{"updatedFields"=>
{"cuisine"=>"Irish"}, "removedFields"=>[], "truncatedArrays"=>[]}}

Dica

Para saber mais sobre pré e pós-imagens, consulte Change Streams com pré e pós-imagens de documentos no manual do MongoDB Server .

Informações adicionais

Para saber mais sobre fluxos de alterações, consulte Change Streams de alterações no manual do MongoDB Server .

Documentação da API

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Cursors

Agrupamentos