:Compatibility changes in MongoDB 4.2

MMAPv1-specific options

MongoDB 4.2 removes the following MMAPv1-specific options:

MMAPv1-specific parameters

MongoDB 4.2 removes the following MMAPv1-specific parameters:

• newCollectionsUsePowerOf2Sizes

• replIndexPrefetch

MMAPv1-specific command

MongoDB 4.2 removes the MMAPv1-specific command touch.

MMAPv1-specific options for commands and methods

MongoDB 4.2 removes the following MMAPv1-specific options:

• noPadding and usePowerOf2Sizes from the collMod command.

• verbose from the collStats command.

• flags from the create command.

• paddingFactor, paddingBytes, and preservePadding from the db.createCollection() command.

MongoDB 4.2 ignores the MMAPv1-specific option async from the fsync command.

Deprecation of the group command

Starting from MongoDB 4.2, MongoDB deprecates the group command (deprecated in MongoDB 3.4) and its mongo shell helper function db.collection.group().

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

Deprecation of the eval command

Starting from MongoDB 4.2, MongoDB deprecates the eval command (deprecated in MongoDB 3.0).

The mongo shell helper functions db.eval() and db.collection.copyTo() can only be run when you connect to an instance that runs MongoDB 4.0 or earlier.

Deprecation of the copydb and clone commands

Starting from MongoDB 4.2, MongoDB deprecates the copydb and clone commands. The mongo shell helper functions db.copyDatabase() and db.cloneDatabase() can only be run when you connect to an instance that runs MongoDB 4.0 or earlier.

Instead, use mongodump and mongorestore (along with the mongorestore options --nsFrom and --nsTo) or a driver for writing a script.

mongodump --archive --db=test | mongorestore --archive  --nsFrom='test.*' --nsTo='examples.*'

Deprecation of the parallelCollectionScan command

Starting from MongoDB 4.2, MongoDB deprecates the parallelCollectionScan command.

Removal of the maxScan option

Starting from MongoDB 4.2, MongoDB removes the maxScan option from the find command and the mongo shell helper function cursor.maxScan(). Use the maxTimeMS option of the find command or the mongo shell method cursor.maxTimeMS() instead.

Deprecation of the geoNear command

Starting from MongoDB 4.2, MongoDB deprecates the geoNear command. Use the $geoNear aggregation stage instead.

For the $geoNear stage, its options are similar to those in the deprecated geoNear command with the following exceptions:

• The output of the deprecated geoNear command includes the dis field that contains the distance information.

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

• The deprecated 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 output of the deprecated geoNear command includes avgDistance and maxDistance.

  You can use the aggregation pipeline to return avgDistance and maxDistance. Specially, include the group stage to calculate avgDistance and maxDistance after the geoNear stage.

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

Deprecation of the repairDatabase command

Starting from MongoDB 4.2, MongoDB deprecates the repairDatabase command, the mongo shell helper function db.repairDatabase(), and the repairDatabase permission.

Alternatives:

• To compress data on a mongod, use the compact command.

• To rebuild indexes on a standalone instance, use the reIndex command or its helper function db.collection.reIndex().

• To restore data for a standalone instance, use mongod --repair.

Deprecation of the getPrevError command

Starting from MongoDB 4.2, MongoDB deprecates the getPrevError command and its mongo shell helper function db.getPrevError().

Deprecation of the cloneCollection command

Starting from MongoDB 4.2, MongoDB deprecates the cloneCollection command and its mongo shell helper function db.cloneCollection().

Instead, use the mongoexport and mongoimport commands or a drive for writing a script.

Deprecation of PlanCache commands

Starting from MongoDB 4.2, MongoDB deprecates the following items:

• The PlanCache.getPlansByQuery() method and the planCacheListPlans command.

  To get the cached query plans for a shape, use the $planCacheStats aggregation stage instead.

• The PlanCache.listQueryShapes() method and the planCacheListQueryShapes command.

  To list the cached query shapes, use the $planCacheStats aggregation stage instead.

$out stage limits

Removal of the limit and num options from $geoNear

Starting from MongoDB 4.2, MongoDB removes the limit and num options from $geoNear, along with the default limits of 100 documents. To limit the results of $geoNear, use the $geoNear stage with the $limit stage.

For example, the following sample aggregation where the $geoNear stage includes the num option is no longer valid in MongoDB 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 command in the following format.

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

Availability

Starting from MongoDB 4.2, change streams are available regardless of whether the "majority" read concern level supports them.

