- MongoDB CRUD Operations >
- MongoDB CRUD Concepts >
- Read Operations >
- Cursors
Cursors¶
On this page
In the mongo
shell, the primary method for the read
operation is the db.collection.find()
method. This method
queries a collection and returns a cursor to the returning
documents.
To access the documents, you need to iterate the cursor. However, in
the mongo
shell, if the returned cursor is not assigned to a
variable using the var
keyword, then the cursor is automatically
iterated up to 20 times [1] to print up to the
first 20 documents in the results.
For example, in the mongo
shell, the following read
operation queries the inventory
collection for documents that have
type
equal to 'food'
and automatically print up to the first 20
matching documents:
To manually iterate the cursor to access the documents, see Iterate a Cursor in the mongo Shell.
[1] | You can use the DBQuery.shellBatchSize to
change the number of iteration from the default value 20 . See
Executing Queries for more information. |
Cursor Behaviors¶
Closure of Inactive Cursors¶
By default, the server will automatically close the cursor after 10
minutes of inactivity or if client has exhausted the cursor. To
override this behavior, you can specify the noTimeout
flag in your
query using cursor.addOption()
; however, you should either
close the cursor manually or exhaust the cursor. In the
mongo
shell, you can set the noTimeout
flag:
See your driver documentation for
information on setting the noTimeout
flag. For the mongo
shell, see cursor.addOption()
for a complete list of
available cursor flags.
Cursor Isolation¶
Because the cursor is not isolated during its lifetime, intervening write operations on a document may result in a cursor that returns a document more than once if that document has changed. To handle this situation, see the information on snapshot mode.
Cursor Batches¶
The MongoDB server returns the query results in batches. Batch size
will not exceed the maximum BSON document size. For most queries, the first batch
returns 101 documents or just enough documents to exceed 1 megabyte.
Subsequent batch size is 4 megabytes. To override the default size of
the batch, see batchSize()
and
limit()
.
For queries that include a sort operation without an index, the server must load all the documents in memory to perform the sort before returning any results.
As you iterate through the cursor and reach the end of the returned
batch, if there are more results, cursor.next()
will perform
a getmore operation
to retrieve the next batch.
To see how many documents remain in the batch as you iterate the
cursor, you can use the objsLeftInBatch()
method, as
in the following example:
Cursor Information¶
The db.serverStatus()
method returns a document that includes
a cursors
field with the following information:
- number of timed out cursors since the last server restart
- number of open cursors with the option
DBQuery.Option.noTimeout
set to prevent timeout after a period of inactivity - number of “pinned” open cursors
- total number of open cursors
Consider the following example which calls the
db.serverStatus()
method and accesses the cursors
field:
The result is the following document:
See also