All nodes/Data/Database

DB Find One

First document matching the filter (or null).

Try it

When to use it

Reach for this node when exactly one document is expected: a customer card by user_id, an order by its number, a setting by key. It returns a ready object rather than an array, so nothing downstream needs a loop or an index. When several documents match and it matters which one you get, use db_find with a sort and a limit of 1 — there is no sort here.

How it works

The Filter port carries both the trigger and the filter; an object arriving over the edge replaces the configured filter, an empty trigger keeps it. The Filter and Projection fields are JSON editors: {{ … }} is not expanded there, so build a dynamic filter with a template emitting a JSON object as a string, or with code_javascript returning an object, and feed it to the port.

The output has two fields: doc — the document itself or null — and found, whether it was there. A missing document is a successful run, not a failure: draw the “no such thing” branch with if on {{ nodes.<id>.output.found }}.

Common mistakes

• Expecting an error when nothing matches. The node succeeds with found: false; without a check downstream, null travels on and some other node fails later, in an unexpected place.
• Reading fields before checking found. Branch on found first, then use {{ nodes.<id>.output.doc.<field> }}.
• Reading “first” as “newest”. The order is not defined — it is whatever the store returned. For the freshest document use db_find with [["created_at", -1]] and a limit of 1.
• A filter that matches several documents. You get one of them, and the next run may hand you a different one. Filter on a field that is genuinely unique.
• Mixing the projection. Including (1) and excluding (0) fields in one projection is rejected. With an including projection _id always comes back.

Inputs

Outputs

Configuration