> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Compatibility Changes in MongoDB 8.0

## Query Behavior

### Queries for null Don't Match undefined Fields

Starting in MongoDB 8.0, comparisons to `null` in equality match expressions don't match `undefined` values.

For example, consider these documents and query:

```javascript
// create the people collection

db.people.insertMany( [
   { _id: 1, name: null },
   { _id: 2, name: undefined },
   { _id: 3, name: [ "Gabriel", undefined ] },
   { _id: 4, names: [ "Alice", "Charu" ] }
] )
```

```javascript
db.people.find( { name: null } )
```

Prior to MongoDB 8.0, the preceding query would match documents where:

- The `name` field is `null` (`_id: 1`)

- The `name` field is `undefined` or contains an `undefined` array element (`_id: 2` and `_id: 3`)

- The `name` field does not exist (`_id: 4`)

Starting in MongoDB 8.0, the preceding query does not match documents where the `name` field is `undefined` or contains `undefined` array elements. The query only matches documents where:

- The `name` field is `null` or contains a `null` array element (`_id: 1`)

- The `name` field does not exist (`_id: 4`)

This query behavior change also impacts these operations:

- [`$eq`](https://www.mongodb.com/docs/manual/reference/operator/query/eq.md#mongodb-query-op.-eq)

- [`$in`](https://www.mongodb.com/docs/manual/reference/operator/query/in.md#mongodb-query-op.-in)

- [`$lookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup.md#mongodb-pipeline-pipe.-lookup), because a `null` local field no longer matches an `undefined` foreign field.

To learn how to rewrite your queries or migrate your data to account for this behavior change, see [Migrate Undefined Data and Queries.](https://www.mongodb.com/docs/manual/reference/bson-types/migrate-undefined.md#std-label-migrate-undefined-data-types)

**Important:**

The undefined BSON type is [deprecated](https://bsonspec.org/spec.html). If you try to insert a document with the undefined JS type in [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh), your deployment stores a null value. For more information, see the [mongosh compatibility documentation.](https://www.mongodb.com/docs/mongodb-shell/reference/compatibility.md#std-label-compatibility)

## Deprecations

| Deprecated | Description |
| --- | --- |
| LDAP | Starting in MongoDB 8.0, LDAP authentication and authorization is deprecated. LDAP is available and will continue to operate without changes throughout the lifetime of MongoDB 8. LDAP will be removed in a future major release. For more details, see [LDAP Authentication Alternatives.](https://www.mongodb.com/docs/manual/core/ldap-deprecation.md#std-label-ldap-deprecation) LDAP migration information will be available in the future. |
| Hedged reads | Starting in MongoDB 8.0, hedged reads are deprecated. Queries that specify the read preference [`nearest`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-nearest) no longer use hedged reads by default. If you explicitly specify a hedged read, MongoDB performs a hedged read and logs a warning. |
| Index filters | *Deprecated in version 8.0.* Starting in MongoDB 8.0, use query settings instead of adding [index filters](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-index-filters). Index filters are deprecated starting in MongoDB 8.0. Query settings have more functionality than index filters. Also, index filters aren't persistent and you cannot easily create index filters for all cluster nodes. To add query settings and explore examples, see [`setQuerySettings`.](https://www.mongodb.com/docs/manual/reference/command/setquerysettings.md#mongodb-dbcommand-dbcmd.setQuerySettings) |
| `tcmallocAggressiveMemoryDecommit` | MongoDB 8.0 deprecates the `tcmallocAggressiveMemoryDecommit` parameter. |
| `enableFinerGrainedCatalogCacheRefresh` | MongoDB 8.0 deprecates the `enableFinerGrainedCatalogCacheRefresh` parameter. |
| `timeField` in shard key for time series collection | WARNING: Starting in MongoDB 8.0, use of the `timeField` as a shard key in a time series collection is deprecated. |
| `cleanupOrphaned` | MongoDB 8.0 deprecates the `cleanupOrphaned` command. To confirm that no orphaned documents remain, use [`$shardedDataDistribution`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/shardeddatadistribution.md#mongodb-pipeline-pipe.-shardedDataDistribution) instead. |
| `rangePreview` | Starting in MongoDB 8.0, the `rangePreview` Queryable Encryption algorithm is deprecated and removed. Use the `range` algorithm instead. |

## Backward-Incompatible Features

### Cannot Connect Directly to Shard and Run Commands

Starting in MongoDB 8.0, you can only run [certain commands](https://www.mongodb.com/docs/manual/reference/supported-shard-direct-commands.md#std-label-node-direct-commands) on nodes in sharded clusters. If you attempt to connect directly to a node and run an unsupported command, MongoDB returns an error:

```none
"You are connecting to a sharded cluster improperly by connecting directly
to a shard. Please connect to the cluster via a router (mongos)."
```

To run a non-supported database command directly against a node in a sharded cluster, you must either connect to `mongos` or have the maintenance-only `directShardOperations` role.

MongoDB supports online transition from a replica set to a 1-shard cluster by allowing commands to be run directly against a shard. However, once the cluster has more than one shard, only the [listed commands](https://www.mongodb.com/docs/manual/reference/supported-shard-direct-commands.md#std-label-node-direct-commands) can be run directly against the shard without the maintenance-only `directShardOperations` role.

### Write Concern Majority

Starting in MongoDB 8.0, write operations that use the [`"majority"`](https://www.mongodb.com/docs/manual/reference/write-concern.md#mongodb-writeconcern-writeconcern.-majority-) write concern return an acknowledgment when the majority of replica set members have written the oplog entry for the change. This improves the performance of `"majority"` writes. In previous releases, these operations would wait and return an acknowledgment after the majority of replica set members applied the change.

### Oplog Buffers

Starting in MongoDB 8.0, secondaries write and apply oplog entries for each batch in parallel. This introduces a breaking change for the [`metrics.repl.buffer`](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-serverstatus-serverstatus.metrics.repl.buffer) status metric, as it now provides information on two buffers instead of one.

MongoDB 8.0 deprecates the following server status metrics:

- [`metrics.repl.buffer.count`](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-serverstatus-serverstatus.metrics.repl.buffer.count)

- [`metrics.repl.buffer.maxSizeBytes`](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-serverstatus-serverstatus.metrics.repl.buffer.maxSizeBytes)

- [`metrics.repl.buffer.sizeBytes`](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-serverstatus-serverstatus.metrics.repl.buffer.sizeBytes)

It replaces them with these metrics:

- [`metrics.repl.buffer.apply.count`](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-serverstatus-serverstatus.metrics.repl.buffer.apply.count)

- [`metrics.repl.buffer.apply.maxSizeBytes`](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-serverstatus-serverstatus.metrics.repl.buffer.apply.maxSizeBytes)

- [`metrics.repl.buffer.apply.sizeBytes`](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-serverstatus-serverstatus.metrics.repl.buffer.apply.sizeBytes)

- [`metrics.repl.buffer.write.count`](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-serverstatus-serverstatus.metrics.repl.buffer.write.count)

- [`metrics.repl.buffer.write.maxSizeBytes`](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-serverstatus-serverstatus.metrics.repl.buffer.write.maxSizeBytes)

- [`metrics.repl.buffer.write.sizeBytes`](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-serverstatus-serverstatus.metrics.repl.buffer.write.sizeBytes)

## General Changes

### Shutdown Performance

Starting in MongoDB 8.0, [`Bulk.insert()`](https://www.mongodb.com/docs/manual/reference/method/bulk.insert.md#mongodb-method-Bulk.insert) and data ingestion workloads may perform better. However, shutting down MongoDB immediately after running these workloads might take longer because of the extra data being flushed to disk.

### Concurrent Compact Commands Not Allowed

Starting in MongoDB 8.0, if you try to run multiple concurrent [`compact`](https://www.mongodb.com/docs/manual/reference/command/compact.md#mongodb-dbcommand-dbcmd.compact) commands on the same collection, MongoDB returns an error.

### Geospatial Input Validation

Starting in MongoDB 8.0, you cannot use geospatial queries with malformed input. In prior versions, certain geospatial queries accept malformed input without an error.

### OIDC Identity Providers Can Share an Issuer

Starting in MongoDB 8.0, when multiple IdPs are defined, the [`oidcIdentityProviders`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.oidcIdentityProviders) parameter accepts duplicate `issuer` values as long as the `audience` value is unique for each issuer. This is also available in versions 7.3 and 7.0.

### Removed Parameters

MongoDB 8.0 removes the `storeFindAndModifyImagesInSideCollection` parameter.

### serverStatus Output Change

Starting in MongoDB 8.0, `wiredTiger.concurrentTransactions` is renamed to [`queues.execution`.](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-serverstatus-serverstatus.queues.execution)

### Time Series system.buckets Collections

When you upgrade to 9.0, if you have any `system.buckets` collections that are not time-series collections, you might need to [`drop`](https://www.mongodb.com/docs/manual/reference/method/db.collection.drop.md#mongodb-method-db.collection.drop) or [`rename`](https://www.mongodb.com/docs/manual/reference/method/db.collection.renamecollection.md#mongodb-method-db.collection.renameCollection) those collections before you upgrade, depending on your 8.0 patch release:

MongoDB 8.0.5 and later

You do not need to drop `system.buckets` collections that aren't time-series collections before you upgrade. However, you must drop or rename them after you complete your upgrade.

MongoDB 8.0.4 and earlier

You must drop or rename `system.buckets` collections that aren't time-series collections before you upgrade. All `system.buckets` collections must have valid [time series options](https://www.mongodb.com/docs/manual/reference/command/shardcollection.md#std-label-cmd-sharded-time-series-collection-options) configured before you upgrade to versions 8.0.0 - 8.0.4.

To determine whether you have `system.buckets` collections that are not time-series collections, use the [`db.getCollectionInfos()`](https://www.mongodb.com/docs/manual/reference/method/db.getcollectioninfos.md#mongodb-method-db.getCollectionInfos) method with a filter:

```javascript
db.getCollectionInfos(
   {
      $and: [
         { name: { $regex: /^system\.buckets/ } },
         { 'options.timeseries': { $exists: false } }
      ]
   }
)
```

### Sorting by Non-Existent Fields

When sorting by a nonexistent field, MongoDB does not guarantee any particular output ordering. The behavior in these cases may change from version to version.

## Aggregation

### `$rank` and `$denseRank` Behavior

Starting in MongoDB 8.0, `null` and missing field values in [`$denseRank`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/denserank.md#mongodb-group-grp.-denseRank) and [`$rank`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/rank.md#mongodb-group-grp.-rank) [sortBy](https://www.mongodb.com/docs/manual/reference/operator/aggregation/setwindowfields.md#std-label-setWindowFields-sortBy) operations are treated the same when calculating rankings. This change makes the behavior of `denseRank` and `rank` consistent with [`$sort`.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#mongodb-pipeline-pipe.-sort)

### $shardedDataDistribution Output

Starting in MongoDB 8.0, `$shardedDataDistribution` only returns output for a collection's [primary shard](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary-shard) if the primary shard has [chunks](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-chunk) or [orphaned documents.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-orphaned-document)

For details, see [`$shardedDataDistribution`.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/shardeddatadistribution.md#mongodb-pipeline-pipe.-shardedDataDistribution)

### Upgraded TCMalloc

Starting in MongoDB 8.0, MongoDB uses an upgraded version of TCMalloc that uses [per-CPU caches](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-per-CPU-cache), instead of [per-thread caches](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-per-thread-cache), to reduce memory fragmentation and make your database more resilient to high-stress workloads.

To use the new TCMalloc with better performance, see [TCMalloc Performance Optimization for a Self-Managed Deployment.](https://www.mongodb.com/docs/manual/administration/tcmalloc-performance.md#std-label-tcmalloc-performance)

#### tcmallocReleaseRate Parameter

Starting in MongoDB 8.0, [`tcmallocReleaseRate`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.tcmallocReleaseRate) specifies the [TCMalloc release rate](https://github.com/google/tcmalloc/blob/master/docs/tuning.md) in bytes per second, and the default value of `tcmallocReleaseRate` is reduced to `0`.

In earlier versions, MongoDB used an older version of `tcmalloc` that:

- Set the default `tcmallocReleaseRate` to `1`.

- Accepted values for `tcmallocReleaseRate` between `0` and `10`, inclusive.