What does cursor.batchSize() change about how a MongoDB find() returns documents?

## find() returns a cursor, not a result set When you run `db.c.find(filter)`, the server does not materialize and ship every matching document. It creates a **cursor** — server-side state identifying the query and its progress — and returns a first batch of documents plus a cursor id. The driver then issues `getMore` commands against that id to pull further batches, transparently, as your loop advances. When the cursor is exhausted the server returns a cursor id of zero and releases the state. This streaming design is what lets a query over a billion documents run in constant client memory. It is also why cursors have lifecycle concerns — batches, timeouts, and explicit closing — that a "give me the rows" API does not. ## Default batching For a `find()`, the first batch contains up to 101 documents, or fewer if the batch would exceed the 16 MB maximum BSON message size. Subsequent `getMore` batches are not capped at 101; they are bounded by that 16 MB message size. So with small documents you get a modest first batch and then much larger ones; with 1 MB documents you get roughly a dozen or so per batch regardless of counts. These defaults are deliberately chosen so that the common case — a query returning a screenful of results — completes in one round trip, while a large scan streams efficiently. ## What batchSize actually controls `cursor.batchSize(n)` asks the server to put at most `n` documents in each batch, including the first. It is purely a **transport tuning knob**: - **Smaller batches**: more `getMore` round trips, therefore more latency overhead on a slow or distant link, but less memory materialized per fetch and a smaller amount of work discarded if the client stops early. - **Larger batches**: fewer round trips and better throughput on a fast link, at the cost of holding more documents in memory on both server and client per fetch, and a longer pause between touching the cursor. The 16 MB message ceiling still applies: a `batchSize` larger than what fits is silently satisfied with fewer documents. ## batchSize is not limit This is the confusion the question exists to catch. `limit(n)` bounds the **total** number of documents the query will ever return; `batchSize(n)` bounds documents **per batch**. `db.c.find().limit(5).batchSize(10)` returns five documents in total. `db.c.find().limit(1000).batchSize(10)` returns a thousand documents across roughly a hundred round trips. When a `limit` is smaller than the batch size, the server sends only up to the limit and can close the cursor immediately, which is why a small `limit` is the right way to say "I only want a few" — never a small `batchSize`. ## When tuning is justified Leave the default alone unless you have a specific reason. Real ones: - **Large documents.** If documents are hundreds of kilobytes, a default batch can be a big allocation on both sides. A smaller `batchSize` smooths memory use. - **Slow per-document processing.** If each document triggers an external call taking seconds, a large batch means a long gap between `getMore` calls, and the cursor sits idle on the server — which interacts badly with the idle-cursor timeout. Smaller batches touch the cursor more often, though the more robust fix is to stop holding a long-lived cursor at all and page with a range query instead. - **Low-latency first result.** A UI that wants to render the first rows fast may prefer a small first batch, though a `limit` usually expresses that better. - **Aggregation cursors.** The aggregate command has its own `cursor: { batchSize: n }` option with the same meaning; note that `{ batchSize: 0 }` there means "return the cursor without any documents in the first reply", which is used to start a pipeline and stream everything through `getMore`. ## Iteration in practice In `mongosh`, iterating with `hasNext()`/`next()` or `forEach()` walks the cursor and fetches batches automatically; `toArray()` drains it fully into client memory, which defeats the point of streaming for a large result. Drivers expose the same duality — an async iterator that streams, and a `toArray`-style helper that buffers. Choosing `toArray()` on an unbounded query is a far more common production incident than any `batchSize` mistake. Cursors should be closed when you stop early. Driver iterators close on exhaustion or when their scope ends; if you break out of a loop manually, close explicitly so the server can drop the state rather than waiting for the idle timeout. ## What to say in an interview Say that `find()` streams through a cursor, that the first batch defaults to 101 documents with later batches bounded by the 16 MB message size, that `batchSize` moves documents per round trip while `limit` caps the total, and that the honest default advice is not to tune it without a measured reason.