findAndModify

findAndModify is an atomic single-document operation in MongoDB that combines querying, updating or removing a document in one step. It locates a document matching a query and either updates its fields, removes it, or inserts a new document if no match is found (upsert). The operation can also apply a sort to determine which document to act on when multiple candidates match.

Parameters typically include: query (the filter), sort (to choose among matches), update (the update operators to apply), remove (boolean), new (boolean to return the modified or pre-modified document), upsert (boolean), fields (projection), and collation. When new is true, the operation returns the document after applying the update; when false, it returns the document as it was before the update. If remove is true, the matched document is deleted and the original document is returned (if any). Upsert may cause a new document to be created by applying the update to an empty document; the exact shape depends on the update and schema.

Since it's a single-document, atomic operation, it avoids race conditions within that document, but it does not scale to multi-document updates. In practice, findAndModify has been deprecated in favor of the findOneAndUpdate, findOneAndReplace, and findOneAndDelete family of methods in modern MongoDB drivers. These newer methods provide similar functionality with clearer semantics and better driver support.

Usage today: prefer findOneAndUpdate to increment counters, modify fields, or replace documents; use findOneAndDelete to remove and return the deleted document; and use upsert as needed to create a new document when absent.