:Compatibility changes in MongoDB 3.4

To view the official MongoDB compatibility change documentation, visit Legacy Documentation.

Changes to sharded cluster instances

Compatibility of collection renaming with initial sync

If a collection, as a synchronization source, is renamed during initial sync, the initial sync process fails and is restarted, thereby avoiding potential data corruption risks. For more information, see SERVER-26117.

The following pperations involve collection renaming:

• The renameCollection command: such as the db.collection.renameCollection() method.

• The $out stage in an aggregation operation, such as using the db.collection.aggregate() method or the aggregate command with the $out stage.

• The out option in MapReduce, such as using the db.collection.mapReduce() method or the mapReduce command with the out option specified.

• The convertToCapped command that is used to convert a regular collection to a capped collection.

When you upgrade from MongoDB 3.2.11 or earlier to 3.4, initial sync may fail if encountering a collection renaming operation.

Priior to MongoDB v3.2.11, an initial sync process continues when encountering a collection renamimng operation that may corrupt data. For more information, see SERVER-4941.

Deprecated operations

Collection and index specifications

db.createCollection( "myCappedCollection", { cappedtypo: true, size: 5242880 } )

General compatibility changes

• Adjustment of namespace limits: Starting from MongoDB 3.4, database names no longer support the $ symbol.

  Note

  Before upgrading to MongoDB 3.4, you must delete all databases whose names contain $.

• Removal of the textSearchEnabled parameter. Starting from MongoDB 2.6, MongoDB enables text search by default.

• Removal of the mongosniff tool: Starting from MongoDB 3.4, mongosniff is replaced by the tool mongoreplay that provides more powerful features and supports more flexible network traffic capture and analysis.

• Changes to the $project aggregation stage behavior: If the $project stage returns an empty document (no fields preserved or added), an error is reported.

• Counting issues of hints and sparse indexes: If you use a hint() that specifies a sparse index when counting documents in a collection (with an empty query predicate), the sparse index may cause inaccurate counting results.

  db.collection.insert({ _id: 1, y: 1 } );
  db.collection.createIndex( { x: 1 }, { sparse: true } );
  
  db.collection.find().hint( { x: 1 } ).count();

  To obtain the correct counting results, do not specify a sparse index in a hint() when counting all documents in a collection.

  db.collection.find().count();
  
  db.collection.createIndex({ y: 1 });
  db.collection.find().hint({ y: 1 }).count();

  Prior to MongoDB 3.4, hints are ignored if the use of sparse indexes cause the missing count results.

Changes to user role permissions

Starting from MongoDB 3.4, the permissions of the following built-in roles no longer apply to the local and config databases:

The following built-in roles have permissions on the local and config databases:

• clusterManager

• clusterMonitor

• backup

• restore

Features incompatible with later versions

MongoDB 3.4 introduces the following features that persist data improperly processed by earlier versions. To enable these features, set featureCompatibilityVersion to "3.4".

• Views

• Collation and case-insensitive indexes

• Decimal type

• Index version v2

  • Supports collation and decimal data types.

  • When featureCompatibilityVersion is set to "3.4", the default version of new indexes is v2. Otherwise, the default version is v1.

Default featureCompatibilityVersion values:

• Fresh deployments of MongoDB 3.4: "3.4".

• Deployments upgraded from MongoDB 3.2: "3.2" (needs to be manually set to "3.4").

Prior to MongoDB 3.4, if a database contains views, collation definitions, or v2 indexes, MongoDB cannot start. If decimal type fields exist, operations for these documents may fail.

For upgrade to MongoDB 3.4, you must clear all incompatible data, including views, v2 indexes, and decimal fields.

Driver compatibility changes

To use the new features introduced in MongoDB 3.4 (such as decimal type and collation), you must upgrade your driver to a version that supports these features.

Single-element $in and upsert behavior changes

When an upsert operation finds no matching documents, it creates a base document for upserts based on the equality statement in a query predicate, and then applies update operators to the document. Example:

db.c.drop()
db.c.update( { a : 3, b: "foo" }, { $set : { c : 15 } }, { upsert : true } )
db.c.find()
{ "_id" : ObjectId("59c03009529946822d0afb8c"), "a" : 3, "b" : "foo", "c" : 15 }

Prior to MongoDB 3.4, a single-element $in does not initialize fields.

db.c.drop()
db.c.update( { a : { $in : [1] } }, { $addToSet : { a : 2 } }, { upsert : true } )
db.c.find()
{ "_id" : ObjectId("58bdb00eb39e8f87607e9222"), "a" : [ 2 ] }

Starting from MongoDB 3.4, a single-element $in is treated as an equality statement for upserts:

• If a query predicate includes a single-element $in, the fields are initialized as scalar fields rather than arraies.

• The $addToSet operation in the preceding example fails because array operators cannot be applied to the scalar fields.

Solution: Wrap the $in expression in $elemMatch to forcibly maintain the array type of the fields.

db.c.drop()
db.c.update(
   { a : { $elemMatch : { $in : [ 2 ] } } },
   { $addToSet : { a: 3 } },
   { upsert: true } )
db.c.find()
{ "_id" : ObjectId("..."), "a" : [ 3 ] }