MongoDB Cursor

The MongoDB cursor is a pointer that references the documents of the collection returned by the find() method.

The cursor is used to access the documents. By default, the cursor iterates automatically, but can also be iterated manually by the user.

MongoDB Cursor Example

In this example, we are working with:

Database: gfg

Collection: student

Documents: Three documents contain the details of the students

Here, we use the following query to display all the documents present in the student collection

db.student.find().pretty()

This find() method returns a cursor containing all documents present in the student collection.

How to Manually Iterate a Cursor in MongoDB

There are different ways to manually iterate a cursor in MongoDB. Users can manually iterate a cursor in MongoDB by:

Assigning Cursor to a Var Keyword

In MongoDB, the find() method returns the cursor, now to access the document we need to iterate the cursor.

To iterate a cursor manually, simply assign the cursor return by the find() method to the var keyword Or JavaScript variable. 

Note: In the Mongo shell, if the cursor is not assigned to a var keyword then the Mongo shell automatically iterates the cursor up to 20 documents. If a cursor is inactive for 10 min then the MongoDB server will automatically close that cursor.

Syntax:

var name = db.collection_name.find()
name

Example :

var mycursor = db.student.find({studentId:3}).pretty()
mycursor

Here, we iterate the cursor manually to find the document whose studentId is 3. So, we assigned the cursor returned by the find() method to the JavaScript variable(i.e. mycursor).

Using the next() Method

We can also use the next() cursor method to access the next document. Let us discuss with the help of an example:

Example:

var mycursor = db.student.find({studentId:{$gt:1}});
> while(mycursor.hasNext()){
... print(tojson(mycursor.next()));
... }

In this example, studentId 2 and 3 documents are displayed because, in the first line, we exclusively took the cursor to start with the studentId > 1. So it skipped 1st document and retrieved the remaining documents. Here, the print(tojson()) method is used to display the result. You can also use printjson() method to display the result.

Using the forEach() method

We can also use the forEach() method to iterate the cursor. This function applies a JavaScript function to each document from the cursor.

Syntax:

db.collection.find().forEach(<function>)

Example:

var mycursor = db.student.find({studentId:3}).pretty()
mycursor.forEach(printjson)

Here, first we store the cursor returned by the find() method(i.e., studentId:3) in the mycursor variable. Now, we use the forEach() method to iterate the cursor and display the resultant document using printjson.

Using Iterator Index

In Mongo shell, you are allowed to iterate the cursor and display the resultant document in the array using the toArray() method.

Syntax:

cursor.toArray()

Example:

var mycursor = db.student.find().pretty()
var docs = mycursor.toArray()
var resultdoc = docs[0]
resultdoc

Here, first, we assign the returned cursor to the var keyword(i.e. mycursor), in next we create an array from the resultant cursor using the toArray() method and assign the result to the var keyword(i.e. docs). Now we access the documents according to their index e.g. var resultdoc = docs[0], here we display a document whose index is 0.

Alternate Method:

You can also this method to access a document using index on the cursor.  

var mycursor = db.student.find().pretty()
var resultdoc = mycursor[0]
resultdoc

MongoDB Cursor Methods

Some of the commonly used cursor methods are:

Count cursor:

In order to get the correct documents, we need to know how many documents are present for that collection. To get that we can use the count() method which returns the total number of documents present in the given collection.

Syntax:

db.collection_name.find().count()
or 
db.collection_name.count()

Example: 

db.student.find().count()

Here, we find the total number of documents present in the student collection using the count() method.

Cursor Limit:

The limit() method helps to fetch limited records from a collection. Suppose we have multiple documents, but we want to have the topmost or only 2 documents, then by using the limit() method, we can achieve that.

Syntax:

db.collection_name.find().limit(<number>)

Example:

db.student.find().limit(2).pretty()

Here, we only display the first two documents from the student collection.

Cursor size:

The cursor.size() method will be helpful to return a count of the number of documents that got as the output from the db.collection.find() query after applying any cursor.skip() and cursor.limit() methods. Hence, it is mentioned as it has applied cursor.skip() and cursor.limit() methods.

Syntax:

db.collection_name.find().size()

Example:

db.student.find({studentId:1}).size()

Cursor sort:

Usually while verifying documents, if the output is in sorted order, either in ascending or descending order, it will be easier. So we use the sort() method to sort the documents. If you want to sort the documents in ascending, then set the value of the field to 1 and in descending, then set -1.

Syntax:

db.collection_name.find().sort(<sort>)

Example:

db.student.find().sort({studentId:-1}).pretty()

Here, we sort all the documents present in the student collection in descending order.

Cursor.toArray():

In order to have an array that contains all documents returned by the cursor, we can use the toArray() method.

Syntax:

db.collection_name.find().toArray()

Example:

db.student.find().toArray()

Cursor.next:

The next() method is used to return the next document in a cursor. Usually, it will return the first document as that will be the result of the first document in the cursor.

Syntax:

db.student.find().next()

Example:

db.student.find().next()

Here, the next() method returns the first document from the collection.

Additional Cursor Methods in MongoDB

Cursor Methods modify the way that the underlying query is executed.

Conclusion

Cursors in MongoDB reference the documents of a collection returned by the find() method. A cursor is used to iterate over documents when the query result is returned.

In this guide on MongoDB cursors, we have covered important cursor topics like MongoDB cursor examples, cursor methods, and how to manually iterate the cursor in MongoDB.

priyarajtt

Follow

Improve