Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Fluxos de alterações
/
Alterar eventos

replace Evento

Nesta página

  • Resumo
  • Descrição
  • Comportamento
  • Documentar pré e pós-imagens
  • Exemplos

Resumo

replace

Um evento replace ocorre quando uma operação de atualização remove um documento de uma coleta e o substitui por um novo documento, como quando o método replaceOne é chamado.

Descrição

Campo
Tipo
Descrição

_id

Documento

Um objeto BSON que serve como um identificador para o evento de fluxo de alterações. Este valor é utilizado como resumeToken para o parâmetro resumeAfter ao retomar um fluxo de alteração. O objeto _id tem o seguinte formulário:

{
   "_data" : <BinData|hex string>
}

O _data tipo de depende das versões do MongoDB e, em alguns casos, da versão de compatibilidade do recurso (FCV) no momento da abertura ou retomada do fluxo de alterações.Consulte Tokens de currículo para obter a lista completa de _data tipos.

Para obter um exemplo de como retomar um fluxo de alterações por resumeToken, consulte Retomar um fluxo de alterações.

clusterTime

Timestamp

clusterTime é o registro de data/hora da entrada de registro opcional associada ao evento.

Devido aos limites de tamanho do oplog , transações com vários documentos podem criar várias entradas no oplog. Em uma transação, os eventos de change stream encenados em uma determinada entrada do oplog compartilham o mesmo clusterTime.

Eventos com o mesmo clusterTime podem não estar relacionados à mesma transação. Alguns eventos não estão nem um pouco relacionados a uma transação. A partir do MongoDB 8.0, isso pode ser verdade para eventos em qualquer sistema. Nas versões anteriores, este comportamento era possível apenas para eventos em um cluster fragmentado.

Para identificar eventos para uma única transação, você pode usar a combinação de lsid e txnNumber no documento de eventos do fluxo de alterações.

Alterado na versão 8.0.

collectionUUID

UUID

UUID identificando a coleção onde ocorreu a alteração.

Novidades na versão 6.0.

documentKey

documento

Documento que contém o valor _id do documento criado ou modificado pela operação CRUD.

Para coleções fragmentadas, este campo também exibe a chave de fragmentação completa do documento. O campo _id não se repete se já fizer parte da chave fragmentada.

fullDocument

documento

O novo documento criado pela operação.

Alterado na versão 6.0.

A partir do MongoDB 6.0, se você definir a opção changeStreamPreAndPostImages usando db.createCollection(), create ou collMod, o campo fullDocument mostrará o documento depois que ele foi inserido, substituído ou atualizado (o documento pós-imagem). fullDocument é sempre incluído para eventos insert.

fullDocumentBeforeChange

documento

O documento antes das alterações serem aplicadas pela operação. Ou seja, a pré-imagem do documento.

Este campo está disponível quando você habilita o campo changeStreamPreAndPostImages para uma coleção utilizando o método db.createCollection() ou os comandos create ou collMod.

Novidades na versão 6.0.

lsid

documento

O identificador da sessão associada à transação.

Somente presente se a operação fizer parte de uma transação de vários documentos.

ns

documento

O namespace (banco de dados e/ou coleção) afetado pelo evento.

ns.coll

string

O nome da coleção onde o evento ocorreu.

ns.db

string

O nome do banco de dados onde ocorreu o evento.

operationType

string

O tipo de operação que os relatórios de notificação de alteração.

Retorna um valor de replace para estes eventos de alteração.

txnNumber

Número longo

Juntamente com o lsid, um número que ajuda a identificar exclusivamente uma transação.

Somente presente se a operação fizer parte de uma transação de vários documentos.

wallTime

Data ISO

A data e hora do servidor da operação do banco de dados. wallTime difere de clusterTime em que clusterTime é um carimbo de data/hora obtido da entrada oplog associada ao evento de operação do banco de dados.

Novidades na versão 6.0.

Comportamento

Documentar pré e pós-imagens

A partir do MongoDB 6.0, você verá um documento fullDocumentBeforeChange com os campos antes de o documento ser alterado (ou excluído) se executar estas etapas:

  1. Ative o novo campo changeStreamPreAndPostImages para uma coleção utilizando db.createCollection(), create ou collMod.

  2. Configure fullDocumentBeforeChange para "required" ou "whenAvailable" em db.collection.watch().

