[DOCS-13346] Documentation of maxTimeMS on getMore is incorrect Created: 16/Jan/20  Updated: 30/Oct/23

Status: Closed
Project: Documentation
Component/s: manual
Affects Version/s: None
Fix Version/s: Server_Docs_20231030

Type: Bug Priority: Major - P3
Reporter: Patrick Freed Assignee: Unassigned
Resolution: Won't Do Votes: 0
Labels: docs-query
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Duplicate
Participants:
Days since reply: 1 year, 14 weeks, 2 days ago
Epic Link: DOCSP-1769

 Description   

Description

The current documentation for the getMore command describes maxTimeMS in the following way:

Optional. Specifies a time limit in milliseconds for processing operations on a cursor. If you do not specify a value for maxTimeMS, operations will not time out. A value of 0 explicitly specifies the default unbounded behavior.

MongoDB terminates operations that exceed their allotted time limit using the same mechanism as db.killOp(). MongoDB only terminates an operation at one of its designated interrupt points.

This is an accurate description of the option as it pertains to other commands, but for getMore specifically maxTimeMS behaves differently.

Firstly, the option is only applicable to getMore commands associated awaitData cursors, and the server will return an error indicating so if it is used in a getMore against a non-awaitData cursor.
e.g.

MongoDB Enterprise repl0:PRIMARY> db.runCommand({getMore: NumberLong("8625890266383683105"), collection: 'test', maxTimeMS: 5000})
{
	"operationTime" : Timestamp(1579212441, 1),
	"ok" : 0,
	"errmsg" : "cannot set maxTimeMS on getMore command for a non-awaitData cursor",
	"code" : 2,
	"codeName" : "BadValue",
	"$clusterTime" : {
		"clusterTime" : Timestamp(1579212441, 1),
		"signature" : {
			"hash" : BinData(0,"AAAAAAAAAAAAAAAAAAAAAAAAAAA="),
			"keyId" : NumberLong(0)
		}
	}
}

Secondly, the option determines how long the server will wait for new data to be available to an awaitData cursor before returning an empty batch. It is unrelated to limiting how long an operation is allowed to run for before returning an error (this is what the option is used for in other commands).

Thirdly, if no maxTimeMS is specified in a getMore associated with an awaitData cursor, it will wait for data server-side for a default amount of time, which I believe is 1 second. The command will return after that with an empty batch if no new data was received.

For context, this option is typically specified by users via the maxAwaitTimeMS option in the drivers, most often in the context of change streams. For example, here is the Java driver's documentation of the option if used with a find command.

Scope of changes

Impact to Other Docs

MVP (Work and Date)

Resources (Scope or Design Docs, Invision, etc.)



 Comments   
Comment by Education Bot [ 31/Oct/22 ]

Hello! This ticket has been closed due to inactivity. If you believe this ticket is still important, please reopen it and leave a comment to explain why. Thank you!

Generated at Thu Feb 08 08:07:33 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.