Compatibility Changes in MongoDB 9.0

Empty Field Names in $group

Starting in MongoDB 9.0, the $group stage returns an error if an accumulator expression has an empty field name. For details, see Empty Field Name $group Restriction.

allowPartialResults in the aggregate $queryStats Key

Starting in MongoDB 9.0, the $queryStats key for aggregate commands includes the allowPartialResults option when the option is explicitly set. Query stats can then distinguish between requests where allowPartialResults is omitted, explicitly true, or explicitly false.

The addition changes the key and keyHash serialization for aggregate queries that set allowPartialResults. The queryShapeHash is unchanged. Downstream consumers that match on keyHash might observe different values for these queries.

For more information, see the aggregate command query shape.

Null Comparisons on Dotted Paths That Traverse Arrays

Starting in MongoDB 9.0, a dotted path that does not resolve to a non-null value evaluates as null. The new behavior applies when a field in the path holds an empty array or an array of scalar values. In earlier versions, these paths did not evaluate as null, which produced results that disagreed with $exists.

Consider a collection that contains the following documents:

{ _id: 1, a: [ 1 ] }
{ _id: 2, a: [ ] }

The path a.b does not resolve to a non-null value in either document. Starting in MongoDB 9.0, the { "a.b": null } query matches both documents. In earlier versions, the query matched neither document. The { "a.b": { $ne: null } } query returns the opposite results: in MongoDB 9.0, the query matches neither document, and in earlier versions, it matched both.

The new behavior affects comparisons to null that use the $eq, $ne, $in, $nin, $gte, and $lte operators. Equality matching in the $lookup stage follows the same semantics.

Queries Fail When an Indexed Field Becomes Multikey

Starting in MongoDB 9.0, if an indexed field becomes a multikey field while a query that references the field is running, the query might fail with a QueryKilledError. An indexed field becomes multikey when you insert or update a document so the field contains an array value.

If your query fails with this error, re-run the query after the insert or update operation completes.

Change Streams Enforce Read Preference After Elections

Starting in MongoDB 9.0, a change stream opened with a readPreference of primary or secondary returns the resumable error InterruptedDueToReplStateChange (error code 11602) from getMore if a replica set election changes the node's role so that it no longer satisfies the read preference. In earlier versions, the cursor kept returning results from the same node.

Compliant drivers and mongos resume automatically from the last resume token. Manual getMore loops and mongosh must resume with resumeAfter. For details, see Resume a Change Stream.

Geospatial Index Key-Extraction Error Codes

Starting in MongoDB 9.0, 2dsphere index key-extraction failures return the named error codes 510 (GeoKeyExtractionFailed) and 511 (GeoKeyExtractionFailedTimeseries). These codes replace the previous assertion codes 16755 and 16756 for regular 2dsphere indexes and 183934 and 183493 for time series collections. If your application matches on the previous codes, update it to match 510 and 511.

Stronger Collection Locks for Cross-Database renameCollection

Starting in MongoDB 9.0, when you rename a collection between different databases on a replica set, the renameCollection command holds an exclusive lock on the source and target collections. The lock lasts for the entire operation, and blocks DDL operations and writes to both collections. Most read operations use lock-free reads and are not blocked.

Earlier versions released the source collection's lock before renameCollection completed the rename. A concurrent write to the source collection during that window could be lost.

The change affects replica sets only. Sharded clusters already lock both collections for the duration of the rename.

Expressions in Views

In MongoDB 9.0, $convert can convert an object to binData. For details, see Convert an Object to binData.

If you create a view that uses this conversion, queries on that view return an error after you downgrade to an earlier version.

Before you downgrade from 9.0, update or drop any views that use this conversion.