Overview
This node implements a real-time MongoDB Change Stream trigger using the Mongoose ODM. It allows users to monitor changes occurring in a MongoDB deployment at different levels: a specific collection, an entire database, or across all databases in the deployment.
Typical use cases include:
- Reacting instantly to document insertions, updates, deletions, or replacements in a MongoDB collection.
- Building event-driven workflows that respond to data changes without polling.
- Synchronizing data between systems by capturing live change events.
- Filtering and projecting change events for efficient downstream processing.
For example, you could watch the "orders" collection for new inserts and updates to automatically trigger order fulfillment workflows or notify customers of status changes.
Properties
| Name | Meaning |
|---|---|
| Database | The name of the MongoDB database to watch. Leave empty to use the default database from the configured credential. |
| Collection | The MongoDB collection name to monitor for real-time changes (e.g., "users", "orders"). Required when watching at the collection level. |
| Watch Level | The scope of change monitoring: - Collection: watch changes in a specific collection. - Database: watch changes in the entire database. - Deployment: watch changes across all databases. |
| Operation Types | Types of operations to watch for: - Insert - Update - Delete - Replace |
| Schema Definition | A JSON-formatted Mongoose schema definition used for proper field type conversion and validation. Leave empty to operate in schemaless mode. |
| Match Filter | A MongoDB aggregation match filter (JSON) to trigger only on specific changes. Supports filtering by fields in fullDocument or operation types. |
| Projection | A MongoDB projection (JSON) specifying which fields to include (1) or exclude (0) in the change event output, reducing data transfer. |
| Full Document | How to handle the full document in change events: - Default: no full document for deletes. - Update Lookup: return full document for update operations. - When Available: return full document if available. - Required: always return full document (may fail). |
| Output Format | Format of the output data: - Full Change Event: complete change stream event with all metadata. - Document Only: only the changed document ( fullDocument).- Simplified: operation type and document simplified format. |
| Options | Additional options including: - Batch Size: number of change events per batch. - Max Await Time (ms): max wait time for new changes. - Resume Token: JSON string to resume from a specific point. - Resume Token From Database: whether to load/save resume tokens automatically. - Resume Token Collection/Database/Key: settings for storing resume tokens. - Start At Operation Time: ISO timestamp to start watching from. - Resume Token Save Frequency: how often to save resume tokens. - Debug Mode: enable debug logging. |
Output
The node outputs JSON objects representing MongoDB change events according to the selected output format:
- Full Change Event: Outputs the entire change stream event object, including metadata such as operation type, cluster time, document key, update description, etc.
- Document Only: Outputs only the changed document (
fullDocument) from the event. - Simplified: Outputs a simplified object containing the operation type, document key, changed document, update description, and timestamp.
If enabled, debug logs provide additional insights into the change stream lifecycle and events.
No binary data is output by this node.
Dependencies
- Requires a MongoDB connection configured via an API key credential supporting multi-database access.
- Uses Mongoose ODM internally to manage schema definitions and connections.
- Optionally stores and retrieves resume tokens in a MongoDB collection to allow resuming streams after interruptions.
- Requires network access to the MongoDB deployment.
- No external services beyond MongoDB are required.
Troubleshooting
- Connection Timeout: If the node fails to connect within 30 seconds, check network connectivity and MongoDB server availability.
- Invalid JSON in Properties: Schema definition, match filter, projection, or resume token must be valid JSON strings. Errors will indicate invalid JSON format.
- Resume Token Issues: Incorrect or missing resume tokens can cause missed events or duplicate processing. Ensure resume tokens are correctly stored and loaded if using automatic resume token management.
- Permission Errors: The MongoDB user must have permissions to watch change streams and read/write resume token collections if used.
- Schema Mismatch: Providing an incorrect schema definition may cause unexpected behavior in field conversions.
- Debug Mode: Enable debug mode to get detailed logs about connection status, event processing, and errors.
- Change Stream Closure: Unexpected closure of the change stream may indicate network issues or server-side problems; the node attempts to handle reconnections.