Compatibility Changes in MongoDB 4.4

Enterprise Edition

• Ubuntu 18.04 PPC64LE

Community Edition

• RHEL-72-s390x

Rollback Directory

Starting in Mongo 4.4, the rollback directory for a collection is named after the collection's UUID rather than the collection namespace; e.g.

<dbpath>/rollback/20f74796-d5ea-42f5-8c95-f79b39bad190/removed.2020-02-19T04-57-11.0.bson

For details, see Rollback Data.

replSetGetStatus Output Field Changes

The replSetGetStatus command and its mongo shell helper rs.status() removes the following deprecated fields from its output:

Replica Configuration Document Changes

MongoDB 4.4 adds the term field to the replica set configuration document. Replica set members use term and version to achieve consensus on the "newest" replica configuration. Setting featureCompatibilityVersion (fCV) : "4.4" implicitly performs a replSetReconfig to add the term field to the configuration document and blocks until the new configuration propagates to a majority of replica set members. Similarly, downgrading to fCV : "4.2" implicitly performs a reconfiguration to remove the term field.

Initial Sync Restrictions on Operations

Starting in MongoDB 4.4, to run on a replica set member, the following operations require the member to be in PRIMARY or SECONDARY state.

• listDatabases

• listCollections

• listIndexes

• distinct

• dbStats

• collStats

If the member is in another state, such as STARTUP2, the operation errors.

In previous versions, the operations can also be run when the member is in STARTUP2. However, the operations wait until the member transitions to RECOVERING.

Custom getLastErrorDefaults Values Deprecated

Starting in version 4.4, MongoDB deprecates specifying a settings.getLastErrorDefaults value other than the default of { w: 1, wtimeout: 0 }. MongoDB 4.4 honors any write concern value that you specify, however future MongoDB versions might not honor values other than the default. Instead, use the setDefaultRWConcern command to set the default read or write concern configuration for a replica set or sharded cluster.

Set Fields to New Values

Starting in MongoDB 4.4, find and findAndModify() projection can accept aggregation expressions and aggregation syntax.

With the use of aggregation expressions and syntax, including the use of literals and aggregation variables, if you specify a literal (other than a number or a boolean) for the projection field value, the field is projected with the new value.

For example, consider a collection inventory with documents that contain a status field:

db.inventory.insertOne( { _id: 1, item: "postcard", status: "A", instock: [ { warehouse: "B", qty: 15 }, { warehouse: "C", qty: 35 } ] })

Starting in MongoDB, 4.4, the following operation projects the fields status and instock with new values instead of their current value:

db.inventory.find(
   { status: "A" },
   { status: "Active", instock: ["blue", "crimson"] }
)

That is, the operation returns the following document:

{ "_id" : 1, "status" : "Active", "instock" : [ "blue", "crimson" ] }

In previous versions, any specification value (with the exception of zero/false value or the previously unsupported document value) is treated as true to indicate the inclusion of the field with its current value. That is, in earlier versions, the previous operation returns a document with the status and instock fields with their current values:

{ "_id" : 1, "status" : "A", "instock" : [ { "warehouse" : "B", "qty" : 15 }, { "warehouse" : "C", "qty" : 35 } ] }

$elemMatch Projection Field Order

Starting in MongoDB 4.4, regardless of the ordering of the fields in the document, the $elemMatch projection of an existing field returns the field after the other existing field inclusions.

For example, consider a players collection with the following document:

db.players.insert( {
   name: "player1",
   games: [ { game: "abc", score: 8 }, { game: "xyz", score: 5 } ],
   joined: new Date("2020-01-01"),
   lastLogin: new Date("2020-05-01")
} )

In version 4.4+, the following projection returns the games field after the other existing fields included in the projection even though in the document, the field is listed before joined and lastLogin fields:

db.players.find( {}, { games: { $elemMatch: { score: { $gt: 5 } } }, joined: 1, lastLogin: 1 } )

That is, the operation returns the following document:

{
   "_id" : ObjectId("5edef64a1c099fff6b033977"),
   "joined" : ISODate("2020-01-01T00:00:00Z"),
   "lastLogin" : ISODate("2020-05-01T00:00:00Z"),
   "games" : [ { "game" : "abc", "score" : 8 } ]
}

