QueryCursor

A QueryCursor is a concurrency primitive for processing query results one document at a time. A QueryCursor fulfills the Node.js streams3 API, in addition to several other mechanisms for loading documents from MongoDB one at a time.

QueryCursors execute the model's pre find hooks before loading any documents from MongoDB, and the model's post find hooks after loading each document.

Unless you're an advanced user, do not instantiate this class directly. Use Query#cursor() instead.

Adds a cursor flag. Useful for setting the noCursorTimeout and tailable flags.

Marks this cursor as closed. Will stop streaming and subsequent calls to next() will error.

Execute fn for every document in the cursor. If fn returns a promise, will wait for the promise to resolve before iterating on to the next one. Returns a promise that resolves when done.

Example:

// Iterate over documents asynchronously
Thing.
  find({ name: /^hello/ }).
  cursor().
  eachAsync(async function (doc, i) {
    doc.foo = doc.bar + i;
    await doc.save();
  })

Registers a transform function which subsequently maps documents retrieved via the streams interface or .next()

Example:

// Map documents returned by `data` events
Thing.
  find({ name: /^hello/ }).
  cursor().
  map(function (doc) {
   doc.foo = "bar";
   return doc;
  })
  on('data', function(doc) { console.log(doc.foo); });

// Or map documents returned by `.next()`
const cursor = Thing.find({ name: /^hello/ }).
  cursor().
  map(function (doc) {
    doc.foo = "bar";
    return doc;
  });
cursor.next(function(error, doc) {
  console.log(doc.foo);
});

Get the next document from this cursor. Will return null when there are no documents left.

The options passed in to the QueryCursor constructor.

Rewind this cursor to its uninitialized state. Any options that are present on the cursor will remain in effect. Iterating this cursor will cause new queries to be sent to the server, even if the resultant data has already been retrieved by this cursor.

Returns an asyncIterator for use with for/await/of loops. You do not need to call this function explicitly, the JavaScript runtime will call it for you.

Example:

// Works without using `cursor()`
for await (const doc of Model.find([{ $sort: { name: 1 } }])) {
  console.log(doc.name);
}

// Can also use `cursor()`
for await (const doc of Model.find([{ $sort: { name: 1 } }]).cursor()) {
  console.log(doc.name);
}

Node.js 10.x supports async iterators natively without any flags. You can enable async iterators in Node.js 8.x using the --harmony_async_iteration flag.

Note: This function is not if Symbol.asyncIterator is undefined. If Symbol.asyncIterator is undefined, that means your Node.js version does not support async iterators.