$changeStream (estágio de agregação )

Esta versão da documentação foi arquivada e não é mais suportada. Para atualizar seu sistema do 6.0, consulte osprocedimentos de atualização do MongoDB 7.0 .

Definição

$changeStream

Gera um cursor deChange Stream em uma collection, banco de dados de dados ou cluster inteiro. Deve ser usado como o primeiro estágio em um agregação pipeline.

O estágio $changeStream tem a seguinte sintaxe:

{
  $changeStream: {
    allChangesForCluster: <boolean>,
    fullDocument: <string>,
    fullDocumentBeforeChange: <string>,
    resumeAfter: <document>
    showExpandedEvents: <boolean>,
    startAfter: <document>
    startAtOperationTime: <timestamp>
  }
}

Parâmetro	Descrição
`allChangesForCluster`	Opcional: define se o fluxo de alterações deve incluir todas as alterações no cluster. Só pode ser aberto no banco de dados `admin`.
`fullDocument`	Opcional: Especifica se as notificações de alteração incluem uma cópia do documento completo quando modificado por operações `update`. `default`: notificações de alteração não incluem o documento completo para operações de `update`. `required`: as notificações de alteração incluem uma cópia do documento modificado conforme ele apareceu imediatamente após a alteração. Se o documento não for encontrado, o change stream gerará um erro. Para usar esta opção, você deve primeiro utilizar o comando `collMod` para habilitar a opção de `changeStreamPreAndPostImages`. Novidades na versão 6.0. `updateLookup`: as notificações de alteração incluem uma cópia do documento modificado pela alteração. Este é o documento confirmado pela maioria atual ou `null` se não existir mais. `whenAvailable`: A notificação de alteração inclui uma cópia do documento modificado como ele apareceu imediatamente após a alteração ou `null` se o documento não estiver disponível. Para usar esta opção, você deve primeiro utilizar o comando `collMod` para habilitar a opção de `changeStreamPreAndPostImages`. Novidades na versão 6.0. No caso de atualizações parciais, a notificação de alteração também fornece uma descrição da alteração.
`fullDocumentBeforeChange`	Inclua o documento completo antes da alteração. Este campo aceita os seguintes valores: `off`: Desabilita a inclusão do documento antes da alteração. `whenAvailable`: Inclui documento anterior à alteração. A query não falhará se o documento não modificado não estiver disponível. `required`: inclui documento anterior à alteração. A query falha se o documento não modificado não estiver disponível.
`resumeAfter`	Opcional. Especifica um token de currículo como o ponto de partida lógico para o fluxo de alteração. Não pode ser usado para retomar o fluxo de alterações após um evento `invalidate`. `resumeAfter` é mutuamente exclusivo com `startAfter` e `startAtOperationTime`.
`showExpandedEvents`	Especifica se incluir eventos de mudança adicionais, como DDL e operações de índice. Novidades na versão 6.0.
`startAfter`	Opcional. Especifica um token de resumo como o ponto de partida lógico para o fluxo de alterações. Ao contrário de `resumeAfter`, `startAfter` pode retomar notificações após um evento `invalidate` criando um novo fluxo de alterações. `startAfter` é mutuamente exclusivo com `resumeAfter` e `startAtOperationTime`.
`startAtOperationTime`	Especifica uma hora como o ponto de partida lógico para o change stream. Não pode ser utilizado com campos `resumeAfter` ou `startAfter`.

Suporte à API Estável

Os change streams estão incluídos na Stable API V1. No entanto, a opção showExpandedEvents não está incluída na Stable API V1.

Exemplos

Para criar um cursor de change stream com o estágio de aggregation, execute o comando aggregate.

var cur = db.names.aggregate( [
   { $changeStream: {} }
] )

Para abrir o cursor, execute cur.

Quando o fluxo de alteração detecta uma alteração, o método next() retorna uma notificação de alteração de evento. Por exemplo, após executar o cur.next(), o MongoDB retorna um documento semelhante ao seguinte:

