MongoDB Cursors

• In MongoDB, a cursor is an object that allows iteration over query results.
• The database returns results from the find() operation using a cursor.
• When find() returns multiple documents, a cursor points to these results instead of returning them all at once.

Why Use Cursors?

• Enable lazy loading, where MongoDB fetches documents as needed, optimizing performance and memory.
• Retrieve data in batches.
• Prevent memory leaks.
• Enables handling long operations safely.

Creating a Cursor with the Shell

• First, put documents into a collection.
• Then, make a query on those.
• Assign the results to a local variable, using var for local scope:

    > for(i=0; i<100; i++) {
    ... db.collection.insertMany({x : i});
    ... }
    > var cursor = db.collection.find();

• The advantage of assigning results to a local variable is the ability to look at one result at a time.
• If results are stored in a global variable or no variable, the MongoDB shell iterates automatically.
• Storing results in a global variable also displays the first couple of documents.

Iterating Through Results

• Use the next() method on the cursor.
• hasNext() checks if another result exists.
• Standard loop structure for results:

    > while (cursor.hasNext()) {
    ... obj = cursor.next();
    ... // do stuff
    ...}

• cursor.hasNext() validates that the next result exists
• cursor.next() fetches it.

Limits, Skips, and Sorts

• Common query options include limiting results, skipping, and sorting.
• Limit returns a set number of documents.
• Skip jumps documents.
• Sort sorts documents.
• All these options must be added before a query is sent to the database.
• Chain the limit() function onto your call to find() to set a limit.
• For example, to only return three results, use db.c.find().limit(3)
• If there are fewer than three documents matching the query in the collection, the number of matching documents will be returned.
• Limit sets an upper, not a lower, limit.
• skip works similarly to a limit, for example: db.c.find().skip(3)
• This skips the first three matching documents and returns the rest of the matches.
• If there are fewer than three documents, skip will return nothing.
• The sort function takes an object of key/value pairs, where the keys are key names, and the values are the sort directions.
• Use 1 for ascending and -1 for descending.
• With multiple given keys, the results will be sorted in that order.
• Sort ascending by "username" and descending by "age":

db.c.find().sort({username : 1, age : -1})

• The sort, skip, and limit methods can be combined.
• This is often handy for pagination.
• For example, to take 50 results sorted by price from high to low:

db.stock.find({"desc" : "mp3"}).limit(50).sort({"price" : -1})

• If that person clicks Next Page, add a skip to the query.
• To skip over the first 50 matches:

db.stock.find({"desc" : "mp3"}).limit(50).skip(50).sort({"price" : -1})

Finding a Random Document

• A common problem is how to get a random document from a collection.
• A simple (but inefficient) solution is to:
  • Count the number of documents
  • Make a find
  • Skip a random number of documents between 0 and the size of the collection:

    > // do not use
    > var total = db.foo.count()
    > var random = Math.floor(Math.random()*total)
    > db.foo.find().skip(random).limit(1)

• This is highly inefficient.
• A more efficient solution is to add an extra random key to each document when its inserted.
• To do this in the shell, use the Math.random() function, which creates a random number between 0 and 1:

    > db.people.insert({"name" : "joe", "random" : Math.random()})
    > db.people.insert({"name" : "john", "random" : Math.random()})
    > db.people.insert({"name" : "jim", "random" : Math.random()})

• To actually find a random document:
  • Calculate a random number
  • Use that as a query criteria

    > var random = Math.random()
    > result = db.foo.findOne({"random": {"$gt" : random}})
    > if (result == null) {
    ... result = db.foo.findOne({"random": {"$lt" : random}})
    ... }

Getting Consistent Results

• No documents are skipped or duplicated in the results.
• The data does not change midway through operation.
• You should get a "stable snapshot" of the data as at the start of read.
• The general solution to this problem is to snapshot your query.
• For example, db.foo.find().snapshot() instead of db.foo.find()
• Prevent MongoDB from returning the same document more than once if the collection was being modified during the query.
• Ensure that the query results were not affected by index changes or document movement .

Immortals Cursors

• There are two sides to a cursor:
  • The client-facing cursor.
  • The database cursor that the client-side represents.
• On the server side, a cursor takes up memory and resources.
• Once a cursor runs out of results or the client sends a message telling it to die, the database can free the resources it was using.
• Freeing these resources is important, so the database can use them for other things.
• Ensuring cursors can be freed quickly is a design concern.
• An immortal cursor is a cursor that does not expire automatically after a period of inactivity.
• Even if the user hasn't iterated through all the results, the cursor is still in scope after 10 minutes of inactivity, and the database cursor will automatically "die."

    > const cursor = db.myCollection.find().noCursorTimeout();

• Since this cursor won't time out, make sure to close it manually when done:

    > cursor.close();