/ /

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 usam a collection restaurants no banco de dados sample_restaurants dos conjuntos de dados de amostra do Atlas. Para acessar essa coleção a partir do seu aplicação Ruby, crie um objeto Mongo::Client que se conecte a um Atlas cluster e atribua os seguintes valores às suas variáveis database e collection:

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

Para aprender a criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o Guia de Introdução do MongoDB.

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`	Especifica se o documento completo deve ser mostrado após a alteração, em vez de mostrar apenas as alterações feitas no documento. Para saber mais sobre essa opção, consulte a seção Incluir pré-imagens e pós-imagens deste guia.
`full_document_before_change`	Especifica se o documento completo deve ser mostrado como estava antes da alteração, em vez de mostrar apenas as alterações feitas no documento. Para saber mais sobre essa opção, consulte Incluir pré-imagens e pós-imagens.
`resume_after`	Especifica o ponto de partida lógico para o change stream. Esta opção é mutuamente exclusiva `start_at_operation_time` com.
`start_at_operation_time`	Instrui o change stream a fornecer apenas alterações que ocorreram no momento ou após o registro de data e hora especificado. Esta opção é mutuamente exclusiva `resume_after` com.
`collation`	Define o agrupamento a ser usado para o cursor do change stream.

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 método watch 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 opção full_document_before_change. 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

Exploração madeireira

Autenticação