Exemplo de documento fullDocumentBeforeChange na saída do fluxo de mudança:

"fullDocumentBeforeChange" : {
   "_id" : ObjectId("599af247bb69cd89961c986d"),
   "userName" : "alice123",
   "name" : "Alice Smith"
}

Para obter exemplos completos com a saída do fluxo de alterações, consulte Fluxos de alterações com imagens pré e pós-documento.

As imagens pré e pós não estarão disponíveis para um change stream se as imagens forem:

  • Não habilitadas na coleção no momento de uma operação de atualização ou exclusão de documento.

  • Removido após o tempo de retenção pré e pós-imagem definido em expireAfterSeconds.

    • O exemplo a seguir define expireAfterSeconds para 100 segundos em um cluster inteiro:

      use admin
      db.runCommand( {
         setClusterParameter:
            { changeStreamOptions: {
               preAndPostImages: { expireAfterSeconds: 100 }
            } }
      } )

    • O exemplo a seguir retorna as configurações atuais do changeStreamOptions, incluindo expireAfterSeconds:

      db.adminCommand( { getClusterParameter: "changeStreamOptions" } )

    • Definir expireAfterSeconds para off usa a política de retenção: pré-imagens e pós-imagens são retidas até os eventos de change streams serem removidos do oplog.

    • Se um change stream for removido do oplog, as imagens pré e pós correspondentes também serão excluídas, independentemente do tempo de retenção pré e pós-imagem expireAfterSeconds .

Considerações adicionais:

  • Habilitar pré e pós-imagens consome espaço de armazenamento e adiciona tempo de processamento. Ative as imagens anteriores e posteriores somente se precisar delas.

  • Limite o tamanho do evento de transmissão da alteração para menos de 16 megabytes. Para limitar o tamanho do evento, você pode:

    • Limite o tamanho do documento a 8 megabytes. Você pode solicitar imagens pré e pós simultaneamente na saída do change stream se outros campos de evento de change stream, como updateDescription não forem grandes.

    • Solicite apenas pós-imagens na saída de fluxo de alteração para documentos de até 16 megabytes se outros campos de evento de fluxo de alteração como updateDescription não forem grandes.

    • Solicite somente pré-imagens na saída do change stream para documentos de até 16 megabytes se:

      • as atualizações do documento afetam apenas uma pequena fração da estrutura ou conteúdo do documento, e

      • não causa um evento de alteração replace . Um evento replace sempre inclui o pós-imagem.

  • Para solicitar uma pré-imagem, defina fullDocumentBeforeChange como required ou whenAvailable em db.collection.watch(). Para solicitar uma pós-imagem, defina fullDocument usando o mesmo método.

  • As pré-imagens são gravadas na coleção config.system.preimages.

    • A coleção config.system.preimages pode ficar grande. Para limitar o tamanho da coleção, você pode definir expireAfterSeconds tempo para as pré-imagens, conforme mostrado anteriormente.

    • As pré-imagens são removidas de forma assíncrona por um processo de plano de fundo.

Importante

Funcionalidade incompatível com versões anteriores

A partir do MongoDB 6.0, se você estiver usando imagens anteriores e posteriores de documentos para change streams, deverá desabilitar changeStreamPreandPostImages para cada coleção usando o collMod comando antes de poder fazer o downgrade para uma versão anterior do MongoDB.

Dica

Veja também:

Exemplos

O exemplo seguinte ilustra um evento replace:

{
   "_id": { <Resume Token> },
   "operationType": "replace",
   "clusterTime": <Timestamp>,
   "wallTime": <ISODate>,
   "ns": {
      "db": "engineering",
      "coll": "users"
   },
   "documentKey": {
      "_id": ObjectId("599af247bb69cd89961c986d")
   },
   "fullDocument": {
      "_id": ObjectId("599af247bb69cd89961c986d"),
      "userName": "alice123",
      "name": "Alice"
   }
}

Uma operação replace utiliza o comando de atualização e consiste em dois estágios:

  • Exclua o documento original com o documentKey e

  • Insira o novo documento usando o mesmo documentKey

O fullDocument de um evento replace representa o documento após a inserção do documento de substituição.

Voltar

renomear

Próximo

reshardCollection