Compatibility Changes in MongoDB 3.6

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

Localhost Binding Compatibility Changes

Starting in MongoDB 3.6, MongoDB binaries, mongod andmongos, bind to localhost by default. If thenet.ipv6 configuration file setting or the —ipv6command line option is set for the binary, the binary additionally bindsto the localhost IPv6 address.

Previously, starting from MongoDB 2.6, only the binaries from theofficial MongoDB RPM (Red Hat, CentOS, Fedora Linux, and derivatives)and DEB (Debian, Ubuntu, and derivatives) packages bind to localhost bydefault.

When bound only to the localhost, these MongoDB 3.6 binaries can onlyaccept connections from clients (including the mongo shell,other members in your deployment for replica sets and sharded clusters)that are running on the same machine. Remote clients cannot connect tothe binaries bound only to localhost.

To override and bind to other ip addresses, you can use thenet.bindIp configuration file setting or the—bind_ip command-line option to specify a list of hostnames or ipaddresses.

Warning

Before binding to a non-localhost (e.g. publicly accessible)IP address, ensure you have secured your cluster from unauthorizedaccess. For a complete list of security recommendations, seeSecurity Checklist. At minimum, considerenabling authentication andhardening network infrastructure.

For example, the following mongod instance binds to boththe localhost and the hostname My-Example-Associated-Hostname, which isassociated 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 specifythe hostname or its associated ip address 198.51.100.1:

mongo --host My-Example-Associated-Hostname
 
mongo --host 198.51.100.1

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

Shard Replica Set

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

To convert an existing shard standalone instance to a shard replicaset, see Convert a Shard Standalone to a Shard Replica Set.

HTTP Interface and REST API

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

Tools Changes

MongoDB 3.6 removes the deprecated mongooplog tool.

Array Operation Compatibility Changes

$type: "array" Behavior Change

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 thatcontain 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 collectionbecause the $type query can now detect that field a is itselfan 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 thosedocuments in which the array field a contains an element ofBSON type array.

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

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

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

Array Sort Behavior

Starting in 3.6, when sorting a field containing an array, MongoDBorders the field with the lowest-valued element of the array first forascending sorts and the highest-valued element of the array first fordescending sorts. A sort no longer takes the query predicate intoaccount when choosing the array element which will act as thesort key. This behavior change applies to both thefind command and theaggregation pipeline.

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

Important

As a result of changes to sorting behavior on array fields in MongoDB3.6, when sorting on an array indexed with amultikey index the query plan includesa blocking SORT stage. The new sorting behavior may negatively impactperformance.

In a blocking SORT, all input must be consumed by the sort step beforeit can produce output. In a non-blocking, or indexed sort, thesort step scans the index to produce results in the requested order.

find Method Sorting

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

In MongoDB 3.4 and earlier, a sort by an array field took into accountthe 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 thecollection:

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

In MongoDB 3.6, the sort operation no longer takes into account thequery predicate when determining its sort key. As a result, the sortkey 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 thatmatches 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 ] }

aggregate Method Sorting

In MongoDB 3.6, when sorting array fields with thedb.collection.aggregate() method, only a single array elementis 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 thesort key: 3:31 PM on July 21 for the document with _id: 0 and5:31 PM on July 21 for the document with _id: 1. Since the sortis descending, these keys are then ordered from most recent to leastrecent, resulting in the document with _id: 1 sorting before thedocument with _id: 0.

Before 3.6, the entire array is used as the sortkey for aggregation sorts. The array sort keys are comparedelement-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 elementbreaks the tie and the document with _id: 0 sorts first.

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

Sorting with a Compound Sort Pattern on Multiple Array Fields with aggregate

In MongoDB 3.6, when sorting in anaggregation pipeline, MongoDB canno longer sort documents which contain parallel arrays in the fieldsbeing sorted on. Arrays are considered parallel if they are siblingelements of the BSON object. Sort keys involving nested arrays are notconsidered parallel, nor are sort keys which share the same array as aprefix.

