Cursors

When you run find(), MongoDB does not immediately return all matching documents. Instead, it returns a cursor — a pointer to the result set stored server-side. Documents are fetched in batches as you iterate.

Why Cursors Exist

• Avoid loading millions of documents into memory at once
• Enable streaming/lazy consumption — process one batch at a time
• Allow cancellation mid-way through a large result set
• Support chaining of sort(), limit(), skip() before execution

Cursor in the Shell

// find() returns a cursor — not documents directly
const cursor = db.users.find({ active: true })

// The mongosh shell auto-iterates and prints the first batch
db.users.find({ active: true })
// Prints first 20 documents, then shows "Type 'it' for more"
// "it" iterates the cursor to the next batch

// In Node.js — cursor is not consumed until you iterate
const cursor = collection.find({ active: true })
// Nothing has been sent to the DB yet in terms of data transfer
for await (const doc of cursor) {
  console.log(doc)   // fetches in batches as the loop runs
}

The 10-Minute Inactivity Timeout

MongoDB automatically destroys a cursor that has been inactive (no getMore request) for 10 minutes. If your application pauses iteration for longer than this, the cursor is gone server-side.

// After 10 minutes of inactivity...
cursor.hasNext()
// Error: cursor id N not found (CursorNotFound error)
// The server has already destroyed the cursor

Cursor Exhaustion vs Timeout

MongoDB does not send all documents in one network round-trip. It sends them in batches. The client fetches the next batch automatically as the current one is consumed.

Default Batch Sizes

// The first call to find() triggers the query + returns the first batch
// Subsequent calls to hasNext()/next() consume the local batch, then auto-fetch

// Visualising the flow for 250 documents (default batch size)
// Step 1 — Query sent, first 101 docs returned in response
// Step 2 — Client consumed all 101; driver sends getMore
// Step 3 — Server returns remaining 149 docs (under 16 MB)
// Step 4 — Client consumed all; hasNext() → false; cursor auto-closed

Controlling Batch Size with batchSize()

// Override the default first-batch size
db.users.find().batchSize(50)
// First and subsequent batches will be at most 50 documents each
// Useful to reduce memory footprint per batch

// In Node.js driver
const cursor = collection.find({}).batchSize(100)
for await (const doc of cursor) {
  await processDocument(doc)
}
// Driver automatically issues getMore commands as batches are consumed

hasNext() and next()

// Manual iteration — check then fetch
const cursor = db.users.find({ active: true })

while (cursor.hasNext()) {
  const doc = cursor.next()
  printjson(doc)
}
// hasNext() returns true if there are more documents in current batch or on server
// next() fetches and returns the next document, advancing the cursor

forEach()

// Apply a function to each document — cleaner syntax
db.users.find({ active: true }).forEach(doc => {
  print(doc.name + ": " + doc.email)
})
// forEach automatically iterates the entire cursor
// Cursor is exhausted (and closed) after forEach completes

// In Node.js driver
await collection.find({ active: true }).forEach(async (doc) => {
  await sendEmail(doc.email)
})

toArray()

// Load ALL documents into memory at once
const allUsers = db.users.find({ active: true }).toArray()
// Returns a JavaScript array containing every document
// Fine for small result sets; dangerous for large ones (OOM risk)

// Node.js equivalent
const docs = await collection.find({ status: "active" }).toArray()
console.log(docs.length)

for await...of (Node.js)

// Modern async iteration — best practice in Node.js
const cursor = collection.find({ active: true })

for await (const doc of cursor) {
  await processDoc(doc)
}
// Fetches batches lazily, processes one doc at a time
// Memory-efficient for large result sets
// Cursor is automatically closed when loop completes or throws

Iteration Method Comparison

noCursorTimeout() disables the automatic 10-minute idle timeout for a cursor. This is necessary when processing each document takes a long time and the cursor might go idle between getMore requests.

Usage

// Shell
const cursor = db.heavyCollection.find({}).noCursorTimeout()

// Node.js driver
const cursor = collection.find({}).noCursorTimeout(true)

