cursor.allowDiskUse()
On this page
Definition
cursor.allowDiskUse()
Important
mongosh Method
This is a
mongosh
method. This is not the documentation forNode.js
or other programming language specific driver methods.In most cases,
mongosh
methods work the same way as the legacymongo
shell methods. However, some legacy methods are unavailable inmongosh
.For the legacy
mongo
shell documentation, refer to the documentation for the corresponding MongoDB Server release:For MongoDB API drivers, refer to the language specific MongoDB driver documentation.
allowDiskUse()
allows MongoDB to use temporary files on disk to store data exceeding the 100 megabyte system memory limit while processing a blocking sort operation. If MongoDB requires using more than 100 megabytes of system memory for the blocking sort operation, MongoDB returns an error unless the query specifiescursor.allowDiskUse()
.allowDiskUse()
has the following form:db.collection.find(<match>).sort(<sort>).allowDiskUse()
See Sort and Index Use for more information on blocking sort operations.
Compatibility
This method is available in deployments hosted in the following environments:
MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
Note
This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
Behavior
Supports Large Non-Indexed Sorts Only
cursor.allowDiskUse()
has no effect on sort operations
answered using an index or non-indexed ("blocking") sort operations
which require less than 100 megabytes of memory. For more complete
documentation on blocking sorts and sort index use, see
Sort and Index Use.
To check if MongoDB must perform an blocking sort, append
cursor.explain()
to the query and check the
explain results. If the query plan
contains a SORT
stage, then MongoDB must perform an
blocking sort operation subject to the 100 megabyte memory limit.
Example
Consider a collection sensors
with only the default index on
_id
. The collection contains documents similar to the
following:
{ "sensor-name" : "TEMP-21425", "sensor-location" : "Unit 12", "reading" : { "timestamp" : Timestamp(1580247215, 1), "value" : 212, "unit" : "Fahrenheit" } }
The following operation includes a cursor.sort()
on the
field reading.timestamp
. The operation also includes
cursor.allowDiskUse()
to support the sort operation.
db.sensors.find({"sensor-location" : "Unit 12"}). sort({"reading.timestamp" : 1}). allowDiskUse()
Since reading.timestamp
is not included in an index, MongoDB
must perform a blocking sort operation to return results in the
requested sort order. By specifying allowDiskUse()
,
MongoDB can process the sort operation even if it requires more than
100 megabytes of system memory. If allowDiskUse()
was omitted and the operation required more than 100 megabytes of
system memory, MongoDB would return an error.