# MongoDB

> Source: https://docs.clonepartner.com/connectors/mongodb/

<!-- sources: src/connectors/mongodb.ts, src/connectors/mongodb-bson.ts, references/envoy/connectors.md -->

# MongoDB

The `mongodb` connector queries, aggregates, and writes documents in a MongoDB database.

## When to use it

Use `mongodb` as a document-store source or destination, or as a lookup and staging store when your data is already in MongoDB. Filters and aggregation pipelines use native MongoDB query syntax.

## Configuration

| Key | Type | Required | Default | Description |
|---|---|---|---|---|
| `connection_string` | string | Yes | — | MongoDB connection string (stored as a secret) |
| `database` | string | Yes | — | Database name |

## Methods

| Method | Arguments | Returns | Behavior |
|---|---|---|---|
| `find` | `collection` (required), `filter`, `projection`, `sort`, `limit`, `skip` | array | Streams documents from the driver cursor one at a time |
| `find_one` | `collection` (required), `filter`, `projection` | object | Returns a single document |
| `count` | `collection` (required), `filter` | object | Returns `{ count }` of matching documents |
| `insert_one` | `collection` (required), `data` (required) | object | Inserts a single document |
| `update_one` | `collection` (required), `filter` (required), `update` (required), `upsert` | object | Updates one document; `upsert: true` inserts when nothing matches |
| `update_many` | `collection` (required), `filter` (required), `update` (required), `upsert` | object | Updates all matching documents |
| `delete_one` | `collection` (required), `filter` (required) | object | Deletes one document |
| `delete_many` | `collection` (required), `filter` (required) | object | Deletes all matching documents |
| `aggregate` | `collection` (required), `pipeline` (required) | array | Streams aggregation results from the driver cursor |
| `list_collections` | — | array | Returns `{ name, type }` for every collection and view in the database |

## Example

```yaml
name: export_open_tickets
connectors:
  source:
    type: mongodb
steps:
  - name: read_tickets
    type: call_method
    config: |
      {
        "connector": "source",
        "method": "find",
        "args": {
          "collection": "tickets",
          "filter": { "status": "open" },
          "sort": { "created_at": -1 }
        }
      }
```

The matching `connectors.yaml` entry for CLI runs:

```yaml
source:
  type: mongodb
  config:
    connection_string: ${MONGODB_CONNECTION_STRING}
    database: helpdesk
```

## Behavior notes

- Filters, update documents, and pipelines are coerced from Extended JSON before execution: `{ "$oid": "..." }` values become `ObjectId` instances (invalid hex fails with `Invalid ObjectId hex`), and `$date` values become `Date` objects. This lets YAML/JSON task configs express BSON types.
- `find` and `aggregate` return async iterators over the driver cursor, so large result sets stream with backpressure instead of buffering.
- `update_one` and `update_many` take a MongoDB update document (for example `{ "$set": { ... } }`) in `update`.

## Related

- [Connectors overview](/connectors/) — all compiled connector types
- [Data Explorer](/using/data-explorer/) — interactively query a MongoDB Connector
- [Reading and writing data](/building/reading-and-writing-data/) — calling connector methods from steps