Prior to MongoDB 4.2, change streams are available only if "majority" read concern support is enabled (default).

Default collation

Starting from MongoDB 4.2, change streams use simple binary comparisons unless an explicit collation is provided. Prior to MongoDB 4.2, change streams created for a single collection db.collection.watch() inherit the default collation of the collection.

Resume token modification

Starting from MongoDB 4.2, if a change stream aggregation pipeline modifies the _id field of an event, change streams throw an exception.

FIPS mode

Starting from MongoDB 4.2, MongoDB removes the --sslFIPSMode option from the following programs:

• mongodump

• mongoexport

• mongofiles

• mongoimport

• mongorestore

• mongostat

• mongotop

The preceding programs use FIPS-compliant connections when the FIPS mode is enabled in the mongod and mongos instances.

Extended JSON v2

--query option

Starting from MongoDB 4.2, the --query option for mongodump and mongoexport must be in the Extended JSON v2 format (Relaxed or Strict Mode), including enclosing field names and operators in quotes. Example:

mongoexport -d=test -c=records -q='{ "a": { "$gte": 3 }, "date": { "$lt": { "$date": "2016-01-01T00:00:00.000Z" } } }' --out=exportdir/myRecords.json

Prior to MongoDB 4.2, the --query option uses the Extended JSON v1 format where field names and operators do not need to be enclosed in quotes.

mongoexport -d=test -c=records -q='{ a: { $gte: 3 }, date: { $lt: { "$date": "2016-01-01T00:00:00.000Z" } } }' --out=exportdir/myRecords.json

Primary step down

Starting from MongoDB 4.2, replSetStepDown (or replSetReconfig that causes a step down) no longer closes all client connections. However, writes that are still in progress are killed.

Prior to MongoDB 4.0, replSetStepDown closes all client connections during the step down.

ROLLBACK state

Starting fromMongoDB 4.2, MongoDB kills all user operations when a member enters the ROLLBACK state.

Indexes

{
   "ok" : 0,
   "errmsg" : "Index with name: x_1 already exists with a different name",
   "code" : 85,
   "codeName" : "IndexOptionsConflict"
}

{
   "numIndexesBefore" : 2,
   "numIndexesAfter" : 2,
   "note" : "all indexes already exist",
   "ok" : 1
}

min()/max()

Starting from MongoDB 4.2, when specifying min()/max() for a db.collection.find() operation, you must explicitly specify an index for min()/max() unless the find() query is an equality condition on the _id field { _id: }.

Similarly, when specifying min/max in the find command, you must also explicitly specify the hint for the min/max index.

Prior to MongoDB 4.0, you can choose whether to explicitly specify the min()/max() index regardless of the query conditions. If you do not explicitly specify a hint in MongoDB 4.0 and earlier versions, MongoDB selects an index based on the index boundaries. However, if multiple indexes exist on the same fields but with different sorting orders, the index selection may be ambiguous.

CurrentOp

When reporting "getmore" operations, the $currentOp aggregation stage, the currentOp command, and db.currentOp() now return the originatingCommand field as a nested field of the new cursor field. Prior to MongoDB 4.2, originatingCommand is a top-level field in the "getmore" document.

Server status

The opcounters and opcountersRepl metrics returned by serverStatus and db.serverStatus are now 64-bit integers (NumberLong) instead of 32-bit integers (NumberInt).

Logging

• When logging to syslog, the message text format now includes the component information. Example:

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

  In versions earlier than MongoDB 4.2, syslog message texts do not include the component information. Example:

  ... [repl writer worker 1] Unsupported modification to roles collection ...

• Starting from MongoDB 4.2, log retrieving commands truncate any events that contain more than 1,024 characters. In versions earlier than MongoDB 4.2, the commands truncate after 512 characters.

• Starting from MongoDB 4.2, MongoDB records the debug log level. For example, if the log level is 2, MongoDB records D2.

  Prior to MongoDB 4.2, MongoDB log messages only specifies D as the debug level.

Wire protocol

Starting from MongoDB 4.2, MongoDB no longer supports OP_COMMAND and the corresponding OP_COMMANDREPLY write protocol.

Killcursors changes

Removal of the AsyncRequestsSenderUseBaton parameter

Starting from MongoDB 4.2, MongoDB removes the AsyncRequestsSenderUseBaton parameter and always enables performance enhancement controlled by this parameter.

Stricter validation of the count syntax