In version 4.2 and earlier, the $elemMatch projection of an existing field upholds the ordering in the document:

{
  "_id" : ObjectId("5edef91e76ddff7d92f118e1"),
  "games" : [ { "game" : "abc", "score" : 8 } ],
  "joined" : ISODate("2020-01-01T00:00:00Z"),
  "lastLogin" : ISODate("2020-05-01T00:00:00Z")
}

$slice of Embedded Array

Starting in MongoDB 4.4, the $slice projection of an array in an nested document no longer returns the other fields in the nested document when the projection is part of an inclusion projection.

For example, consider a collection inventory with documents that contain a size field:

{ item: "socks", qty: 100, details: { colors: [ "blue", "red" ], sizes: [ "S", "M", "L"] } }

Starting in MongoDB 4.4, the following operation projects the _id field (by default), the qty field, and the details field with just the specified slice of the colors array:

db.inventory.find( { }, { qty: 1, "details.colors": { $slice: 1 } } )

That is, the operation returns the following document:

{ "_id" : ObjectId("5ee92a6ec644acb6d13eedb1"), "qty" : 100, "details" : { "colors" : [ "blue" ] } }

If the $slice projection is part of an exclusion projection, the operation continues to return the other fields in the nested document. That is, the following projection is an exclusion projection. The projection excludes the _id field and the elements in the colors array that fall outside the specified slice and returns all other fields.

db.inventory.find( { }, { _id: 0, "details.colors": { $slice: 1 } } )

{ "item" : "socks", "qty" : 100, "details" : { "colors" : [ "blue" ], "sizes" : [ "S", "M", "L" ] } }

The $slice projection by itself is considered an exclusion.

In previous versions, the $slice projection also include the other fields in the nested document regardless of whether the projection is an inclusion or an exclusion.

Path Collision Restrictions

{ ..., size: { h: 10, w: 15.25, uom: "cm" }, ... }

db.inventory.find( {}, { size: 1, "size.uom": 1 } )  // Invalid starting in 4.4

{ ..., instock: [ { warehouse: "A", qty: 35 }, { warehouse: "B", qty: 15 }, { warehouse: "C", qty: 35 } ], ... }

db.inventory.find( {}, { "instock": { $slice: 1 }, "instock.warehouse": 0 } ) // Invalid starting in 4.4

$-Prefixed Field Path Restriction

Starting in MongoDB 4.4, the find and findAndModify() projection cannot project a field that starts with $ with the exception of the DBRef fields.

For example, starting in MongoDB 4.4, the following operation is invalid:

db.inventory.find( {}, { "$instock.warehouse": 0, "$item": 0, "detail.$price": 1 } ) // Invalid starting in 4.4

MongoDB already has a restriction where top-level field names cannot start with the dollar sign ($).

In earlier version, MongoDB ignores the $-prefixed field projections.

$ Positional Operator Placement Restriction

Starting in MongoDB 4.4, the $ projection operator can only appear at the end of the field path, for example "field.$" or "fieldA.fieldB.$".

For example, starting in MongoDB 4.4, the following operation is invalid:

db.inventory.find( { }, { "instock.$.qty": 1 } ) // Invalid starting in 4.4

To resolve, remove the component of the field path that follows the $ projection operator.

In previous versions, MongoDB ignores the part of the path that follows the $; i.e. the projection is treated as "instock.$".

$ Positional Operator and $slice Restriction

Starting in MongoDB 4.4, find and findAndModify() projection cannot include $slice projection expression as part of a $ projection expression.

For example, starting in MongoDB 4.4, the following operation is invalid:

db.inventory.find( { "instock.qty": { $gt: 25 } }, { "instock.$": { $slice: 1 } } ) // Invalid starting in 4.4

MongoDB already has a restriction where top-level field names cannot start with the dollar sign ($).

In previous versions, MongoDB returns the first element (instock.$) in the instock array that matches the query condition; i.e. the positional projection "instock.$" takes precedence and the $slice:1 is a no-op. The "instock.$": { $slice: 1 } does not exclude any other document field.

Empty Field Name Projection Restriction

