update Evento

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 }
          } }
    } )

    Observação

    O setClusterParameter comando não é suportado em clusters MongoDB Atlas . Para obter informações sobre o suporte do Atlas para todos os comandos, consulte Comandos não suportados no Atlas.

  • 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 do fluxo de alterações para menos de 16 mebibytes. 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 do fluxo de alterações para documentos de até 16 mebibytes se outros campos de evento de fluxo de alterações como updateDescription não forem grandes.

  • Solicite somente pré-imagens na saída do change stream para documentos de até 16 mebibytes 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 escritas 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.

Desambiguação de Caminho

O campo updateDescription observa alterações feitas em campos específicos em documentos por uma operação. Estes descritores de campo utilizam pontos (.) como separadores de caminho e números como índices de array, o que leva a alguma ambiguidade quando contém nomes de campo que utilizam pontos ou números.

Quando um evento do update relata alterações envolvendo campos ambíguos, o documento do disambiguatedPaths fornece a chave de caminho com uma array listando cada componente de caminho.

Por exemplo, considere um documento que relacione as pessoas e as cidades em que vivem:

{
   "name": "Anthony Trollope",
   "home.town": "Oxford",
   "residences": [
      {"0": "Oxford"},
      {"1": "Sunbury"}
   ]
}

• Quando uma atualização modifica o campo home.town de Oxford para London, ela produz uma descrição de atualização que se parece com isto:

  "updateDescription": {
     "updatedFields": {
        "home.town": "London"
     },
     "disambiguatedPaths": {
        "home.town": [ "home.town" ]
     }
  }

  Como o campo home.town contém um período, o campo disambiguatedPaths mostra uma array com um valor, para indicar que town não é um subcampo de home.

• Quando uma atualização modifica um valor na array residences para fazer a mesma alteração, ela produz uma descrição de atualização que se parece com isto:

  "updateDescription": {
     "updatedFields": {
        "residences.0.0": "London"
     },
     "disambiguatedPaths": { "residences.0.0": [ "residences", 0, "0" ] }
  }

  Os caminhos desambiguados incluem um número inteiro 0 para indicar o índice de array e a string "0" para indicar o nome do campo dentro do documento aninhado.

Há dois casos em que o disambiguatedPath não inclui um campo numérico:

• Quando o primeiro campo no caminho é uma sequência numérica (ou seja, 0.name). Isto não é ambíguo, pois o primeiro campo não pode ser um índice de array.

• Quando o campo de string numérica tiver zeros iniciais (ou seja, 0001). Isso não é ambíguo, pois um número inteiro não pode ter zeros à esquerda.

Atualizar operações

O comando update pode produzir diferentes eventos de alteração (não apenas update), dependendo das alterações reais que ele faz na collection.

Array Updates

As atualizações de arrays produzem eventos de alteração update, mas o updateDescription.updateFields pode mostrar valores diferentes.

Por exemplo, considere o seguinte documento e atualizações:

db.students.insertOne( { student_id: 1, scores: [ ] } )
db.students.updateOne(
   { student_id: 1 },
   { $push: { scores: 0.85 } }
)
db.students.updateOne(
   { student_id: 1 },
   { $push: { scores: 0.94 } }
)
db.students.updateOne(
   { student_id: 1 },
   { $pull: { scores: 0.94 } }
)

A primeira atualização opera em uma array vazia. Aqui, o $push produz um evento de alteração update em que o campo é substituído por uma array de entrada única com o valor fornecido:

{
   _id: { _data: '82642AD66B000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
   operationType: 'update',
   clusterTime: Timestamp({ t: 1680529003, i: 1 }),
   ns: { db: 'communication_chat', coll: 'students' },
   documentKey: { student_id: 1 },
   updateDescription: {
      updatedFields: { scores: [ 0.85 ] },
      removedFields: [],
      truncatedArrays: []
   }
}

Na segunda operação de atualização, a array agora contém valores. O $push adiciona uma nova entrada na array. O evento de alteração update então o mostra como uma alteração na nova posição na array (ou seja, scores.1):

{
  _id: { _data: '82642AD673000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
  operationType: 'update',
  clusterTime: Timestamp({ t: 1680529011, i: 1 }),
  ns: { db: 'communication_chat', coll: 'students' },
  documentKey: { student_id: 1 },
  updateDescription: {
    updatedFields: { 'scores.1': 0.94 },
    removedFields: [],
    truncatedArrays: []
  }
}

Se você executar a operação de atualização novamente para adicionar uma terceira pontuação ao registro do aluno, ela produzirá um evento de alteração update que modifica scores.2.

A remoção de itens da array com o operador $pull produz um evento de alteração que mostra a nova array:

{
  _id: { _data: '82642AD673000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
  operationType: 'update',
  clusterTime: Timestamp({ t: 1680529011, i: 1 }),
  ns: { db: 'communication_chat', coll: 'students' },
  documentKey: { student_id: 1 },
  updateDescription: {
    updatedFields: { scores: [ 0.85 ] },
    removedFields: [],
    truncatedArrays: []
  }
}

Truncamento de array

As operações de atualização que reduzem o número de elementos em arrays por meio das atualizações de pipeline, como com os estágios de agregação $addFields ou $set, mostram a array atualizada e o novo tamanho no campo truncatedArrays.

db.students.insertOne( { student_id: 2, scores: [ 0.85, 0.94, 0.78 ] } )
db.students.updateOne(
   { student_id: 2 },
   [ { $addFields: { scores: [ 0.85, 0.94 ] } } ]
)
db.students.updateOne(
   { student_id: 2 },
   [ { $addFields: { scores: [ 0.85, 0.94, 0.78 ] } } ]
)

O evento de alteração da primeira atualização, que usou o estágio $addFields para remover um valor do campo scores, mostra a alteração no campo truncatedArrays:

{
  _id: { _data: '82642AD673000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
  operationType: 'update',
  clusterTime: Timestamp({ t: 1680529011, i: 1 }),
  ns: { db: 'communication_chat', coll: 'students' },
  documentKey: { student_id: 2 },
  updateDescription: {
    updatedFields: {},
    removedFields: [],
    truncatedArrays: [ { fields: "scores", newSize: 2 } ]
  }
}

O evento de alteração da segunda atualização, que usou o estágio $addFields para adicionar um valor de volta ao campo scores, mostra a atualização no campo updatedFields:

{
  _id: { _data: '82642AD673000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
  operationType: 'update',
  clusterTime: Timestamp({ t: 1680529011, i: 1 }),
  ns: { db: 'communication_chat', coll: 'students' },
  documentKey: { student_id: 2 },
  updateDescription: {
    updatedFields: { scores.2: 0.78 },
    removedFields: [],
    truncatedArrays: []
  }
}