<!-- BusyBot node reference — https://busybot.net/tools/mongodb/ -->

> Node: MongoDB (`mongodb`) · Action · v1
> Category: Data & Storage · Credentials: MongoDB (`mongodbApi`)
> Updated: 2026-08-16

# MongoDB

> Find, insert, update, and delete documents in MongoDB

## Overview

Runs CRUD operations against documents in a MongoDB database: find (with filter, sort, projection, skip and limit), insert (single or batch), update (one `$set` update per item), find-and-update, find-and-replace, delete (deletes every match), and aggregation pipelines. It also manages Atlas Search indexes — create, list, update and drop. The node connects with the official MongoDB Node.js driver and accepts either a full connection string or host/port credentials.

**Category:** Data & Storage  
**Tool Name:** `mongodb`  
**Version:** 1

**Appearance:** Icon: `si-mongodb` | Color: `#13AA52`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **MongoDB** credentials.
See the [Credentials Guide](https://busybot.net/credentials/mongodb-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Document | `document` |
| Search Index | `searchIndexes` |

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Aggregate | `aggregate` | Run an aggregation pipeline |
| Delete | `delete` | Delete documents matching a filter |
| Find | `find` | Find documents matching a query |
| Find And Replace | `findOneAndReplace` | Find a document and replace it entirely |
| Find And Update | `findOneAndUpdate` | Find a document and update specific fields using $set |
| Insert | `insert` | Insert new documents |
| Update | `update` | Update documents using updateOne per item |
| Create | `createSearchIndex` | Create an Atlas Search index |
| Drop | `dropSearchIndex` | Drop an Atlas Search index |
| List | `listSearchIndexes` | List Atlas Search indexes |
| Update | `updateSearchIndex` | Update an Atlas Search index definition |

The first seven belong to the **Document** resource; the last four belong to **Search Index**.

### Parameters

#### Document: Aggregate

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Query (JSON) | `json` | Yes | — | MongoDB aggregation pipeline as a JSON array of stage objects. |
| Allow Unbounded | `boolean` | No | `false` | Allow unbounded queries (no row cap). Use with extreme caution — can OOM the worker. |

#### Document: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Delete Query (JSON) | `json` | Yes | `{}` | MongoDB delete filter as a JSON object. All matching documents will be deleted (deleteMany). |
| Confirm Delete All | `boolean` | No | `false` | Required when the delete filter is empty (matches every document). Safety guard against accidental wipe. |

#### Document: Find

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Query (JSON) | `json` | Yes | `{}` | MongoDB find filter as a JSON object. |
| Options | `collection` | No | `{}` | Additional query options for find. |
| — Limit | `number` | No | `0` | Maximum number of documents to return. 0 = unlimited. |
| — Skip | `number` | No | `0` | Number of documents to skip in the result set. |
| — Sort (JSON) | `json` | No | `{}` | Sort order as a JSON object. Use 1 for ascending, -1 for descending. |
| — Projection (JSON) | `json` | No | `{}` | Fields to include or exclude in results. 1 = include, 0 = exclude. |
| Allow Unbounded | `boolean` | No | `false` | Allow unbounded queries (no row cap). Use with extreme caution — can OOM the worker. |

#### Document: Insert

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Fields | `string` | No | — | Comma-separated list of fields from input items to include in the inserted documents. Leave empty to include all fields. |
| Options | `collection` | No | `{}` | Additional options for insert/update/replace operations. |
| — Date Fields | `string` | No | — | Comma-separated list of fields to parse as MongoDB Date type. |
| — Use Dot Notation | `boolean` | No | `false` | Whether to use dot notation to access nested fields. E.g. "address.city" resolves to { address: { city: value } }. |

#### Document: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Update Key | `string` | Yes | `_id` | Field name used to match the document to update. Use "_id" for the MongoDB document ID. |
| Fields | `string` | No | — | Comma-separated list of fields to include in the update/replacement document. |
| Upsert | `boolean` | No | `false` | Whether to insert a new document if no documents match the update key. |
| Options | `collection` | No | `{}` | Additional options for insert/update/replace operations. |
| — Date Fields | `string` | No | — | Comma-separated list of fields to parse as MongoDB Date type. |
| — Use Dot Notation | `boolean` | No | `false` | Whether to use dot notation to access nested fields. E.g. "address.city" resolves to { address: { city: value } }. |

#### Document: Find And Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Update Key | `string` | Yes | `_id` | Field name used to match the document to update. Use "_id" for the MongoDB document ID. |
| Fields | `string` | No | — | Comma-separated list of fields to include in the update/replacement document. |
| Upsert | `boolean` | No | `false` | Whether to insert a new document if no documents match the update key. |
| Options | `collection` | No | `{}` | Additional options for insert/update/replace operations. |
| — Date Fields | `string` | No | — | Comma-separated list of fields to parse as MongoDB Date type. |
| — Use Dot Notation | `boolean` | No | `false` | Whether to use dot notation to access nested fields. E.g. "address.city" resolves to { address: { city: value } }. |

#### Document: Find And Replace

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Update Key | `string` | Yes | `_id` | Field name used to match the document to update. Use "_id" for the MongoDB document ID. |
| Fields | `string` | No | — | Comma-separated list of fields to include in the update/replacement document. |
| Upsert | `boolean` | No | `false` | Whether to insert a new document if no documents match the update key. |
| Options | `collection` | No | `{}` | Additional options for insert/update/replace operations. |
| — Date Fields | `string` | No | — | Comma-separated list of fields to parse as MongoDB Date type. |
| — Use Dot Notation | `boolean` | No | `false` | Whether to use dot notation to access nested fields. E.g. "address.city" resolves to { address: { city: value } }. |

#### Document: All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| ObjectId Fields | `string` | No | `_id` | Comma-separated list of field names whose string values should be coerced to ObjectId (e.g. "_id,userId,orderId"). |

#### Search Index: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Index Name (`indexNameRequired`) | `string` | Yes | — | The name of the search index. |
| Index Definition (JSON) | `json` | Yes | `{}` | The search index definition as a JSON object. |
| Index Type | `options` | Yes | `vectorSearch` | The type of search index to create. |
| | | | | Options: `vectorSearch`, `search` |

#### Search Index: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Index Name (`indexNameRequired`) | `string` | Yes | — | The name of the search index. |
| Index Definition (JSON) | `json` | Yes | `{}` | The search index definition as a JSON object. |

#### Search Index: Drop

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Index Name (`indexNameRequired`) | `string` | Yes | — | The name of the search index. |

#### Search Index: List

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Index Name (`indexName`) | `string` | No | — | If provided, only lists indexes matching this name. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Collection | `string` | Yes | — | The MongoDB collection name. Supports expressions. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

The result replaces the item's JSON — the incoming fields do **not** pass through — while binary data on the input item is forwarded. `ObjectId` values in results are converted to strings so they survive JSON serialization.

| Operation | Output |
|-----------|--------|
| `find` | **One item per matching document.** |
| `aggregate` | **One item per pipeline result document.** |
| `insert` | One item — the document as inserted, with `_id` added as a string. |
| `update` | One item carrying the fields that were written. |
| `findOneAndUpdate` | One item — the document as it stands *after* the update. |
| `findOneAndReplace` | One item — the document as it stands *after* the replacement. |
| `delete` | One item carrying `deletedCount`. |
| `listSearchIndexes` | **One item per index**, carrying that index's definition as Atlas reports it. |
| `createSearchIndex` | One item carrying `indexName`. |
| `dropSearchIndex`, `updateSearchIndex` | One item carrying the index name as a key set to `true`. |

An operation that matches nothing still emits one item, with empty JSON, so the branch does not go silent.

A found document looks like the stored document itself:

```json
{
  "_id": "6520f1c3a4e5b6c7d8e9f012",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "status": "active"
}
```

## Usage Examples

- Find all active users in MongoDB
- Insert a new document into a collection
- Update documents matching a filter with $set
- Delete documents matching a query
- Run an aggregation pipeline
- Create an Atlas vector search index

## Example Configuration

Find documents with a filter, sort and projection:

```json
{
  "type": "mongodb",
  "parameters": {
    "resource": "document",
    "operation": "find",
    "collection": "users",
    "query": "{\"status\": \"active\", \"age\": {\"$gte\": 18}}",
    "options": {
      "limit": 100,
      "skip": 0,
      "sort": "{\"createdAt\": -1}",
      "projection": "{\"name\": 1, \"email\": 1, \"status\": 1}"
    }
  }
}
```

Insert selected fields of each incoming item:

```json
{
  "type": "mongodb",
  "parameters": {
    "resource": "document",
    "operation": "insert",
    "collection": "products",
    "fields": "name,price,category,description",
    "options": {
      "dateFields": "createdAt,updatedAt",
      "useDotNotation": false
    },
    "maxConcurrency": 5
  }
}
```

Update a document matched on a business key:

```json
{
  "type": "mongodb",
  "parameters": {
    "resource": "document",
    "operation": "update",
    "collection": "orders",
    "updateKey": "orderId",
    "fields": "status,updatedAt,notes",
    "upsert": false,
    "options": {
      "dateFields": "updatedAt",
      "useDotNotation": true
    }
  }
}
```

Run an aggregation pipeline:

```json
{
  "type": "mongodb",
  "parameters": {
    "resource": "document",
    "operation": "aggregate",
    "collection": "sales",
    "query": "[{\"$match\": {\"date\": {\"$gte\": \"2024-01-01\"}}}, {\"$group\": {\"_id\": \"$category\", \"total\": {\"$sum\": \"$amount\"}}}, {\"$sort\": {\"total\": -1}}]"
  }
}
```

Delete old records:

```json
{
  "type": "mongodb",
  "parameters": {
    "resource": "document",
    "operation": "delete",
    "collection": "logs",
    "query": "{\"createdAt\": {\"$lt\": \"2024-01-01\"}, \"level\": \"debug\"}"
  }
}
```

Replace a whole document, creating it if it is missing:

```json
{
  "type": "mongodb",
  "parameters": {
    "resource": "document",
    "operation": "findOneAndReplace",
    "collection": "configurations",
    "updateKey": "configId",
    "fields": "settings,version,updatedBy",
    "upsert": true,
    "options": {
      "dateFields": "updatedAt",
      "useDotNotation": false
    },
    "maxConcurrency": 1
  }
}
```

Update a document and read back the result:

```json
{
  "type": "mongodb",
  "parameters": {
    "resource": "document",
    "operation": "findOneAndUpdate",
    "collection": "inventory",
    "updateKey": "sku",
    "fields": "quantity,lastRestocked,location",
    "upsert": true,
    "options": {
      "dateFields": "lastRestocked",
      "useDotNotation": false
    }
  }
}
```

Create an Atlas text search index:

```json
{
  "type": "mongodb",
  "parameters": {
    "resource": "searchIndexes",
    "operation": "createSearchIndex",
    "collection": "articles",
    "indexNameRequired": "article_search",
    "indexType": "search",
    "indexDefinition": "{\"mappings\": {\"dynamic\": false, \"fields\": {\"title\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"tags\": {\"type\": \"stringFacet\"}}}}"
  }
}
```

Create an Atlas vector search index:

```json
{
  "type": "mongodb",
  "parameters": {
    "resource": "searchIndexes",
    "operation": "createSearchIndex",
    "collection": "embeddings",
    "indexNameRequired": "vector_index",
    "indexType": "vectorSearch",
    "indexDefinition": "{\"fields\": [{\"type\": \"vector\", \"path\": \"embedding\", \"numDimensions\": 768, \"similarity\": \"cosine\"}]}"
  }
}
```

List the search indexes on a collection:

```json
{
  "type": "mongodb",
  "parameters": {
    "resource": "searchIndexes",
    "operation": "listSearchIndexes",
    "collection": "products",
    "indexName": "product_search"
  }
}
```

Drop a search index:

```json
{
  "type": "mongodb",
  "parameters": {
    "resource": "searchIndexes",
    "operation": "dropSearchIndex",
    "collection": "old_data",
    "indexNameRequired": "deprecated_index"
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Perform CRUD operations on MongoDB documents: find, insert, update, replace, delete, aggregate, and manage Atlas Search indexes.

- **Reads are capped at 10,000 documents** unless you turn on Allow Unbounded. A `Limit` of `0` inside Find's Options means "no limit", which is still subject to that cap until the guard is lifted. Turning it off is a deliberate choice — an unbounded read of a large collection can exhaust the worker's memory.
- **Long-running queries are cut off.** A find, aggregate or write that has not returned within 30 seconds is abandoned and the item fails.
- **Deleting with an empty filter is refused** unless Confirm Delete All is on, because an empty filter matches every document in the collection.
- **Server-side JavaScript is blocked.** Filters and pipelines containing `$where`, `$function`, `$accumulator` or `$accumulatorJs` are rejected before they reach the database.
- **String IDs become ObjectIds automatically.** By default only `_id` is coerced; add more field names to ObjectId Fields when your filters reference other reference columns. A value that is not a valid ObjectId is left as a string, so legacy string IDs still match.
- **`Fields` is mandatory for the three write-by-key operations.** Update, Find And Update and Find And Replace each need a comma-separated field list; the Update Key is added to that list automatically.
- **Use Dot Notation reads nested values.** With it on, a field named `address.city` is pulled out of the nested item structure — for updates the key stays flat so it becomes a targeted `$set` on that path.
- **Find, Aggregate and List fan out** — every returned document becomes its own item.