Starting in MongoDB 4.4, find and findAndModify() projection cannot include a projection of an empty field name.

For example, starting in MongoDB 4.4, the following operation is invalid:

db.inventory.find( { }, { "": 0 } ) // Invalid starting in 4.4

In previous versions, MongoDB treats the inclusion/exclusion of the empty field as it would the projection of non-existing fields.

Text Search Metadata { $meta: "textScore" } Query Requirement

Starting in MongoDB 4.4, you must specify the $text operator in the query predicate of the db.collection.find() operations to use { $meta: "textScore" } expression in the projection or sort. For example:

db.articles.find(
   { $text: { $search: "cake" } },
   { score: { $meta: "textScore" } }
);
db.articles.find(
   { $text: { $search: "cake" } },
   { score: { $meta: "textScore" } }
).sort( { score: {  $meta: "textScore" } } );

If you do not specify the $text operator in the query predicate, the operation fails. For example, the following operations are invalid starting in MongoDB 4.4:

db.articles.find(
   { },
   { score: { $meta: "textScore" } }
)
db.articles.find(
   { },
   { score: { $meta: "textScore" } }
).sort( { score: {  $meta: "textScore" } } );

Reduce a Key Containing a Single Value

Starting in MongoDB 4.4, when you run the mapReduce command, MongoDB calls the reduce function regardless of how many values are contained in the associated key.

In earlier versions, MongoDB does not call the reduce function for a key that has a single value.

For more information, see Usage.

Map-Reduce Output Change

Starting in MongoDB 4.4, mapReduce removes the counts field from its output.

In earlier versions, the command includes a counts field in its output. For example:

"counts" : {
   "input" : 4,
   "emit" : 4,
   "reduce" : 1,
   "output" : 2
},

Map Function's Emit Limit

Starting in MongoDB 4.4, the map function no longer restricts the size of each emit() output to a half of MongoDB's maximum BSON document size.

In earlier versions, a single emit can only hold half of MongoDB's maximum BSON document size

Remove support for BSON Type JavaScript code with scope

mapReduce no longer supports the deprecated BSON type JavaScript code with scope (BSON type 15) for its functions. The map, reduce, and finalize functions must be either BSON type String (BSON type 2) or BSON type JavaScript (BSON type 13). To pass constant values which will be accessible in the map, reduce, and finalize functions, use the scope parameter.

The use of JavaScript code with scope for the mapReduce functions has been deprecated since version 4.2.1.

Removal of rs getLog value

Starting in MongoDB 4.4, the getLog command no longer accepts the rs value, as this categorization of message type has been deprecated. Instead, log messages are now always identified by their component, including REPL for replication messages.

See Filtering by Component for log parsing examples that filter on the component field.

Timestamp Format

With the transition to structured JSON logging, the ctime timestamp format is no longer supported. The following configuration options no longer accept ctime as a valid parameter:

• systemLog.timeStampFormat

• mongod --timeStampFormat

• mongos --timeStampFormat

Use the iso8601-local (default) or iso8601-utc timestamp formats instead.

maxLogSizeKB Parameter

With the transition to structured JSON logging, the maxLogSizeKB server parameter now truncates any individual attributes in a log entry that exceed the specified limit. Previously, this parameter would truncate the entire log entry.

In addition:

• maxLogSizeKB now accepts a value of 0, which disables truncation entirely.

• maxLogSizeKB no longer accepts negative values.

See log message truncation for more information.

db.collection.validate() Parameter Change

The mongo method db.collection.validate() no longer accepts just a boolean parameter.

That is, the method no longer accepts db.collection.validate(<boolean>) as a shorthand for db.collection.validate({full: <boolean>}):

Full Validation on oplog

Starting in MongoDB 4.4, full validation on the oplog for WiredTiger skips the more thorough check. The validate.warnings includes a notice of the behavior.

MMAPv1 Cleanup

• dbStats command no longer returns the obsolete MMAPv1 numExtents field.

• replSetGetStatus command no longer returns the obsolete MMAPv1 field replSetGetStatus.initialSyncStatus.fetchedMissingDocs in its output.

• fsync command no longer accepts the obsolete MMAPv1 field async as an option.

Deprecations