Navigation
This is an upcoming (i.e. in progress) version of the manual.

Compatibility Changes in MongoDB 4.2 (Development Series 4.1.x)

MongoDB 4.2 is currently in development as part of the 4.1 development series.

Warning

While the 4.1-dev-series are available, these versions of MongoDB are for testing purposes only and not for production use.

Removal of MMAPv1 Storage Engine

MongoDB 4.2 removes support for the deprecated MMAPv1 storage engine.

If your 4.0 deployment uses MMAPv1, you must change the deployment to WiredTiger Storage Engine before upgrading to MongoDB 4.2. For details, see:

MMAPv1 Specific Configuration Options

MongoDB removes the following MMAPv1 specific configuration options:

Configuration File Setting Command-line Option
storage.mmapv1.journal.commitIntervalMs  
storage.mmapv1.journal.debugFlags mongod --journalOptions
storage.mmapv1.nsSize mongod --nssize
storage.mmapv1.preallocDataFiles mongod --noprealloc
storage.mmapv1.quota.enforced mongod --quota
storage.mmapv1.quota.maxFilesPerDB mongod --quotaFiles
storage.mmapv1.smallFiles mongod --smallfiles
storage.repairPath mongod --repairpath
replication.secondaryIndexPrefetch mongod --replIndexPrefetch

MMAPv1 Specific Parameters

MongoDB removes the following MMAPv1 parameters:

  • newCollectionsUsePowerOf2Sizes
  • replIndexPrefetch

MMAPv1 Specific Command

MongoDB removes the MMAPv1 specific touch command.

MMAPv1 Specific Options for Commands and Methods

MongoDB removes the MMAPv1 specific options:

Removed or Deprecated Commands and Methods

Remove Support for the group Command

Starting in version 4.2, MongoDB removes the group command (deprecated since version 3.4) and its mongo shell helper db.collection.group().

Use db.collection.aggregate() with the $group stage instead.

Remove Support for the eval Command

Starting in version 4.2, MongoDB removes the eval command. eval command has been deprecated since version 3.0.

The associated MongoDB 4.2 mongo shell methods db.eval() and db.collection.copyTo() can only be run when connected to MongoDB 4.0 or earlier.

Remove Support for the copydb and clone Commands

Starting in version 4.2, MongoDB removes the deprecated copydb command and clone command.

The corresponding mongo shell helpers db.copyDatabase() and db.cloneDatabase() can only be run when connected to MongoDB 4.0 or earlier.

As an alternative, users can use mongodump and mongorestore or write a script using the drivers.

Remove Support for the parallelCollectionScan Command

Starting in version 4.2, MongoDB removes the parallelCollectionScan command.

Remove maxScan

MongoDB removes the deprecated option maxScan for the find command and the mongo shell helper cursor.maxScan(). Use either the maxTimeMS option for the find command or the helper cursor.maxTimeMS() instead.

Remove Support for the geoNear Command

Starting in version 4.2, MongoDB removes the geoNear command. Use the $geoNear aggregation stage instead.

The options for $geoNear are similar to the removed geoNear command with the following exceptions:

  • The removed geoNear command includes in its output a field named dis that included the distance information.

    For the $geoNear stage, specify the distance field name in distanceField.

  • The removed geoNear command accepts a boolean value for the includeLocs option to include the loc field.

    For the $geoNear stage, specify the location field name in includeLocs.

  • The removed geoNear command includes the avgDistance and maxDistance of the returned results.

    You can use the aggregation pipeline to return the avgDistance and maxDistance as well. Specifically, after the $geoNear stage, include a $group stage to calculate the avgDistance and maxDistance:

    db.places.aggregate([
       { $geoNear: { near: <...>, distanceField: "dis", includeLocs: "loc", spherical: true, ... } },
       { $group: { _id: null, objectsLoaded: { $sum: 1 }, maxDistance:
             { $max: "$dis" }, avgDistance: { $avg: "$dis" } } }
    ])
    

Remove Support for the repairDatabase Command

Starting in version 4.2, MongoDB removes the repairDatabase command and its mongo shell helper db.repairDatabase().

As alternatives:

Deprecate Support for cloneCollection

MongoDB deprecates the cloneCollection command and its mongo shell helper db.cloneCollection()