{
   "_id": {
      _data: "8262E2EE54000000022B022C0100296E5A100448E5E3DD01364019AE8FE8C6859527E046645F6964006462E2EE54C8756C0D5CF6F0720004"
   },
   "operationType": "insert",
   "clusterTime": Timestamp({ t: 1659039316, i: 2 }),
   "wallTime": ISODate("2022-07-28T20:15:16.148Z"),
   "fullDocument": {
      "_id": ObjectId("62e2ee54c8756c0d5cf6f072"),
      "name": "Walker Percy"
   },
   "ns": {
      "db": "test",
      "coll": "names"
   },
   "documentKey": { _id: ObjectId("62e2ee54c8756c0d5cf6f072") }
}

Para usar o driver MongoDB .NET/C# para adicionar um estágio $changeStream a um pipeline de agregação, chame o método ChangeStream() em um objeto PipelineDefinition.

O exemplo a seguir cria um estágio de pipeline que retorna um cursor de fluxo de mudança:

var pipeline = new EmptyPipelineDefinition<Movie>()
    .ChangeStream();

Você pode usar um objeto ChangeStreamStageOptions para personalizar o comportamento do change stream. O exemplo a seguir executa a mesma operação $changeStream do exemplo anterior, mas especifica as seguintes opções:

A opção FullDocument especifica que as notificações de alteração não incluem uma cópia do documento completo quando modificado por operações de atualização.
A opção StartAtOperationTime especifica o ponto de partida lógico para o fluxo de alteração.

var changeStreamOptions = new ChangeStreamStageOptions()
{
    FullDocument = ChangeStreamFullDocumentOption.Default,
    StartAtOperationTime = new BsonTimestamp(300),
};
var pipeline = new EmptyPipelineDefinition<Movie>()
    .ChangeStream(changeStreamOptions);

Observação

Preferir o método Watch()

Sempre que possível, use o método IMongoCollection<TDocument>.Watch() em vez deste estágio de agregação . Use o método ChangeStream() somente se os estágios subsequentes projeto o token de retomada (_id) ou se você não quiser que o cursor resultante seja retomado automaticamente.

Você pode usar o método watch() e o método aggregate() para executar uma operação $changeStream. $changeStream retorna um ChangeStreamCursor quando você passa o pipeline de agregação para o método watch() em um objeto MongoDB Collection. $changeStream retorna um AggregationCursor quando você passa o pipeline de agregação para o método aggregate().

Importante

Retomabilidade $changeStream

Se você passar um change stream para o método aggregate(), o change stream não poderá ser retomado. Um change stream só é retomado se você passá-lo para o método watch(). Para saber mais sobre a capacidade de retomada, consulte Retomar um fluxo de alterações.

O exemplo seguinte cria e executa um pipeline que retorna um ChangeStreamCursor:

const pipeline = [{ $changeStream: {} }];
const changeStream = collection.watch(pipeline);
return changeStream;

Você pode usar um objeto ChangeStreamOptions para personalizar o comportamento do change stream. O exemplo a seguir executa a mesma operação $changeStream do exemplo anterior, mas especifica as seguintes opções:

A opção fullDocument especifica que, se uma operação de atualização modificar um documento, as notificações de alteração incluirão uma cópia do documento completo.
A opção startAtOperationTime especifica o ponto de partida lógico para o fluxo de alteração.

const pipeline = [
  {
    $changeStream: {
      fullDocument: 'updateLookup',
      startAtOperationTime: 3000
    }
  }
];
const changeStream = collection.watch(pipeline);
return changeStream;

Saiba mais

Para mais informações sobre como alterar as notificações de transmissão, consulte Alterar eventos.

Para saber mais sobre os estágios de pipeline relacionados, consulte o guia$changeStreamSplitLargeEvent.

Voltar

$bucketAuto

$changeStreamSplitLargeEvent