MongoDB node

The MongoDB node reads from and writes to a MongoDB collection — look up a record, insert a submission, update a document, delete one. It's an I/O node that connects to your database, so it carries an error port.

Component id: flowrunner/mongodb.

How it works

The node connects to a database and runs one operation against one collection. Connection details and the query are all templated so they can pull in secrets and flow data:

• connectionRef, database, collection — each resolves ${env.X} and ${secrets.X}. The connection URI must start with mongodb:// or mongodb+srv://.
• query — a JSON string with {{namespace.field}} placeholders, filled from the flow's refs before parsing. It must parse to a JSON object.

Connections are pooled and reused per URI, so repeated calls to the same database don't reopen a client.

Operations

operation	What it does	Result stored
findOne (default)	Returns the first matching document	the document object (or null)
find	Returns matching documents, capped at 100	an array of documents
insertOne	Inserts the query object as a new document	{ insertedId }
updateOne	Query is { filter, update }; applies the update	{ matchedCount, modifiedCount }
deleteOne	Deletes the first matching document	{ deletedCount }

The result is stored under resultVar (default result). If the result is a plain object it's stored as-is; a scalar or array is wrapped as { value: <result> }. So a find array reads as result.value, while a findOne document reads as result.<field>.

Query placeholders

The query template uses double-brace placeholders — {{start.email}} — which are substituted from refs (string values are inserted safely into the JSON). This is distinct from the ${...} syntax used elsewhere.

{ "email": "{{start.email}}" }

For updateOne, supply both a filter and an update:

{ "filter": { "id": "{{start.id}}" }, "update": { "$set": { "seen": true } } }

Config

Field	Required	Description
connectionRef	Yes	The MongoDB connection URI (mongodb://… or mongodb+srv://…). Resolves ${env.X} / ${secrets.X} — keep the real URI in a secret.
database	Yes	Database name. Resolves ${env.X} / ${secrets.X}.
collection	Yes	Collection name. Resolves ${env.X} / ${secrets.X}.
operation	No (default findOne)	One of find, findOne, insertOne, updateOne, deleteOne.
query	No	JSON template with {{ref}} placeholders. Must resolve to a JSON object. Empty means {}.
resultVar	No (default result)	Variable the operation result is stored under.

Ports

Port	Followed when
next	The operation succeeded.
error	The operation failed — bad URI, missing database/collection, invalid query JSON, or a database error. The message is written to error.message, and if error is wired the flow routes there.

WARNING

A find returns at most 100 documents. If you need more, narrow the query or paginate — the node will not return the full collection.

Example

Look up a user by the email submitted with the request:

MongoDB  operation: findOne
  connectionRef: ${secrets.MONGO_URI}
  database: app   collection: users
  query: { "email": "{{start.email}}" }
  resultVar: user
# read later as: user.name, user.plan  (or null if no match)

Insert a contact-form submission:

MongoDB  operation: insertOne
  connectionRef: ${secrets.MONGO_URI}   database: app   collection: messages
  query: { "email": "{{start.email}}", "message": "{{start.message}}" }
  resultVar: saved
# read later as: saved.insertedId

TIP

Never paste a connection string with a password straight into connectionRef. Store it as a workspace secret and reference it with ${secrets.MONGO_URI}.

See also

• HTTP node
• Secrets
• Submissions store
• Error handling in flows