Monitorar alterações de dados
Nesta página
Visão geral
Neste guia, você pode aprender a usar o driver Kotlin Sync para monitorar um change stream, permitindo que você visualize as alterações em tempo real no seu banco de dados de dados. Um change stream é uma funcionalidade do MongoDB Server que publica alterações de dados em uma collection, banco de dados de dados ou sistema. Seu aplicação pode se inscrever em um change stream e usar eventos para executar outras ações.
Dados de amostra
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 saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o guia Iniciar com Atlas .
A seguinte classe de dados Kotlin modela os documentos nesta coleção:
data class Restaurant( val name: String, val cuisine: String, )
Abrir um fluxo de alterações
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()
em instâncias das seguintes classes:
MongoClient
: Para monitorar todas as alterações no sistema MongoDBMongoDatabase
: Para monitorar alterações em todas as coleções no banco de dadosMongoCollection
: Para monitorar alterações na coleção
Abrir um exemplo de change stream
O exemplo a seguir abre um fluxo de alteração na collection restaurants
e imprime as alterações conforme elas ocorrem:
collection.watch().forEach { change -> println(change) }
Para começar a observar as alterações, execute o aplicação. Em seguida, em um aplicação ou shell separado, execute uma operação de gravação na coleção restaurants
. O exemplo a seguir atualiza um documento no qual o valor de name
é "Blarney Castle"
:
val filter = Filters.eq(Restaurant::name.name, "Blarney Castle") val update = Updates.set(Restaurant::cuisine.name, "Irish") val result = collection.updateOne(filter, update)
Quando você atualiza a coleção, o aplicativo de fluxo de alterações imprime a alteração conforme ela ocorre. O evento de alteração impresso é semelhante ao seguinte:
{ "_id": { ... }, "operationType": "update", "clusterTime": { ... }, "ns": { "db": "sample_restaurants", "coll": "restaurants" }, "updateDescription": { "updatedFields": { "cuisine": "Irish" }, "removedFields": [], "truncatedArrays": [] } ... }
Modificar a saída change stream
Você pode passar o parâmetro pipeline
para o método watch()
para modificar a saída do change stream. Esse parâmetro permite que você observe somente eventos de alteração especificados. Formate o parâmetro como uma lista de objetos que cada um representa um estágio de agregação .
Você pode especificar os seguintes estágios no parâmetro pipeline
:
$addFields
$match
$project
$replaceRoot
$replaceWith
$redact
$set
$unset
Exemplo de eventos específicos da correspondência
O exemplo a seguir usa o parâmetro pipeline
que inclui um $match
para abrir um fluxo de alteração que apenas registra operações de atualização:
val pipeline = listOf( Aggregates.match(Filters.eq("operationType", "update")) ) collection.watch(pipeline).forEach { change -> println(change) }
Para saber mais sobre como modificar a saída do change stream, consulte a seção Modificar a saída do change stream no manual do MongoDB Server .
Modificar comportamento do watch()
Você pode modificar o watch()
encadeando métodos ao objeto ChangeStreamIterable
retornado pela chamada de método watch()
. Se você não especificar nenhuma opção, o driver não personalizará a operação.
A tabela a seguir descreve métodos que você pode usar para personalizar o comportamento do watch()
:
Método | Descrição |
---|---|
batchSize() | Sets the number of documents to return per batch. |
collation() | Specifies the kind of language collation to use when sorting
results. For more information, see Collation
in the MongoDB Server manual. |
comment() | Specifies a comment to attach to the operation. |
fullDocument() | Sets the fullDocument value. To learn more, see the
Include Pre-Images and Post-Images section of this document. |
fullDocumentBeforeChange() | Sets the fullDocumentBeforeChange value. To learn more, see the
Include Pre-Images and Post-Images section of this document. |
maxAwaitTime() | Sets the maximum await execution time on the server for this operation, in
milliseconds. |
Para obter uma lista completa de métodos que você pode usar para configurar o watch()
método, consulte a documentação da API ChangeStreamIterable.
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 o delta dos campos modificados por essa operação. Para ver o documento completo antes ou depois de uma alteração, encadeie os métodos fullDocumentBeforeChange()
ou fullDocument()
ao método watch()
.
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, passe uma das seguintes opções para o método fullDocumentBeforeChange()
:
FullDocumentBeforeChange.WHEN_AVAILABLE
: 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.FullDocumentBeforeChange.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, passe uma das seguintes opções para o método fullDocument()
:
FullDocument.UPDATE_LOOKUP
: o evento de alteração inclui uma cópia de todo o documento alterado de algum tempo após a alteração.FullDocument.WHEN_AVAILABLE
: 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.FullDocument.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 nos resultados especificando o parâmetro fullDocument
:
collection.watch().fullDocument(FullDocument.UPDATE_LOOKUP).forEach { change -> println("Received a change: $change") }
Com o aplicativo 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 seguinte:
ChangeStreamDocument{ operationType=update, resumeToken={"_data": "..."}, namespace=sample_restaurants.restaurants, destinationNamespace=null, fullDocument=Restaurant(name=Blarney Castle, cuisine=Irish), fullDocumentBeforeChange=null, documentKey={"_id": {"$oid": "..."}}, clusterTime=Timestamp{value=..., seconds=..., inc=...}, updateDescription=UpdateDescription{removedFields=[], updatedFields={"cuisine": "Irish"}, truncatedArrays=[], disambiguatedPaths=null}, txnNumber=null, lsid=null, splitEvent=null, wallTime=BsonDateTime{value=...}}
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: