Overview
This node enables interaction with MongoDB databases using the Mongoose Object Data Modeling (ODM) library. It supports a variety of operations such as finding documents, creating new entries, updating existing ones, deleting documents, counting records, and running aggregation pipelines on specified collections.
Common scenarios where this node is beneficial include:
- Querying user data or product catalogs with complex filters.
- Updating multiple documents based on dynamic criteria.
- Aggregating data for reports or analytics.
- Managing database records programmatically within an n8n workflow.
For example, you can use the "Find" operation to retrieve all users older than 18 years, selecting only their names and emails. Or use the "Update" operation to modify multiple documents matching certain conditions, optionally creating new documents if none match (upsert).
Properties
| Name | Meaning |
|---|---|
| Database | The name of the MongoDB database to connect to. Leave empty to use the default database from the configured credential. |
| Collection | The name of the collection within the database to operate on. |
| Query | A MongoDB query object in JSON format used to filter documents. Leave empty ({}) for no filtering. |
| Schema Definition | Defines the Mongoose schema for the collection in JSON format, specifying field names and types (e.g., String, Number, Date). |
| Select Fields | JSON string specifying which fields to include or exclude in the result (e.g., {"_id": 1, "name": 1}). Leave empty to select all fields. Only applicable for "find" and "findOne" operations. |
| Include Query Info | Boolean flag indicating whether to include raw MongoDB query information in the response output. |
| Options | A collection of additional options: |
| - Limit | Maximum number of results to return (default 1000, max 10000). |
| - Skip | Number of documents to skip before returning results (not applicable for aggregate operations). |
| - Sort | JSON object defining sort order (e.g., {"name": 1, "age": -1}), not applicable for aggregate operations. |
| - Select Fields | Space-separated string listing fields to include/exclude (e.g., "name email -_id"), not applicable for aggregate operations. |
| - Upsert | For update operations only: whether to create a document if none matches the query. |
| - Multi | For update operations only: whether to update multiple documents. |
| - Query Timeout (Ms) | Maximum time in milliseconds to allow the query to run (range 1000โ300000 ms). |
| - Debug Mode | Enables Mongoose debug mode to log all MongoDB queries to the console. |
Output
The node outputs an array of items, each containing a json property with the operation result. The structure depends on the operation:
- Find / Find One: Returns the matched documents as plain JSON objects, optionally filtered by selected fields.
- Create: Returns the created document.
- Update / Update One: Returns the result of the update operation, including counts of modified documents.
- Delete / Delete One: Returns the result of the delete operation, including counts of deleted documents.
- Count: Returns the count of documents matching the query.
- Aggregate: Returns the aggregated documents as per the pipeline stages.
If the "Include Query Info" option is enabled, the output includes additional metadata about the executed query, operation type, and options used.
The node does not output binary data.
Dependencies
- Requires a MongoDB instance accessible via a connection string.
- Uses Mongoose ODM library for database interactions.
- Requires configuration of credentials that provide the MongoDB connection string and optional default database.
- Supports multi-database connections by specifying the database name at runtime.
Troubleshooting
Common Issues
- Connection errors: If the node cannot connect to MongoDB, verify the connection string, network accessibility, and that MongoDB is running.
- Authentication failures: Check username, password, and authentication source settings in the credentials.
- Invalid JSON inputs: Query, schema definition, or other JSON parameters must be valid JSON strings or objects; otherwise, parsing errors occur.
- Limit exceeded: The maximum allowed limit for returned documents is 10,000 to prevent performance issues.
- Large result sets warning: When returning more than 5,000 documents, a warning is logged suggesting adding indexes or refining filters.
Error Messages and Resolutions
"MongoDB connection error": Indicates failure to establish a connection. Verify connection details and server status."MongoDB authentication failed": Credentials are incorrect or insufficient permissions. Recheck authentication info."MongoDB host not found": DNS or IP address issue. Confirm hostname/IP and network connectivity."MongoDB connection refused": MongoDB service may not be running or port is blocked. Ensure MongoDB is active and reachable."Invalid JSON format": Input JSON is malformed. Correct the syntax."Limit exceeds maximum allowed limit": Reduce the limit parameter to 10,000 or less.