Note

This behavior has always existed for sorting withfind, but now in 3.6find andaggregate share the samesemantics.

Example

A collection contains the following document:

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

The following aggregation succeeds because the sort is performed ona 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 thesame 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 becausein the document with _id : 1 , the sibling fields a andb are both arrays. As a result, MongoDB encounters a parallelarray during sort key generation and returns an error.

Update Operation Changes

New Fields in Updates

Starting in MongoDB 3.6, new fields added through updateoperations 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. Theupdated document would be {_id : 0, x: 0, a: 0, b: 0}.

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

Fields Conflicting with arrayFilters Identifiers

Starting in MongoDB 3.6, fields that conflict with arrayFiltersidentifiers 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 witharrayFilters identifier syntax. For more information onarrayFilters see Specify arrayFilters for Array Update Operations.

Note

The new update behaviors apply only when featureCompatibilityVersion isset to 3.6.

Stricter Validation of $pop Arguments

Starting in 3.6 [1], $pop operator performsa 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 valueto remove the last element in an array.

Remove $pushAll Update Operator

MongoDB 3.6 removes the deprecated $pushAll operator. The operatorhas 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 ] } } }
)

Platform Support

• MongoDB 3.6 discontinues support for versions of Windows prior toWindows Server 2008 R2 and Windows 7.
• MongoDB 3.6 is not tested on APFS, the new filesystem in macOS 10.13and may encounter errors.

General Compatibility Changes

MONGODB-CR Deprecation

As of MongoDB 3.6, MONGODB-CR authentication mechanism isdeprecated. If you have not upgraded your MONGODB-CR authenticationschema to SCRAM, see Upgrade to SCRAM.

Arbiter and Priority

Starting in MongoDB 3.6, arbiters have priority 0. When you upgradea replica set to MongoDB 3.6, if the existing configuration has anarbiter with priority 1, MongoDB 3.6 reconfigures the arbiter tohave priority 0.

Deprecate Master-Slave Replication

MongoDB 3.6 deprecates master-slave replication.

—nojournal Option with WiredTiger

In version 3.6, the —nojournal option is deprecated forreplica set membersusing the WiredTiger storage engine.

Replica set members which use theWiredTiger storage engine should notuse the —nojournal option. For more information aboutjournaling, see Manage Journaling.

aggregate Command and Results

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

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

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

Aggregation Date to String Coercion

Starting in 3.6, a date coerced to a string in an aggregation expression willinclude 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" andd: "2017-10-18t20:04:28" respectively. In 3.6, the results include themilliseconds 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:

• $concat
• $substr
• $substrBytes
• $substrCP
• $strcasecmp
• $toLower
• $toUpper

Remove Diagnostic Logging Command and Option

MongoDB 3.6 removes the deprecated diagLogging command andmongod —diaglog option. Instead, usemongoreplay to capture, replay, and profile commands sent toyour MongoDB deployment.

validate Operation

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

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

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

Indexes Named *

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

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

Deprecated Options

Changed in version 3.6.1.

• MongoDB 3.6.1 deprecates the snapshot query option.

For MMAPv1, use hint() on the { _id: 1} indexinstead to prevent a cursor from returning a document more than onceif 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 moreinformation on read isolation, seeRead Isolation, Consistency, and Recency. [2]

Backwards Incompatible Features

The following 3.6 features require thatfeatureCompatibilityVersion be set to "3.6":

• UUID for collections
• $jsonSchema document validation
• Change Streams
• Chunk aware secondaries
• View definitions, document validators, and partial index filters thatuse 3.6 query features
• Sessions and retryable writes
• Users and roles with authenticationRestrictions

3.6 deployments have the following defaultfeatureCompatibilityVersion values:

To view the featureCompatibilityVersion, see View FeatureCompatibilityVersion.

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