Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

Compatibility Changes in MongoDB 3.6

On this page

  • Localhost Binding Compatibility Changes
  • Shard Replica Set
  • HTTP Interface and REST API
  • Tools Changes
  • Array Operation Compatibility Changes
  • Update Operation Changes
  • Platform Support
  • General Compatibility Changes
  • Backwards Incompatible Features

The following 3.6 changes can affect the compatibility with older versions of MongoDB.

Warning

Before you bind your instance to a publicly-accessible IP address, you must secure your cluster from unauthorized access. For a complete list of security recommendations, see Security Checklist. At minimum, consider enabling authentication and hardening network infrastructure.

MongoDB binaries, mongod and mongos, bind to localhost by default. If the net.ipv6 configuration file setting or the --ipv6 command line option is set for the binary, the binary additionally binds to the localhost IPv6 address.

By default mongod and mongos that are bound to localhost only accept connections from clients that are running on the same computer. This binding behavior includes mongosh and other members of your replica set or sharded cluster. Remote clients cannot connect to binaries that are bound only to localhost.

To override the default binding and bind to other IP addresses, use the net.bindIp configuration file setting or the --bind_ip command-line option to specify a list of hostnames or IP addresses.

Warning

Starting in MongDB 5.0, split horizon DNS nodes that are only configured with an IP address fail startup validation and report an error. See disableSplitHorizonIPCheck.

For example, the following mongod instance binds to both the localhost and the hostname My-Example-Associated-Hostname, which is associated with the IP address 198.51.100.1:

mongod --bind_ip localhost,My-Example-Associated-Hostname

In order to connect to this instance, remote clients must specify the hostname or its associated IP address 198.51.100.1:

mongosh --host My-Example-Associated-Hostname
mongosh --host 198.51.100.1

To bind to all IPv4 addresses, you can specify the bind ip address of 0.0.0.0. To bind to all IPv4 and IPv6 addresses, you can specify the bind ip address of ::,0.0.0.0 or alternatively, use the new net.bindIpAll setting or the new command-line option --bind_ip_all.

Starting in 3.6, shards must be replica sets. To upgrade your sharded cluster to version 3.6, the shard servers must be running as a replica set.

MongoDB 3.6 removes the deprecated HTTP interface and REST API to MongoDB.

Configuration Settings
mongod/mongos option
net.http.enabled
net.http.JSONPEnabled
net.http.port
net.http.RESTInterfaceEnabled
httpinterface
nohttpinterface
jsonp
rest

MongoDB 3.6 removes the deprecated mongooplog tool.

Starting in 3.6, $type: "array" and $type: 4 expressions match array fields that contain any element type.

In earlier versions, $type : "array" only matches array fields that contain nested arrays.

For example, a collection named c contains two documents:

{ "_id": 1, "a": [ 1, 2, 3 ] },
{ "_id": 2, "a": [ 1, 2, [ 3, 4 ] ] }

The following operation queries by type on field a:

db.c.find( { "a": { $type : "array" } } )

Starting in 3.6, the query returns both documents in the collection because the $type query can now detect that field a is itself an array.

{ "_id": 1, "a": [ 1, 2, 3 ] },
{ "_id": 2, "a": [ 1, 2, [ 3, 4 ] ] }

In 3.4 and earlier versions of MongoDB, the query only returns those documents in which the array field a contains an element of BSON type array.

{ "_id": 2, "a": [ 1, 2, [ 3, 4 ] ] }

If upgrading from a MongoDB 3.4.x deployment that has partial indexes whose partialFilterExpression includes a $type : "array" or $type : 4 expression, you must rebuild these indexes after upgrading to avoid conflicting $type : 'array' semantics.

For more information on the $type: "array" expression, see Querying by Array Type.

Starting in 3.6, when sorting a field containing an array, MongoDB orders the field with the lowest-valued element of the array first for ascending sorts and the highest-valued element of the array first for descending sorts. A sort no longer takes the query predicate into account when choosing the array element which will act as the sort key. This behavior change applies to both the find command and the aggregation pipeline.

As a result of this change, applications that currently sort by an array field may experience a different sort order.

Important

When you sort based on an array field that is indexed with a multikey index, the query plan includes a blocking sort stage unless both of the following are true:

  • The index boundaries for all sort fields are [MinKey, MaxKey].

  • No boundaries for any multikey-indexed field have the same path prefix as the sort pattern.

A sort key is the array element MongoDB uses during the sorting process to compare and ultimately order documents containing an array. In an ascending sort, documents containing arrays with the lowest-valued sort keys are ordered first. Likewise, in a descending sort, documents containing arrays with the highest-valued sort keys are ordered first.

In MongoDB 3.4 and earlier, a sort by an array field took into account the query predicate when determining the sort key.

