findOne 与 find：理解游标

MongoDB provides two primary methods for reading documents from a collection:

• findOne(filter, projection) — retrieves the first document matching the filter and returns it as a plain document object (or null if nothing matches)
• find(filter, projection) — retrieves all matching documents and returns a cursor, a lazy iterator that streams results from the server one batch at a time

Understanding when to use each method—and how cursors work—is fundamental to writing efficient MongoDB queries.

findOne() is the simplest way to retrieve a single document. It returns the first document that matches the filter, or null if no document matches. If multiple documents match, MongoDB returns whichever it encounters first in its internal order—add a .sort() before calling this if you need a specific one.

Common use cases for findOne: looking up a user by email, fetching a product by SKU, or checking if a record exists. Because it returns a plain object rather than a cursor, you use the result directly without iteration.

A cursor is a pointer to the result set of a query. When you call find(), MongoDB does not immediately transfer all matching documents to the client. Instead it opens a server-side cursor and sends documents in batches (default 101 documents per batch). The client fetches the next batch only when the current batch is exhausted.

This design is crucial for memory efficiency. If a query matches 10 million documents and you loaded them all at once, you would crash the client. With a cursor, you process documents one batch at a time, keeping memory usage constant regardless of result set size.

Node.js driver cursors support multiple iteration patterns. The most modern approach is for await...of (async iteration), which cleanly handles backpressure and error handling. Alternatives include cursor.toArray() which loads all results into memory—convenient but dangerous for large result sets.

Always close cursors when done if you break out of iteration early (e.g., after finding what you need). An open cursor holds resources on the MongoDB server. Use cursor.close() explicitly, or rely on for await...of which auto-closes the cursor on loop completion or error.

Internally, the cursor protocol works in two phases:

1. The initial find command returns the first batch (default 101 documents or 16 MB, whichever comes first)
2. Each subsequent batch is fetched via a getMore command using the cursor ID

You can customize the batch size with cursor.batchSize(n). A smaller batch size reduces memory usage on both sides but requires more network round-trips. A larger batch size is more efficient for large sequential scans. The default is usually optimal—only tune it for specific workloads.

By default, MongoDB cursors time out after 10 minutes of inactivity on the server side. If your processing of each batch takes longer than that, the cursor will be killed and you will get a CursorNotFound error when you try to fetch the next batch.

For long-running operations, set noCursorTimeout: true or use a session to keep the cursor alive. However, be aware that noCursorTimeout holds a server cursor open indefinitely—always explicitly close these cursors when done to avoid resource leaks.

The cursor returned by find() supports a fluent API—you chain methods to modify the query before iteration begins. Order matters for readability but not execution (MongoDB sends all modifiers together):

• .sort({ field: 1 }) — sort direction
• .limit(n) — max documents
• .skip(n) — skip first n results
• .projection({ field: 1 }) — select fields
• .hint({ index: 1 }) — force a specific index
• .maxTimeMS(ms) — abort if query takes too long

A special cursor type called a tailable cursor works only on capped collections. Unlike normal cursors that close when all results are consumed, a tailable cursor blocks and waits for new documents, similar to Unix's tail -f command on a log file.

Tailable cursors were the original mechanism for real-time data streaming in MongoDB before Change Streams were introduced. They are still useful for lightweight log tailing on capped collections where Change Streams are overkill.

Use this rule of thumb for choosing between findOne and find:

• Use findOne when: you expect exactly one result (lookup by unique key), you only need to check existence, or you want the simplest code for a single-record API endpoint
• Use find when: the query may return zero, one, or many results; you are building a list endpoint; you need cursor control (batchSize, maxTimeMS); or you are processing results without loading all into memory

Avoid find({}).toArray() on large collections—it loads all results into memory. Process with for await...of instead.

Appending .explain('executionStats') to a cursor shows how MongoDB executes the query instead of returning documents. The output reveals:

• winningPlan.stage: IXSCAN (uses an index) or COLLSCAN (full scan—bad for large collections)
• nReturned: how many documents were returned
• totalDocsExamined: how many documents MongoDB looked at to find results (should be close to nReturned if an index is used)
• executionTimeMillis: total execution time

Regularly running explain() on your critical queries is the foundation of MongoDB performance tuning.

When findOne or find().toArray() return documents with ObjectId fields, those ObjectIds need special handling before returning them in a JSON API response. JSON.stringify serializes an ObjectId as an object {} (losing the value) in older driver versions, or as its string representation in newer ones.

The safest pattern is to explicitly call .toString() on any ObjectId fields in a mapping function before sending to the client. Clients then send the ID back as a string, and you convert it with new ObjectId(idString) in the server before querying.

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

In this lesson you learned: findOne returns a single document directly while find returns a cursor that lazily streams results in batches to avoid memory issues with large result sets, cursors support a fluent chain API—.sort(), .limit(), .skip(), .maxTimeMS()—which MongoDB sends as a single optimized query, and explain('executionStats') reveals whether a query uses an index (IXSCAN) or a full collection scan (COLLSCAN). Next up we dive into querying nested fields and arrays with dot notation.