// Always manually close the cursor when done
try {
  for await (const doc of cursor) {
    await slowProcessing(doc)   // might take minutes per document
  }
} finally {
  await cursor.close()          // REQUIRED — prevents server-side cursor leak
}

When to Use noCursorTimeout

• Batch data migration / ETL jobs with slow per-document processing
• Export operations where each document triggers an external API call
• Long-running aggregation consumers
• Any processing loop where inter-document pause could exceed 10 minutes

Alternatives to noCursorTimeout

// ALTERNATIVE 1 — Periodically refresh the cursor with a small $limit
// If you need to pause, save your position and start a new cursor
let lastId = null
while (true) {
  const filter = lastId ? { _id: { $gt: lastId } } : {}
  const docs = await collection
    .find(filter)
    .sort({ _id: 1 })
    .limit(100)
    .toArray()

  if (docs.length === 0) break

  for (const doc of docs) {
    await slowProcessing(doc)
  }
  lastId = docs[docs.length - 1]._id
}
// No cursor kept open — safe to pause between page fetches

Traditional skip()-based pagination degrades at large offsets because MongoDB must scan and discard the skipped documents. Cursor-based pagination (also called keyset pagination) uses the last seen _id as a bookmark — O(log n) regardless of page number.

The Problem with skip()

// Page 1: skip 0, take 20 — fast (scans 20 docs)
db.products.find().sort({ _id: 1 }).skip(0).limit(20)

// Page 100: skip 1980, take 20 — SLOW (scans 2000 docs, discards 1980)
db.products.find().sort({ _id: 1 }).skip(1980).limit(20)
// Performance degrades linearly with page number
// Also: inserted docs between pages cause duplicates/skips

_id-Based Keyset Pagination

// Page 1 — no bookmark needed
const page1 = db.products
  .find({ status: "active" })
  .sort({ _id: 1 })
  .limit(20)
  .toArray()

// Save the last _id as the bookmark
const lastId = page1[page1.length - 1]._id

// Page 2 — use bookmark, no skip
const page2 = db.products
  .find({ status: "active", _id: { $gt: lastId } })
  .sort({ _id: 1 })
  .limit(20)
  .toArray()
// MongoDB uses the index on _id to jump directly to the right position
// O(log n) regardless of how deep you are in the result set

// Page N — same pattern, carry the bookmark forward
const lastId_N = page2[page2.length - 1]._id
const pageN1 = db.products
  .find({ status: "active", _id: { $gt: lastId_N } })
  .sort({ _id: 1 })
  .limit(20)
  .toArray()

Pagination by Custom Sort Field

// Sort by createdAt — use both createdAt and _id to break ties
const lastDoc = page1[page1.length - 1]

const page2 = db.posts.find({
  $or: [
    { createdAt: { $gt: lastDoc.createdAt } },
    { createdAt: lastDoc.createdAt, _id: { $gt: lastDoc._id } }
  ]
})
.sort({ createdAt: 1, _id: 1 })
.limit(20)
.toArray()
// The $or handles ties on createdAt — no duplicates across pages

skip() vs keyset Comparison

Common Usage Patterns

// Efficient large-dataset processing (Node.js)
const cursor = collection
  .find({ status: "pending" })
  .sort({ createdAt: 1 })
  .batchSize(200)

try {
  for await (const doc of cursor) {
    await processDocument(doc)
  }
} finally {
  await cursor.close()
}

// Count without loading documents
const count = await collection.countDocuments({ status: "active" })
// estimatedDocumentCount() is faster but uses metadata (no filter)
const approx = await collection.estimatedDocumentCount()

// Debug a slow query
db.users.find({ email: /gmail/ }).explain("executionStats")
// Look for: totalDocsExamined vs nReturned
// A good index: nReturned ≈ totalDocsExamined
// Full scan warning: totalDocsExamined >> nReturned

// Read with projection on cursor
db.users
  .find({ active: true })
  .project({ name: 1, email: 1, _id: 0 })
  .sort({ name: 1 })
  .limit(50)