As alternatives,

Aggregation

$out Stage Restrictions

$out and Views

The view definition pipeline cannot include the $out stage. If you already have an existing view that includes the $out stage, you can no longer create new views from this existing view.

For existing views that include the $out stage, you should either drop and recreate the views without the $out stage or use replace the view definition with a new pipeline that does not contain the $out stage.

$out and $lookup

The $lookup stage cannot include the $out stage in its nested pipeline field for the joined collection.

$out and linearizable Read Concern Level

The $out stage cannot be used in conjunction with read concern "linearizable".

$out and Explain

You cannot run the db.collection.explain() method (or the explain command) in executionStats mode or allPlansExecution mode if the aggregation pipeline contains the $out stage.

If the aggregation pipeline contains the $out stage, to view executionStats or allPlansExecution information, run explain without the $out stage in order to return explain results for the preceding stages.

Alternatively, you can run explain in queryPlanner mode for an aggregation pipeline that contains the $out stage.

Remove limit and num Options from $geoNear

Starting in version 4.2, MongoDB removes the limit and num options for the $geoNear stage as well as the default limit of 100 documents. To limit the results of $geoNear, use the $geoNear stage with the $limit stage.

For example, the following aggregation where the $geoNear stage contains the num option is no longer valid in 4.2.

db.places.aggregate([
   {
     $geoNear: {
        near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] },
        distanceField: "distance",
        num: 5,                 // Not supported in 4.2
        spherical: true
     }
   }
])

Instead, you can rewrite the aggregation to the following pipeline:

db.places.aggregate([
   {
     $geoNear: {
        near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] },
        distanceField: "distance",
        spherical: true
     }
   },
   { $limit: 5 }
])

General Changes

Indexes

  • MongoDB implements a stronger restriction on running reIndex command and db.collection.reIndex() shell helper against a collection in a sharded cluster by disallowing reIndex and db.collection.reIndex() on a mongos.
  • MongoDB removes the --noIndexBuildRetry command-line option and the corresponding storage.indexBuildRetry option.

CurrentOp

  • When reporting on "getmore" operations, the $currentOp aggregation stage, along with currentOp command and the db.currentOp() helper, now returns the originatingCommand field as a nested field in the new cursor field. In previous versions, the originatingCommand was a top-level field for the associated "getmore" document. See also 4.2 currentOp Changes.

Server Status

Logging

  • When logging to syslog, the format of the message text includes the component. For example:

    ...  ACCESS   [repl writer worker 5] Unsupported modification to roles collection ...
    

    Previously, the syslog message text did not include the component. For example:

    ... [repl writer worker 1] Unsupported modification to roles collection ...
    
  • Starting in MongoDB 4.2, the getLog command truncates any event that contains more than 1024 characters. In earlier versions, getLog truncates after 512 characters.

Wire Protocol

  • MongoDB no longer supports the deprecated internal OP_COMMAND and the corresponding OP_COMMANDREPLY wire protocol.

killCursors Privilege

Starting in MongoDB 4.2, users can always kill their own cursors, regardless of whether the users have the privilege to killCursors. As such, the killCursors privilege has no effect in MongoDB 4.2+.

In MongoDB 3.6.3 through MongoDB 4.0.x, users required the killCursors privilege in order to kill their own cursors when access control is enabled.

4.2 Feature Compatibility

Some features in 4.2 require not just the 4.2 binaries but the featureCompatibilityVersion (fCV) set to 4.2. These features include:

  • Multi-document transactions for sharded clusters.
  • Removal of Index Key Limit for MongoDB versions with fCV set to 4.2+. In concert with the removal of this limit, the failIndexKeyTooLong parameter has no effect for MongoDB versions with fCV set to 4.2+ and only applies for MongoDB 2.6 through MongoDB versions with fCV set to "4.0" or earlier.
  • Removal of Index Name Length for MongoDB versions with fCV set to 4.2+.
  • New internal format for unique indexes. The new format applies to both existing unique indexes as well as newly created/rebuilt unique indexes.
  • Starting in MongoDB 4.2, users can no longer use the query filter $type: 0 as a synonym for $exists:false. To query for null or missing fields, see Query for Null or Missing Fields.