MongoDB Cursor

The find() method returns a cursor object which can be used to iterate the result.

The following example gets the cursor object and assign it to a variable.

Example: Cursor Object

var cursor = db.employees.find()

The cursor object has the following important methods:

Method	Description
cursor.count()	Returns the total number of documents referenced by a cursor.
cursor.forEach()	Iterates the cursor to apply a JavaScript function to each document from the cursor.
cursor.hasNext()	Returns true if a cursor can iterate further to return more documents.
cursor.isExhausted()	Returns true if the cursor is closed and there are no remaining objects in the batch.
cursor.itcount()	Counts the number of documents remaining in a cursor.
cursor.limit()	Specify the maximum number of documents the cursor will return.
cursor.map()	Applies a function to each document visited by the cursor and collects the return values from successive applications of the function into a Cursor object.
cursor.max()	Specifies the exclusive upper bound for a specific index in order to constrain the results of find().
cursor.min()	Specifies the inclusive lower bound for a specific index in order to constrain the results of find().
cursor.next()	Returns the next document from the result set.
cursor.pretty()	Display result in the readable format.
cursor.readConcern()	Specifies a level of isolation for read operations.
cursor.skip()	Skips the specified number of document for pagination.
cursor.sort()	Specifies the order in which the query returns matching documents.
cursor.toArray()	Returns an array that contains all the documents from a cursor.

Note that cursor methods are depends on the drivers you are using in your application. Visit mongosh cursor methods for more information.

The following example shows how to use next() method in mongosh shell.

humanResourceDB> var cur = db.employees.find()

humanResourceDB> cur.next()
{ 
    _id:1,
    firstName: "John",
    lastName: "King",
    email: "[email protected]",
    salary: 5000
}
humanResourceDB> cur.next()
{ 
    _id:2,
    firstName: "Sachin",
    lastName: "T",
    email: "[email protected]",
    salary: 8000
}
humanResourceDB> cur.next()
{ 
    _id:3,
    firstName: "James",
    lastName: "Bond",
    email: "[email protected]",
    salary: 7500
}
humanResourceDB> cur.next()
{ 
    _id:4,
    firstName: "Steve",
    lastName: "J",
    email: "[email protected]",
    salary: 7000

}
humanResourceDB> cur.next()
{ 
    _id:5,
    firstName: "Kapil",
    lastName: "D",
    email: "[email protected]",
    salary: 4500

}
humanResourceDB> cur.next()
{ 
    _id:6,
    firstName: "Amitabh",
    lastName: "B",
    email: "[email protected]",
    salary: 7000
}
humanResourceDB> cur.next()
null
humanResourceDB> cur.next()
MongoCursorExhaustedError: Cursor is exhausted

In the above example, if the cursor reaches at the end, it will MongoCursorExhaustedError: Cursor is exhausted. Use the hasNext() method before calling the next() to prevent an error.

Use cursor.forEach() method to iterate the result. Specify the built-in printjson method to print the result, as shown below.

humanResourceDB> var cur = db.employees.find()

humanResourceDB> cur.forEach(printjson)
{ 
    _id:1,
    firstName: "John",
    lastName: "King",
    email: "[email protected]",
    salary: 5000
}
{ 
    _id:2,
    firstName: "Sachin",
    lastName: "T",
    email: "[email protected]",
    salary: 8000
}
{ 
    _id:3,
    firstName: "James",
    lastName: "Bond",
    email: "[email protected]",
    salary: 7500
}
{ 
    _id:4,
    firstName: "Steve",
    lastName: "J",
    email: "[email protected]",
    salary: 7000

}
{ 
    _id:5,
    firstName: "Kapil",
    lastName: "D",
    email: "[email protected]",
    salary: 4500

}
{ 
    _id:6,
    firstName: "Amitabh",
    lastName: "B",
    email: "[email protected]",
    salary: 7000
}

Learn how to sort documents using cursor.sort() method in the next chapter.