Menu Docs
Página inicial do Docs
/ / /
Driver C++
/

Monitorar alterações de dados

Nesta página

  • Visão geral
  • Dados de amostra
  • Abrir um fluxo de alterações
  • Modificar a saída change stream
  • Modificar Comportamento do watch()
  • Incluir pré-imagens e pós-imagens
  • Informações adicionais
  • Documentação da API

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

Ao utilizar o driver C++ , você pode instanciar um mongocxx::change_stream para monitorar alterações de dados.

Os exemplos neste guia utilizam a coleção do restaurants no banco de dados de dados do sample_restaurants a partir dos conjuntos de dados de amostra do Atlas. Para acessar essa coleção a partir do seu aplicação C++ , instancie um mongocxx::client que se conecte a um Atlas cluster e atribua os seguintes valores às suas variáveis db e collection :

auto db = client["sample_restaurants"];
auto collection = db["restaurants"];

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

Para abrir um fluxo de alteração, chame o método watch() . A instância na qual você chama o método watch() determina o escopo de eventos que o change stream escuta. Você pode chamar o método watch() nas seguintes classes:

  • mongocxx::client: Monitorar todas as alterações na implantação do MongoDB

  • mongocxx::database: Monitorar alterações em todas as collections no banco de banco de dados

  • mongocxx::collection: Monitorar alterações na coleção

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

auto stream = collection.watch();
while (true) {
for (const auto& event : stream) {
std::cout << bsoncxx::to_json(event) << std::endl;
}
}

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

auto result = collection.update_one(make_document(kvp("name", "Blarney Castle")),
make_document(kvp("$set",
make_document(kvp("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" :
{ "$timestamp" : { ... }, "wallTime" : { "$date" : ... }, "ns" :
{ "db" : "sample_restaurants", "coll" : "restaurants" }, "documentKey" :
{ "_id" : { "$oid" : "..." } }, "updateDescription" : { "updatedFields" :
{ "cuisine" : "Irish" }, "removedFields" : [ ], "truncatedArrays" : [ ] } }

Você pode passar uma instância mongocxx::pipeline como argumento para o método watch() para modificar a saída do fluxo de alteração. A lista a seguir inclui alguns dos campos mongocxx::pipeline que você pode definir chamando seus métodos de configuração correspondentes:

  • add_fields: adiciona novos campos aos documentos

  • match: filtra os documentos

  • project: projeta um subconjunto dos campos do documento

  • redact: restringe o conteúdo dos documentos

  • group: Agrupa documentos por uma expressão especificada

  • merge: gera os resultados para uma coleção

Dica

O exemplo a seguir define o campo match de uma instância mongocxx::pipeline e, em seguida, passa o pipeline para o método watch() . Isso instrui o método watch() a gerar somente operações de atualização:

mongocxx::pipeline pipeline;
pipeline.match(make_document(kvp("operationType", "update")));
auto stream = collection.watch(pipeline);
while (true) {
for (const auto& event : stream) {
std::cout << bsoncxx::to_json(event) << std::endl;
}
}

Você pode modificar o comportamento do método watch() passando uma instância da classe mongocxx::options::change_stream como parâmetro. A tabela seguinte descreve os campos que você pode definir em uma instância do mongocxx::options::change_stream :

Campo
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 Include Pre-Images and Post-Images.

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

Instructs watch() to resume returning changes after the operation specified in the resume token.
Each change stream event document includes a resume token as the _id field. Pass the entire _id field of the change event document that represents the operation you want to resume after.
resume_after is mutually exclusive with start_after and start_at_operation_time.

start_after

Instructs watch() to start a new change stream after the operation specified in the resume token. This field allows notifications to resume after an invalidate event.
Each change stream event document includes a resume token as the _id field. Pass the entire _id field of the change event document that represents the operation you want to resume after.
start_after is mutually exclusive with resume_after and start_at_operation_time.

start_at_operation_time

Instructs watch() to return only events that occur after the specified timestamp.
start_at_operation_time is mutually exclusive with resume_after and start_after.

max_await_time_ms

Sets the maximum amount of time, in milliseconds, the server waits for new data changes to report to the change stream cursor before returning an empty batch. Defaults to 1000 milliseconds.

batch_size

Sets the maximum number of change events to return in each batch of the response from the MongoDB cluster.

collation

Sets the collation to use for the change stream cursor.

comment

Attaches a comment to the operation.

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 o delta dos campos modificados por essa operação. Para ver o documento completo antes ou depois de uma alteração, especifique os campos full_document_before_change ou full_document de uma instância do mongocxx::options::change_stream .

A pré-imagem é a versão completa de um documento antes de uma alteração. Para incluir a pré-imagem no evento de fluxo de alteração, defina o campo full_document_before_change para uma das seguintes strings:

  • "whenAvailable": o evento de alteração inclui uma pré-imagem do documento modificado para eventos de alteração somente se a pré-imagem estiver disponível.

  • "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 driver gerará um erro.

A pós-imagem é a versão completa de um documento após uma alteração. Para incluir a pós-imagem no evento de fluxo de alteração, defina o campo full_document para uma das seguintes strings:

  • "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 somente se a pós-imagem estiver disponível.

  • "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 driver gerará um erro.

O exemplo a seguir chama o método watch() em uma coleção e inclui a pós-imagem de documentos atualizados definindo o campo full_document de uma instância mongocxx::options::change_stream :

mongocxx::options::change_stream opts;
opts.full_document("updateLookup");
auto stream = collection.watch(opts);
while (true) {
for (const auto& event : stream) {
std::cout << bsoncxx::to_json(event) << std::endl;
}
}

Com o aplicação change stream em execução, atualizar um documento na collection restaurants usando o exemplo de atualização anterior imprime um evento de alteração semelhante ao código a seguir:

{ "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" :
{ "$timestamp" : { ... } }, "wallTime" : { "$date" : ... },
"fullDocument" : { "_id" : { "$oid" : "..." }, "address" : { "building" : "202-24",
"coord" : [ -73.925044200000002093, 40.559546199999999772 ], "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" : { "$oid" : "..." } }, "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 .

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

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

Voltar

Cursors