maxTimeMS

maxTimeMS is a database operation option used by MongoDB to impose a maximum execution time for certain commands. It is specified as a nonnegative integer representing milliseconds. When set, the server will attempt to interrupt the operation once the time limit is reached and return an error rather than completing the operation. The typical error is MaxTimeMSExpired.

The option can be applied to several commands and operations, including find queries, aggregation pipelines, and certain update or delete operations. In the shell, a find can be limited with db.collection.find(query).maxTimeMS(5000). For aggregations, you can pass a maxTimeMS option in the command, e.g., db.collection.aggregate(pipeline, { maxTimeMS: 5000 }). Many drivers expose maxTimeMS as an option in the command constructor or a query modifier.

Behavior: The timer runs on the server as the operation executes. If the limit is reached, MongoDB aborts the operation, closes any open cursors, and returns an error to the client. The time limit is subject to the server’s clock granularity and does not guarantee exact cancellation; there may be a short delay between expiration and interruption.

Best practices: Use maxTimeMS to protect against long-running queries that could degrade performance or exhaust resources. It is not a substitute for proper indexing or query design. Developers should test with realistic workloads and monitor the occurrence of MaxTimeMSExpired errors.

Limitations: Some operations may ignore maxTimeMS or behave differently across versions or drivers; consult the specific driver and server documentation for details.