# MongoDB

Find, insert, update, delete and aggregate documents in MongoDB.

## Connect MongoDB

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `mongodb` and choose **MongoDB**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for **Connection string**, **Database**, **Server**, **Port**, **User** and **Password**.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Do things in MongoDB

Add a **MongoDB** step and choose an **Operation**. Choose the row to see the fields of each.

- [MongoDB Operation](https://docs.gorunner.io/apps/mongodb#fields-f-operate): Find · Insert · Update · Delete · Count · Aggregate

To start a workflow from MongoDB, use a [Schedule](https://docs.gorunner.io/apps/schedule), [Webhook](https://docs.gorunner.io/apps/webhook) or [Form](https://docs.gorunner.io/apps/form) trigger.

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A find that matches more than 50,000 documents fails the step. Set a **Limit** to read a page at a time.
- In **Filter**, **Update**, **Pipeline**, **Sort** and **Projection**, a value from `{{ }}` is a plain value: write operators in the field itself. A value that carries an operator fails the step, and so does a value in **Filter** that resolves to nothing. A whole field that is one earlier step’s output, such as `{{steps.x.filter}}`, may hold operators, but not code the database runs.
- GoRunner Cloud reaches servers on the public internet only. On a self-hosted installation, an admin can allow private addresses with `WORKFLOW_PRIVATE_NETWORKS`.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, MongoDB is `pieceId: "mongodb"` with `actionId: "operate"`, set by `operation`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### MongoDB › MongoDB Operation

Run a document operation against a collection.

### Find

- **Collection · Required**: The collection name.
- **Filter · Optional**: Query filter, such as {"status":"active"}. An _id given as a 24-char hex string is matched as an ObjectId. MongoDB Extended JSON is understood here and in Update, Document(s) and Pipeline: {"$oid":"…"} is an ObjectId, {"$date":"2026-10-01T00:00:00Z"} a date. A value from {{ }} is matched as a plain value: write operators in the field itself, as a value carrying one is refused, and so is one that resolves to nothing. The exception is a whole Filter that is one earlier step's output ({{steps.x.filter}}), a query that step built.
- **Limit · Optional**: Max documents to return (0 = no limit). Default: 0.
- **Skip · Optional**: Number of documents to skip (offset pagination). Default: 0.
- **Sort · Optional**: Sort spec, such as {"created_at":-1}.
- **Projection · Optional**: Fields to include/exclude, such as {"password":0} or {"name":1,"email":1}.

### Insert

- **Collection · Required**: The collection name.
- **Document(s) · Optional**: A document object, or an array of documents to insert.

### Update

- **Collection · Required**: The collection name.
- **Filter · Optional**: Query filter, such as {"status":"active"}. An _id given as a 24-char hex string is matched as an ObjectId. MongoDB Extended JSON is understood here and in Update, Document(s) and Pipeline: {"$oid":"…"} is an ObjectId, {"$date":"2026-10-01T00:00:00Z"} a date. A value from {{ }} is matched as a plain value: write operators in the field itself, as a value carrying one is refused, and so is one that resolves to nothing. The exception is a whole Filter that is one earlier step's output ({{steps.x.filter}}), a query that step built.
- **Update · Optional**: Update spec, such as {"$set":{"status":"done"}}.
- **Update all matching documents · Optional**: Off (default) updates only the first match; on updates every match. Off by default.
- **Upsert · Optional**: Insert a new document if no match is found. Off by default.

### Delete

- **Collection · Required**: The collection name.
- **Filter · Optional**: Query filter, such as {"status":"active"}. An _id given as a 24-char hex string is matched as an ObjectId. MongoDB Extended JSON is understood here and in Update, Document(s) and Pipeline: {"$oid":"…"} is an ObjectId, {"$date":"2026-10-01T00:00:00Z"} a date. A value from {{ }} is matched as a plain value: write operators in the field itself, as a value carrying one is refused, and so is one that resolves to nothing. The exception is a whole Filter that is one earlier step's output ({{steps.x.filter}}), a query that step built.
- **Delete all matching documents · Optional**: On (default) deletes every match; off deletes only the first. On by default.

### Count

- **Collection · Required**: The collection name.
- **Filter · Optional**: Query filter, such as {"status":"active"}. An _id given as a 24-char hex string is matched as an ObjectId. MongoDB Extended JSON is understood here and in Update, Document(s) and Pipeline: {"$oid":"…"} is an ObjectId, {"$date":"2026-10-01T00:00:00Z"} a date. A value from {{ }} is matched as a plain value: write operators in the field itself, as a value carrying one is refused, and so is one that resolves to nothing. The exception is a whole Filter that is one earlier step's output ({{steps.x.filter}}), a query that step built.

### Aggregate

- **Collection · Required**: The collection name.
- **Pipeline · Optional**: Aggregation pipeline, such as [{"$group":{"_id":"$status","n":{"$sum":1}}}].

Source: https://docs.gorunner.io/apps/mongodb