npm package: @shoutoutlabs/n8n-nodes-mongodb-ejson
Description: n8n community node for MongoDB operations with EJSON query parsing support
Author: shoutout-labs
Latest version: 0.1.22

# n8n-nodes-mongodb-ejson

This is an n8n community node that provides MongoDB operations with Extended JSON (EJSON) query parsing support. It allows you to work with MongoDB ObjectIds, Dates, and other BSON types using the standard MongoDB Extended JSON format.

[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.

## Table of Contents

- [Installation](#installation)
- [Operations](#operations)
- [Credentials](#credentials)
- [EJSON Support](#ejson-support)
- [Usage Examples](#usage-examples)
- [Compatibility](#compatibility)
- [Resources](#resources)

## Installation

Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.

1. Go to **Settings > Community Nodes**
2. Select **Install**
3. Enter `n8n-nodes-mongodb-ejson` as the npm package name
4. Agree to the [risks](https://docs.n8n.io/integrations/community-nodes/risks/) of using community nodes

## Operations

The MongoDB EJSON node supports the following operations:

### Find Documents
- **Query (EJSON)**: MongoDB query using EJSON format
- **Limit**: Maximum number of documents to return
- **Skip**: Number of documents to skip
- **Sort (EJSON)**: Sort criteria in EJSON format

### Insert Documents  
- **Data to Insert**: Choose between using data from previous node or defining custom data
- **Data (EJSON)**: Custom data to insert in EJSON format

### Update Documents
- **Query (EJSON)**: Filter criteria for documents to update
- **Update (EJSON)**: Update operations using MongoDB update operators
- **Options**: Additional options like upsert

### Delete Documents
- **Query (EJSON)**: Filter criteria for documents to delete

### Find and Update
- **Query (EJSON)**: Filter criteria for document to update
- **Update (EJSON)**: Update operations
- **Options**: Upsert and return document options

### Find and Replace
- **Query (EJSON)**: Filter criteria for document to replace
- **Replacement (EJSON)**: Complete replacement document
- **Options**: Upsert and return document options

### Aggregate Documents
- **Pipeline (EJSON)**: MongoDB aggregation pipeline in EJSON format

## Credentials

The node requires MongoDB API credentials with the following options:

### Connection String Configuration
- **Connection String**: Full MongoDB connection string
  - Format: `mongodb://username:password@hostname:port/database`

### Individual Values Configuration  
- **Host**: MongoDB server hostname (default: localhost)
- **Port**: MongoDB server port (default: 27017)
- **Database**: Database name
- **User**: Username for authentication
- **Password**: Password for authentication

## EJSON Support

This node uses MongoDB's Extended JSON (EJSON) format, which allows you to represent BSON types in JSON. This is particularly useful for:

### ObjectId
```json
{"_id": {"$oid": "507f1f77bcf86cd799439011"}}
```

### Date
```json
{"createdAt": {"$date": "2023-01-01T00:00:00.000Z"}}
```

### Other BSON Types
The node supports all EJSON representations including:
- `{"$numberLong": "123456789"}` for 64-bit integers
- `{"$regex": "pattern", "$options": "flags"}` for regular expressions
- `{"$binary": {"base64": "data", "subType": "00"}}` for binary data

## Usage Examples

### Example 1: Find Documents by ObjectId
```json
{
  "operation": "find",
  "collection": "users",
  "query": "{\"_id\": {\"$oid\": \"507f1f77bcf86cd799439011\"}}"
}
```

### Example 2: Insert Document with Date
```json
{
  "operation": "insert", 
  "collection": "orders",
  "data": "{\"userId\": {\"$oid\": \"507f1f77bcf86cd799439011\"}, \"amount\": 100, \"createdAt\": {\"$date\": \"2023-01-01T00:00:00.000Z\"}}"
}
```

### Example 3: Update Documents with Date Range
```json
{
  "operation": "update",
  "collection": "orders", 
  "query": "{\"createdAt\": {\"$gte\": {\"$date\": \"2023-01-01T00:00:00.000Z\"}}}",
  "updateData": "{\"$set\": {\"status\": \"processed\", \"updatedAt\": {\"$date\": \"2023-01-02T00:00:00.000Z\"}}}"
}
```

### Example 4: Aggregation Pipeline
```json
{
  "operation": "aggregate",
  "collection": "sales",
  "pipeline": "[{\"$match\": {\"date\": {\"$gte\": {\"$date\": \"2023-01-01T00:00:00.000Z\"}}}}, {\"$group\": {\"_id\": \"$category\", \"total\": {\"$sum\": \"$amount\"}}}]"
}
```

### Example 5: Find with Complex Query
```json
{
  "operation": "find",
  "collection": "products",
  "query": "{\"$and\": [{\"price\": {\"$gte\": 100}}, {\"category\": \"electronics\"}, {\"createdAt\": {\"$gte\": {\"$date\": \"2023-01-01T00:00:00.000Z\"}}}]}",
  "sort": "{\"price\": -1}",
  "limit": 10
}
```

## Key Features

- ✅ **Full EJSON Support**: Native support for MongoDB Extended JSON format
- ✅ **ObjectId Handling**: Proper ObjectId parsing and serialization  
- ✅ **Date Support**: Native Date object support through EJSON
- ✅ **All MongoDB Operations**: Find, Insert, Update, Delete, FindAndUpdate, FindAndReplace, Aggregate
- ✅ **Advanced Options**: Upsert, return document options, sorting, pagination
- ✅ **Error Handling**: Comprehensive error handling with detailed messages
- ✅ **Connection Flexibility**: Support for both connection strings and individual connection parameters

## Compatibility

This node is compatible with:
- n8n version 1.0.0 and above
- MongoDB 4.0 and above
- Node.js 20.15 and above

## Resources

- [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
- [MongoDB Extended JSON documentation](https://docs.mongodb.com/manual/reference/mongodb-extended-json/)
- [MongoDB Node.js Driver documentation](https://mongodb.github.io/node-mongodb-native/)
- [BSON documentation](https://bsonspec.org/)

## Version History

### 0.1.0
- Initial release
- Full EJSON query parsing support
- All basic MongoDB operations (Find, Insert, Update, Delete, FindAndUpdate, FindAndReplace, Aggregate)
- Flexible credential configuration
- Comprehensive error handling

## License

[MIT](https://github.com/n8n-io/n8n/blob/master/LICENSE.md)