For example, a collection coll has the following documents:

{ _id: 0, a: [-3, -2, 2, 3] }
{ _id: 1, a: [ 5, -4 ] }

Consider following sort operation on the array field a of the collection:

db.coll.find({a: {$gte: 0}}).sort({a: 1});

In MongoDB 3.6, the sort operation no longer takes into account the query predicate when determining its sort key. As a result, the sort key is the lowest-valued element for each document:

  • -3 for the document with _id: 0 and

  • -4 for the document with _id: 1.

The operation returns the documents in the following order:

{ "_id" : 1, "a" : [ 5, -4 ] }
{ "_id" : 0, "a" : [ -3, -2, 2, 3 ] }

Previous MongoDB versions use the lowest-valued array element that matches the query predicate of {$gte: 0} as the sort key:

  • 2 for the document with _id: 0 and

  • 5 for the document with _id: 1,

and would return the documents in the following order:

{ _id: 0, a: [-3, -2, 2, 3] }
{ _id: 1, a: [ 5, -4 ] }

In MongoDB 3.6, when sorting array fields with the db.collection.aggregate() method, only a single array element is used as the sort key.

Consider the following example:

// Documents.
{ "_id" : 1, "timestamps" : [ ISODate("2017-07-15T15:31:01Z"), ISODate("2017-07-21T18:31:01Z") ] }
{ "_id" : 0, "timestamps" : [ ISODate("2017-07-21T15:31:01Z"), ISODate("2017-07-21T13:31:01Z") ] }
// Query.
db.c.aggregate([{$sort: {timestamps: -1}}])

For a descending sort, the most recent time in the array is used as the sort key: 3:31 PM on July 21 for the document with _id: 0 and 5:31 PM on July 21 for the document with _id: 1. Since the sort is descending, these keys are then ordered from most recent to least recent, resulting in the document with _id: 1 sorting before the document with _id: 0.

Before 3.6, the entire array is used as the sort key for aggregation sorts. The array sort keys are compared element-wise to determine the sort order of the result set.

Example

// Documents.
{_id: 0, a: [3, 1, 5]}
{_id: 1, a: [3, 4, 0]}
// Query.
db.coll.aggregate([{$sort: {a: 1}}])

Prior to 3.6, the sort keys are [3, 1, 5] and [3, 4, 0] respectively. Since the first array elements are equal, the second array element breaks the tie and the document with _id: 0 sorts first.

For more information on sorting with the Aggregation Pipeline, see $sort.

In MongoDB 3.6, when sorting in an aggregation pipeline, MongoDB can no longer sort documents which contain parallel arrays in the fields being sorted on. Arrays are considered parallel if they are sibling elements of the BSON object. Sort keys involving nested arrays are not considered parallel, nor are sort keys which share the same array as a prefix.

Note

This behavior has always existed for sorting with find, but now in 3.6 find and aggregate share the same semantics.

Example

A collection contains the following document:

{a: [ {b: [1, 2]}, {b: [3, 4]} ]}

The following aggregation succeeds because the sort is performed on a nested array:

db.coll.aggregate([{$sort: {"a.b": 1}}])

Example

Similarly, if a collection contains the following document:

{a: [{b: 1, c: 1}, {b: 2, c: 2}]}

The following aggregation succeeds because the sort keys share the same array as a prefix:

db.coll.aggregate([{$sort: {"a.b": 1, "a.c": 1}}])

Example

However, in a collection that contains the following documents:

{ _id: 1, a: [ 1, 2 ], b: [ 1, 2 ]}
{ _id: 2, a: [ -3, 5 ], b: 0 }
{ _id: 3, a: [ -6, 12 ], b: 100 }

The following sort operation fails:

db.coll.aggregate([ { $sort: {a: 1, b: 1} } ])

MongoDB cannot sort on both the a and b fields because in the document with _id : 1 , the sibling fields a and b are both arrays. As a result, MongoDB encounters a parallel array during sort key generation and returns an error.

Starting in MongoDB 3.6, new fields added through update operations are appended in lexicographic order.

For example, a collection coll has the following document:

{ _id: 0, x: 0 }

The following update operation adds two new fields to the document:

db.coll.update({_id: 0}, {$set: {b: 0, a: 0}})

Starting in 3.6, MongoDB appends the new fields in lexicographic order. The updated document would be {_id : 0, x: 0, a: 0, b: 0}.

Earlier versions of MongoDB append the new fields in order of appearance in the update document. The updated document would be {_id : 0, x: 0, b: 0, a: 0}.

Starting in MongoDB 3.6, fields that conflict with arrayFilters identifiers can no longer be updated.

For example, a collection coll has the following document:

{ _id: 0, x: { "$[]": 0 } }

