Struttura del documento degli eventi di modifica

Every event delivered by a change stream is a change event document with a standard set of fields. The most important fields are operationType (what happened), ns (which namespace was affected), documentKey (the _id of the affected document), and operation-specific fields like fullDocument and updateDescription. Understanding this structure lets you write event handlers that correctly react to each type of operation.

The operationType field identifies what kind of change occurred. Common values include: 'insert' (new document added), 'update' (document fields modified), 'replace' (entire document replaced), 'delete' (document removed), and 'invalidate' (the change stream has been invalidated, e.g., the collection was dropped). There are also 'drop', 'rename', and 'dropDatabase' for collection/database operations.

The ns field contains the namespace of the affected collection as an object with two properties: ns.db (the database name) and ns.coll (the collection name). This field is essential when you open a change stream at the database or client level, where events from multiple collections arrive on the same stream. Use ns.coll to route events to the correct handler.

The documentKey field contains the _id of the document that was affected by the change. It is present on all operation types except 'invalidate' and collection-level operations. For sharded collections, documentKey may also include the shard key fields alongside _id. This field lets you identify which specific document was changed without needing to read the full document.

For 'insert' operations, the change event includes a fullDocument field containing the complete document that was inserted, including the auto-generated _id. This is available by default for insert events—unlike update events where you need to opt-in with updateLookup. Use this to immediately process new data without issuing a follow-up query.

For 'update' operations, the change event includes an updateDescription object instead of a full document. It has two subfields: updatedFields (a map of field paths to their new values) and removedFields (an array of field paths that were unset). This delta format is compact and efficient—it only reports what changed, not the entire document state.

A 'replace' event occurs when replaceOne() is called, which substitutes the entire document (except _id). The change event includes a fullDocument with the complete new document. This differs from an update event in that there is no updateDescription—you cannot tell what changed, only what the new state is. Process replace events like insert events: read the full new state from fullDocument.

For 'delete' events, the fullDocument field is null because the document is already gone by the time you process the event. Only documentKey (containing the _id) is reliably available. If your delete handler needs the document's content, you must store the relevant information before deletion (e.g., in an audit log) because change streams cannot retrieve documents that have already been removed.

Every change event has a resume token stored in its _id field (a { _data: '...' } object). This token identifies the event's position in the oplog. Store the resume token after processing each event so that if your application restarts, it can resume the stream from where it left off using the resumeAfter or startAfter option. This enables at-least-once delivery guarantees.

An 'invalidate' event signals that the change stream can no longer continue—typically because the watched collection was dropped, the database was dropped, or the replica set encountered a rollback. After an invalidate event, the change stream closes automatically. Your application should handle this by reopening the stream (or alerting administrators) rather than ignoring it. Check for the 'invalidate' type and decide whether to reopen or shut down.

Combining all event types into a single robust handler with switch-based routing makes the code maintainable. Each case reads only the fields that are guaranteed to be present for that operation type. Adding structured logging that includes the operationType, namespace, and documentKey gives good observability into what your change stream is processing.

In this lesson you learned: every change event has operationType, ns, documentKey, and operation-specific fields like fullDocument and updateDescription, insert/replace events include fullDocument but delete events do not (document is already gone), and the event's _id field is the resume token used to restart the stream from a known position. Next up we explore filtering change stream events with aggregation pipelines.