Description

Summary: maxScan is now maxTimeMS

The maxScan option is intended to guard against runaway queries or unexpected bad query plans by limiting the number of keys that the IXSCAN query execution stage is willing to examine. However, this option has since been superseded by maxTimeMS. The maxTimeMS mechanism is more complete in that it applies to most commands, whereas maxScan is only available for find. Furthermore, maxScan can be easily be confused with limit. Limit is a logical component of the query language, whereas maxScan is better understood as a command directive in the vein of maxTimeMS, readConcern, writeConcern, readPreference, and so on.

When maxScan is used, we should occasionally log the following message:

Support for the maxScan option has been deprecated. Instead, use maxTimeMS. See http://dochub.mongodb.org/core/4.0-deprecate-maxScan.

Scope of changes (files that need work and how much)

• make sure the 4.0 compatibility page includes a mention to this.

The following reference pages need to be updated to instruct the user to use maxTimeMS instead of maxScan.

• https://docs.mongodb.com/manual/reference/operator/meta/maxScan/
• https://docs.mongodb.com/manual/reference/method/cursor.maxScan/
• https://docs.mongodb.com/manual/reference/method/js-cursor/index.html
• https://docs.mongodb.com/manual/reference/command/find/index.html
• https://docs.mongodb.com/manual/reference/method/index.html
• https://docs.mongodb.com/manual/reference/operator/meta/orderby/index.html
• https://docs.mongodb.com/manual/reference/operator/query-modifier/index.html

Consider adding content (new page or to an existing page) to explain how to add a time limit to a query, as per this note:

Some users may also be interested in how to add a limit to a query; we've had users confuse maxScan and limit in the past.

Impact to other docs outside of this product

• Update dochub to point to the compatibility page: http://dochub.mongodb.org/core/4.0-deprecate-maxScan

Resources (e.g. Scope Docs, Invision)

• engineering ticket: https://jira.mongodb.org/browse/SERVER-32953

---------------------------------

Documentation Request Summary:

• The 4.0 compatibility changes need to mention this deprecation.
• We need to make the dochub link in the logs (http://dochub.mongodb.org/core/4.0-deprecate-maxScan) link to a page with the deprecation notice.
• Reference pages need to be updated with the deprecation. References pages are https://docs.mongodb.com/manual/reference/operator/meta/maxScan/ and https://docs.mongodb.com/manual/reference/method/cursor.maxScan/.

Users should be instructed to use maxTimeMS instead of maxScan. Some users may also be interested in how to add a limit to a query; we've had users confuse maxScan and limit in the past.