Starting from MongoDB 4.2, MongoDB implements a stricter validation of option names for the count command. If an unknown option name is specified, the command reports an error.

Prior to MongoDB 4.2, MongoDB ignores invalid option names.

Causally consistent sessions

Starting from MongoDB 4.2, the following commands no longer support afterClusterTime:

• dbHash command

• mapReduce command

• validate command

Therefore, these operations cannot be associated with causally consistent sessions.

Removal of the fastmodinsert metric

MongoDB 4.2 removes the deprecated fastmodinsert metric from various outputs, including the explain executionStats and the profiler output.

Map-Reduce

Starting from MongoDB 4.2, MongoDB deprecates the following items:

• The map-reduce option to create a sharded collection and the support for the use of the sharded option for map-reduce. To output to a sharded collection, create a sharded collection first. MongoDB 4.2 also deprecates the replacement of an existing sharded collection.

• Explicit specification of the nonAtomic: false option for map-reduce.

Balancer status and auto splitting

Starting from MongoDB 4.2:

• The balancerStart command and mongo shell helper methods sh.startBalancer() and sh.setBalancerState(true) also enable auto splitting.

  To disable auto splitting, use sh.disableAutoSplit().

• The balancerStop command and mongo shell helper methods sh.stopBalancer() and sh.setBalancerState(false) also disable auto splitting.

  To enable auto splitting, use sh.enableAutoSplit().

The sh.enableBalancing(namespace) and sh.disableBalancing(namespace) methods no longer affect auto splitting.

Lock diagnostics reports

Starting from MongoDB 4.2, MongoDB reports information about the ReplicationStateTransition lock.

Additionally, MongoDB 4.2 separates ParallelBatchWriterMode lock information from global lock information. Earlier versions report ParallelBatchWriterMode lock information as part of the global lock information.

For operations that report lock information, see:

• The serverStatus command and db.serverStatus() method.

• The $currentOp aggregation pipeline stage, the currentOp command, and the db.currentOp() method.

Validation of query, sorting, or projection argument for findAndModify

Starting from MongoDB 4.2 (including V4.0.12+ and 3.6.14+), the findAndModify command and its associated mongo shell methods report an error when the specified query, sorting, or projection argument is not a document.

pRIOR TO MongoDB 4.2, the current operation considers a non-document query or sorting argument as an empty document {}.

DropDatabase and movePrimary

Starting from MongoDB 4.2:

• If you drop a database and create another database with the same name, you must perform one of the following operations:

  • Restart all mongos instances and shard members, or

  • Run the flushRouterConfig command on all mongos instances and shard members before reading from or writing to the created database.

• If you use the movePrimary command to move unsharded collections, you must perform one of the following operations:

  • Restart all mongos instances and shard members, or

  • Run the flushRouterConfig command on all mongos instances and shard members before reading from or writing to those collections.

This ensures that mongos and shard members flush their metadata caches. Otherwise, reads may miss data and writes might not go to the correct shard. Manual intervention is required for restoration.

Prior to MongoDB 4.2, you need only to restart mongos instances or run the flushRouterConfig command on mongos instances.

Removal of system.indexes and system.namespaces collections

Starting from MongoDB 4.2, MongoDB removes the system.indexes and system.namespaces collections (deprecated in MongoDB 3.0).

With the removal of these collections, built-in roles clusterManager, clusterMonitor, dbAdmin, read, restore, and other roles that inherit from these roles no longer are granted permissions to access the system.indexes and system.namespaces collections.

Necessarity of clearing data directories for downgrading arbiter

The arbiter data files in MongoDB 4.2 are incompatible with MongoDB 4.0. To downgrade from MongoDB 4.2 to 4.0, delete the arbiter data files first. An error may occur if you use data files in MongoDB 4.2 to run a arbiter in MongoDB 4.0.

Sharded collections and document replacement

Starting from MongoDB 4.2:

• A document replacement operation such as replaceOne() or update() (when used with a replacement document) first attempts to locate a shard by using the query filter. If the operation cannot locate a shard by using the query filter, it attempts to utilize the replacement document. Prior to MongoDB 4.2, a document replacement operation only attempts to locate a shard by using the replacement document.

• MongoDB deprecates the save() method. Use the insertOne() or replaceOne() methods instead. The save() method cannot be used on sharded collections that are not sharded by-_id. If you use the save() method, an error occurs.

• For a document replacement operation with the setting upsert: true on a sharded collection, the filter must include an equality match on the shard key for the sharded collection.