Monitore dados com change streams

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 a biblioteca PHP do MongoDB , você pode chamar o método watch() para retornar uma instância de MongoDB\ChangeStream. Em seguida, você pode iterar por meio da instância MongoDB\ChangeStream para monitorar alterações de dados, como atualizações, inserções e exclusõ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 acessar essa coleção a partir do seu aplicação PHP , instancie um MongoDB\Client que se conecte a um Atlas cluster e atribua o seguinte valor à sua variável $collection :

$collection = $client->sample_restaurants->restaurants;

Dica

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

Alguns exemplos utilizam a função toJSON() para representar eventos de alteração, que são documentos BSON, como Extended JSON. Para usar essa função, cole o seguinte código no arquivo do seu aplicação :

function toJSON(object $document): string
{
    return MongoDB\BSON\Document::fromPHP($document)->toRelaxedExtendedJSON();
}

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 monitora. Você pode chamar o método watch() em instâncias das seguintes classes:

MongoDB\Client: Monitorar todas as alterações na implantação do MongoDB
MongoDB\Database: Monitorar alterações em todas as collections no banco de banco de dados
MongoDB\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:

$changeStream = $collection->watch();
$changeStream->rewind();
while (true) {
    $changeStream->next();
    if ($changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    echo toJSON($event), PHP_EOL;
    if ($changeStream->current()['operationType'] === 'invalidate') {
        break;
    }
}

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':

$result = $collection->updateOne(
    ['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" :
{ "$timestamp" : { ... } }, "wallTime" : { "$date" : "..." }, "ns" : { "db" :
"sample_restaurants", "coll" : "restaurants" }, "documentKey" : { "_id" :
{ "$oid" : "..." } }, "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']]];
$changeStream = $collection->watch($pipeline);
$changeStream->rewind();
while (true) {
    $changeStream->next();
    if ($changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    echo toJSON($event), PHP_EOL;
    if ($changeStream->current()['operationType'] === 'invalidate') {
        break;
    }
}

Dica

Operações com construtores

Você pode usar um padrão de construtor para criar o pipeline do fluxo de alterações. Para saber mais, consulte o guia Operações com a Builders.

Modificar `watch()` Comportamento do

Para modificar o comportamento do método watch() , você pode passar uma array de opções como parâmetro para watch(). A tabela a seguir descreve opções úteis que você pode definir na array:

Opção	Descrição
`fullDocument`	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.
`fullDocumentBeforeChange`	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.
`startAfter`	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. This option is mutually exclusive with `resumeAfter` and `startAtOperationTime`.
`startAtOperationTime`	Instructs the change stream to only provide changes that occurred at or after the specified timestamp. This option is mutually exclusive with `startAfter` and `resumeAfter`.
`collation`	Sets the collation to use for the change stream cursor. To learn more, see the Collation section of this page.

Para obter uma lista completa das opções watch() , consulte MongoDB\Collection::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 o delta dos campos modificados por essa operação. Para ver o documento completo antes ou depois de uma alteração, especifique as opções fullDocumentBeforeChange ou fullDocument em um parâmetro de array para 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, defina a opção fullDocumentBeforeChange para um dos seguintes valores:

MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE: 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 null .
MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_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.

A pós-imagem é a versão completa de um documento após uma alteração. Para incluir a pós-imagem na alteração de evento de fluxo, defina a opção fullDocument para um dos seguintes valores:

MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP: o evento de alteração inclui uma cópia de todo o documento alterado de algum tempo após a alteração.
MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE: 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 null .
MongoDB\Operation\Watch::FULL_DOCUMENT_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.

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 fullDocument :

$options = ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP];
$changeStream = $collection->watch([], $options);
$changeStream->rewind();
while (true) {
    $changeStream->next();
    if ($changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    echo toJSON($event), PHP_EOL;
    if ($changeStream->current()['operationType'] === 'invalidate') {
        break;
    }
}

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" :
{ "$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 .

Agrupamentos

Para especificar um agrupamento para sua operação, passe um parâmetro de array $options que defina a opção collation para o método de operação. Atribua a opção collation a uma array que configure as regras de agrupamento.

A tabela a seguir descreve os campos que você pode definir para configurar o agrupamento:

Campo	Descrição
`locale`	(Required) Specifies the International Components for Unicode (ICU) locale. For a list of supported locales, see Collation Locales and Default Parameters in the MongoDB Server manual. Data Type: `string`
`caseLevel`	(Optional) Specifies whether to include case comparison. When set to `true`, the comparison behavior depends on the value of the `strength` field: - If `strength` is `1`, the PHP library compares base characters and case. - If `strength` is `2`, the PHP library compares base characters, diacritics, other secondary differences, and case. - If `strength` is any other value, this field is ignored. When set to `false`, the PHP library doesn't include case comparison at strength level `1` or `2`. Data Type: `bool` Default: `false`
`caseFirst`	(Optional) Specifies the sort order of case differences during tertiary level comparisons. Data Type: `string` Default: `"off"`
`strength`	(Optional) Specifies the level of comparison to perform, as defined in the ICU documentation. Data Type: `int` Default: `3`
`numericOrdering`	(Optional) Specifies whether the driver compares numeric strings as numbers. If set to `true`, the PHP library compares numeric strings as numbers. For example, when comparing the strings "10" and "2", the library uses the strings' numeric values and treats "10" as greater than "2". If set to `false`, the PHP library compares numeric strings as strings. For example, when comparing the strings "10" and "2", the library compares one character at a time and treats "10" as less than "2". For more information, see Collation Restrictions in the MongoDB Server manual. Data Type: `bool` Default: `false`
`alternate`	(Optional) Specifies whether the library considers whitespace and punctuation as base characters for comparison purposes. Data Type: `string` Default: `"non-ignorable"`
`maxVariable`	(Optional) Specifies which characters the library considers ignorable when the `alternate` field is set to `"shifted"`. Data Type: `string` Default: `"punct"`
`backwards`	(Optional) Specifies whether strings containing diacritics sort from the back of the string to the front. Data Type: `bool` Default: `false`

Para saber mais sobre agrupamento e os possíveis valores para cada campo, consulte a entrada de Agrupamento 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

Monitoramento

Exploração madeireira

Visão geral

Dados de amostra

Dica

Abrir um fluxo de alterações

Modificar a saída change stream

Dica

Operações com construtores

Modificar watch() Comportamento do

Incluir pré-imagens e pós-imagens

Importante

Dica

Agrupamentos

Informações adicionais

Documentação da API

Modificar `watch()` Comportamento do