The following update succeeds in earlier versions of MongoDB:

db.coll.update({_id: 0}, {$set: {"x.$[]": 1}})

In MongoDB 3.6 the update fails since the field name "$[]" conflicts with arrayFilters identifier syntax. For more information on arrayFilters see Specify arrayFilters for Array Update Operations.

Note

The new update behaviors apply only when featureCompatibilityVersion is set to 3.6.

Starting in 3.6 [1], $pop operator performs a stricter validation of its argument to require either:

  • -1 to remove the first element of an array, or

  • 1 to remove the last element in an array.

In earlier versions, $pop allowed:

  • any value less than 0 to remove the first element of an array, and

  • any value greater than or equal to 0 as well as non-numeric value to remove the last element in an array.

[1] Affects MongoDB deployments with featureCompatibilityVersion set to 3.6; e.g. new 3.6 deployments, upgraded deployments that have set featureCompatibilityVersion to 3.6.

MongoDB 3.6 removes the deprecated $pushAll operator. The operator has been deprecated since 2.4.

Instead of $pushAll, use the $push operator with the $each modifier. For example:

db.students.update(
{ name: "joe" },
{ $push: { scores: { $each: [ 90, 92, 85 ] } } }
)
  • MongoDB 3.6 discontinues support for versions of Windows prior to Windows Server 2008 R2 and Windows 7.

  • MongoDB 3.6 is not tested on APFS, the new filesystem in macOS 10.13 and may encounter errors.

As of MongoDB 3.6, MONGODB-CR authentication mechanism is deprecated.

Arbiters have priority 0.

MongoDB 3.6 deprecates master-slave replication.

In version 3.6, the --nojournal option is deprecated for Replica Set Members using the WiredTiger storage engine.

Replica set members that use the WiredTiger storage engine should not use the --nojournal option. For more information about journaling, see Manage Journaling.

MongoDB 3.6 removes the option for the aggregate command to return its results as a single document.

If you run the aggregate command, you must include either the cursor option or the explain option.

Rather than run the aggregate command directly, most users should use the db.collection.aggregate() helper provided in the mongo shell or the equivalent helper in their driver. These helpers return a cursor unless using the explain option.

Starting in 3.6, a date coerced to a string in an aggregation expression will include milliseconds and is appended with the letter 'Z'.

Example

// Documents.
{_id: 0, d: ISODate("2017-10-18T20:04:27.978Z")}
{_id: 1, d: ISODate("2017-10-18T20:04:28.192Z")}
// Query.
db.coll.aggregate({$project: {d: {$toLower: "$d"}}})

Prior to 3.6, this would return the dates as d: "2017-10-18t20:04:27" and d: "2017-10-18t20:04:28" respectively. In 3.6, the results include the milliseconds and letter 'Z': d: "2017-10-18t20:04:27.978z" and d: "2017-10-18t20:04:28.192z".

The change applies to the following aggregation operators:

MongoDB 3.6 removes the deprecated diagLogging command and mongod --diaglog option. Instead, use mongoreplay to capture, replay, and profile commands sent to your MongoDB deployment.

Starting in MongoDB 3.6, for the WiredTiger storage engine, only the full validation process will force a checkpoint and flush all in-memory data to disk before verifying the on-disk data.

In previous versions, the data validation process for the WT storage engine always forces a checkpoint.

For more information on the validate operation, see the validate command and the db.collection.validate() method.

Starting in 3.6, you cannot specify * as the index name during index creation nor can you delete indexes named * by specifying the index keys.

To delete existing indexes named *, delete the index before upgrading. To rename them, delete and recreate the index.

Changed in version 3.6.1.

  • MongoDB 3.6.1 deprecates the snapshot query option.

    For MMAPv1, use hint() on the { _id: 1} index instead to prevent a cursor from returning a document more than once if an intervening write operation results in a move of the document.

    For other storage engines, use hint() with { $natural : 1 } instead.

  • MongoDB 3.6.1 deprecates the $isolated option. For more information on read isolation, see Read Isolation, Consistency, and Recency. [2]

[2] Starting in version 4.0, MongoDB offers transactions.

The following 3.6 features require that featureCompatibilityVersion be set to "3.6":

3.6 deployments have the following default featureCompatibilityVersion values:

Deployments
featureCompatibilityVersion
For new 3.6 deployments
"3.6"
For deployments upgraded from 3.4
"3.4" until you setFeatureCompatibilityVersion to "3.6".

To view the featureCompatibilityVersion, see Get FeatureCompatibilityVersion.

If you need to downgrade from 3.6, you must remove data related to all persisted incompatible features from your database before downgrading the binaries. See the 3.6 downgrade procedures.

What is MongoDB? →