Uploaded image for project: 'Documentation'
  1. Documentation
  2. DOCS-13346

Documentation of maxTimeMS on getMore is incorrect

    XMLWordPrintable

Details

    • Bug
    • Status: Open
    • Major - P3
    • Resolution: Unresolved
    • None
    • None
    • manual

    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.)

      Attachments

        Activity

          People

            Unassigned Unassigned
            patrick.freed@mongodb.com Patrick Freed
            Divjot Arora Divjot Arora
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

              Created:
              Updated:
              2 years, 24 weeks, 1 day ago