Overview
This node enables interaction with a MongoDB database, specifically supporting operations such as finding documents, inserting new documents, updating existing ones, replacing documents, deleting documents, and running aggregation queries. The "Find And Replace" operation allows you to find documents based on a key and replace them entirely with new data.
Common scenarios where this node is beneficial include:
- Synchronizing data from other systems into MongoDB.
- Updating or replacing specific documents in a collection based on a unique identifier.
- Performing bulk updates or inserts with control over how fields are handled (e.g., date or ObjectId fields).
- Running complex queries or aggregations on MongoDB collections.
Practical example: You have a collection of user profiles and want to replace the entire document for users identified by their unique id with updated profile information received from an external API.
Properties
| Name | Meaning |
|---|---|
| Collection | The name of the MongoDB collection where the operation will be performed. |
| Update Key | The property name used to identify which documents to update or replace. Typically this is "id" or "_id". |
| Fields | Comma-separated list of fields to include in the new document when replacing or updating. |
| Upsert | Boolean flag indicating whether to insert a new document if no matching document is found during update or replace operations. |
| Options | Additional options controlling field parsing and behavior: - Date Fields: Comma-separated list of fields to parse as MongoDB Date type. - Use Dot Notation: Whether to use dot notation to access nested date fields. - OID Fields: Comma-separated list of fields to parse as MongoDB ObjectId type. |
Output
The output is a JSON array where each item corresponds to an input item processed by the node. For the "Find And Replace" operation, each output item contains the replaced document's data after processing.
- If the operation succeeds, the output items contain the full document that was inserted or replaced.
- If an error occurs and the node is configured to continue on failure, the output item will contain an
errorfield with the error message. - The node also converts MongoDB ObjectIds in the output to string representations for easier consumption downstream.
No binary data is output by this node.
Dependencies
- Requires a MongoDB database connection with appropriate credentials.
- Needs an API key or authentication token configured in n8n to connect securely to the MongoDB instance.
- Uses the official MongoDB Node.js driver and BSON utilities internally.
- No additional external services are required beyond MongoDB itself.
Troubleshooting
Common issues:
- Incorrect collection name or database name causing "collection not found" errors.
- Invalid or missing update key leading to no documents being matched for replacement.
- Malformed query or fields input causing parsing errors.
- Insufficient permissions on the MongoDB user account for performing write operations.
- Misconfigured connection string or credentials resulting in connection failures.
Error messages and resolutions:
"Database \"<name>\" does not exist": Verify the database name in credentials and ensure it exists on the MongoDB server."The operation \"<operation>\" is not supported!": Check that the selected operation is valid and supported by the node.- Errors related to ObjectId conversion: Ensure that fields expected to be ObjectIds are correctly specified in the OID Fields option.
- Parsing errors on date fields: Confirm that date fields are listed correctly and that the input data matches expected formats.
To handle errors gracefully, enable the "Continue On Fail" option in the node settings.