MongoDB EJSON

MongoDB operations with EJSON query parsing support

Actions8

Overview

This node performs MongoDB operations using Extended JSON (EJSON) format for queries and data, enabling advanced querying and manipulation of MongoDB documents with support for MongoDB-specific data types. It is particularly useful when working with complex MongoDB documents that include ObjectIds, dates, decimals, or binary data, as EJSON preserves these types during input and output.

The "Find And Replace" operation specifically allows you to find a single document matching a query and replace it entirely with a new document. This is beneficial in scenarios where you want to overwrite an existing document atomically, such as updating a user profile or replacing configuration settings without partial updates.

Example use case:
You have a collection of user profiles and want to replace the entire document for a specific user identified by their unique ID with a new profile object, ensuring no residual fields remain from the old document.

Properties

Name	Meaning
Collection	The name of the MongoDB collection where the operation will be performed.
Update Key	The property used to identify which document to replace. Usually this is `_id`.
Replace Query (EJSON Format)	The MongoDB query in EJSON format used to find the document to replace. For example, `{"_id": {"$oid": "507f1f77bcf86cd799439011"}}`.
Replacement Data (EJSON Format)	The replacement document in EJSON format that will completely replace the matched document. For example, `{"name": "John", "status": "active", "updatedAt": {"$date": "2023-01-01T00:00:00Z"}}`. This is required.
Upsert	Whether to insert the replacement document if no matching document is found (`true` or `false`).
Lean Output	Whether to return lean output, which removes MongoDB ObjectId objects and returns plain JavaScript objects instead. Defaults to `true`.
Options	Additional options for the operation:
- Return Updated Document	Whether to return the document before or after the replacement. Options are `before` or `after`. Defaults to `after`.

Output

The output is a JSON array where each item corresponds to an input item processed. Each output item contains:

The replaced document information depending on the returnDocument option:
- If after, the document after replacement.
- If before, the document before replacement.
If leanOutput is enabled, MongoDB-specific types like ObjectId are converted to plain strings or standard JSON types.
In case of errors (if continueOnFail is enabled), the output includes an error message per item.

No binary data output is produced by this operation.

Dependencies

Requires a MongoDB database connection configured via credentials containing the necessary authentication details.
Uses MongoDB Node.js driver and BSON library internally to parse and handle EJSON.
The node expects the MongoDB server to support the operations used (MongoDB 4.0+ recommended for full feature support).

Troubleshooting

Invalid EJSON query or replacement data:
Error message: Invalid EJSON query: ... or Invalid EJSON: ...
Resolution: Ensure the query and replacement JSON are valid Extended JSON format. Use correct syntax for ObjectId ({"$oid": "..."}), dates, decimals, etc.
Database or collection not found:
Error message: Database "xyz" does not exist or similar connection errors.
Resolution: Verify your MongoDB credentials and that the specified database and collection exist.
No document matched and upsert disabled:
The operation will not insert a new document if upsert is false and no match is found. Consider enabling upsert if insertion is desired.
Return document option confusion:
If you do not see the expected document in output, check the Return Updated Document option to ensure it is set to after to get the updated document.
Connection issues:
Network or authentication failures can cause errors. Check your connection string and network accessibility.