Release Notes for MongoDB 8.2

8.2.1 - Oct 3, 2025

Issues fixed:

• SERVER-94681: Move sampling to the oplog cap maintainer thread

• SERVER-106469: Starting mongocryptd fails on latest build, windows.

• SERVER-109626: Adjust behavior for emitting additional fields in change streams

• SERVER-110250: Use existing session when dropping spill WT ident

• WT-15225: Fix newly created table and drop() EBUSY issue

• All JIRA issues closed in 8.2.1

• 8.2.1 Changelog

terminateSecondaryReadsOnOrphanCleanup Parameter

MongoDB 8.2 adds the terminateSecondaryReadsOnOrphanCleanup parameter, which controls whether long-running read operations on secondary nodes automatically terminate before orphaned document deletion following a chunk migration.

By default, this parameter is set to true. If a read operation on a secondary node begins before the chunk migration commits, MongoDB automatically terminates the operation before deleting the orphaned documents. In MongoDB versions before 8.2, these operations continue executing after orphaned document deletion and may silently miss documents without returning an error.

To support this new behavior, the default value for orphanCleanupDelaySecs is now 3600 (previously 900).

Index Builds During Initial Sync

Starting in MongoDB 8.2, index builds during initial sync use 10% of available RAM by default. You can specify a different percentage of memory for MongoDB to use with the initialSyncIndexBuildMemoryPercentage parameter.

By default, the amount of available memory must be between 200 MB and 16 GB, inclusive. You use the following parameters to specify different minimum and maximum thresholds for memory usage:

• initialSyncIndexBuildMemoryMinMB

• initialSyncIndexBuildMemoryMaxMB

Query Statistics

Starting in MongoDB 8.2, the $queryStats output includes the following metrics on delinquent tickets:

• metrics.delinquentAcquisitions

• metrics.totalAcquisitionDelinquencyMillis

• metrics.maxAcquisitionDelinquencyMillis

MongoDB considers an execution ticket as delinquent when acquisition takes too long.

WiredTiger Cache Size Configuration as a Percentage

Starting in MongoDB 8.2, you can configure the WiredTiger internal cache size using a new percentage-based option. In addition to the existing --wiredTigerCacheSizeGB and storage.wiredTiger.engineConfig.cacheSizeGB gigabyte-based settings, you can now specify the cache size as a percentage of the available memory with the --wiredTigerCacheSizePct and storage.wiredTiger.engineConfig.cacheSizePct options.

New Inconsistency Type: Range Deletion Missing Shard Key Index

Starting in MonogDB 8.2, a new inconsistency type RangeDeletionMissingShardKeyIndex is implemented. The inconsistency type indicates that a sharded collection exists that doesn't have an index compatible with the collection shard key and there is at least one remaining range deletion task to complete.

New Aggregation Expression

Starting in MongoDB 8.2, you can use $currentDate with aggregate() to return the current time on the server.

New $currentOp Field

The $currentOp aggregation stage now includes the versionContext field, which provides information on the Feature Compatibility Version (FCV) of the operation.

serverStatus Output Change

serverStatus includes the following new fields in its output:

• metrics.operation.killedDueToRangeDeletion

• metrics.query.bucketAuto.spilledBytes

• metrics.query.bucketAuto.spilledDataStorageSize

• metrics.query.bucketAuto.spilledRecords

• metrics.query.bucketAuto.spills

• planCache.classic.replanned_plan_is_cached_plan

• planCache.sbe.replanned_plan_is_cached_plan

• spillWiredTiger

• connections.queuedForEstablishment

• connections.establishmentRateLimit

• connections.establishmentRateLimit.rejected

• connections.establishmentRateLimit.exempted

• connections.establishmentRateLimit.interruptedDueToClientDisconnect

• metrics.network.averageTimeToCompletedTLSHandshakeMicros

• metrics.network.averageTimeToCompletedHelloMicros

• metrics.network.averageTimeToCompletedAuthMicros

• queues.ingressSessionEstablishment

• queues.ingressSessionEstablishment.addedToQueue

• queues.ingressSessionEstablishment.removedFromQueue

• queues.ingressSessionEstablishment.interruptedInQueue

• queues.ingressSessionEstablishment.rejectedAdmissions

• queues.ingressSessionEstablishment.exemptedAdmissions

• queues.ingressSessionEstablishment.successfulAdmissions

• queues.ingressSessionEstablishment.attemptedAdmissions

• queues.ingressSessionEstablishment.averageTimeQueuedMicros

• queues.ingressSessionEstablishment.totalAvailableTokens

Explain Output for Disk Spilling Stages

Starting in MongoDB 8.2, the Explain Results for stages that spill to disk now include standardized metrics under consistent field names. This update provides a more unified way to track disk usage for memory-intensive operations.

The new fields include:

• spills

• spilledBytes

• spilledRecords

• spilledDataStorageSize

Repair Mode Field in Validation Output

Starting in MongoDB 8.2, the validate command and the db.collection.validate() helper method return a new repairMode field that indicates what types of data inconsistencies the validate command attempted to repair, if detected.

Support for zstd Fast Compression

Starting in MongoDB 8.2, The storage.wiredTiger.engineConfig.zstdCompressionLevel setting supports negative values for fast zstd compression. Negative values provide faster compression and decompression speeds at the cost of the compression ratio. The new supported range is -7 to 22.

Targeted Mirrored Reads

Starting in MongoDB 8.2, you can selectively mirror read operations to specific servers that need their caches warmed up by tagging the nodes for read mirroring. Unlike general mirrored reads, targeted read mirroring allows you to target hidden nodes and mirror from both primary and secondary nodes.

You can configure targeted mirrored reads using the targetedMirroring field in the mirrorReads parameter.

Rate Limit Ingress Connection Establishment

Starting in MongoDB 8.2, you can enable rate limiting for ingress connections to preserve CPU resources during overload. When enabled, you can see when the rate of incoming connections exceeds the connection establishment rate they specified and configure parameters to specify how your MongoDB deployment handles excess connections.

You can configure rate limiting using the following new fields:

• ingressConnectionEstablishmentRateLimiterEnabled

• ingressConnectionEstablishmentRatePerSec

• ingressConnectionEstablishmentBurstCapacitySecs

• ingressConnectionEstablishmentMaxQueueDepth

Queryable Encryption Prefix, Suffix, and Substring Query Public Preview

MongoDB 8.2 lets you enable prefix, suffix, and substring queries on encrypted string fields in Queryable Encryption enabled collections. For details, see enable substring queries and Supported Aggregation Expressions.

Add Comments to Query Settings

Starting in MongoDB 8.1 (and 8.0.4), you can use setQuerySettings to add comments to query settings. For example, add a comment that indicates why you added query settings.

Aggregation Accumulators

Starting in MongoDB 8.1, the following aggregation accumulators are available:

• $concatArrays

• $setUnion

Aggregation Stages

Starting in MongoDB 8.1, the following aggregation stages are available:

• $listClusterCatalog

Audit Log Improvements

Starting in MongoDB 8.1, if a client application connects to a mongod or a mongos instance through a load balancer, the origin client computer and load balancer IP addresses and ports are included in the audit log. You can use the log to match an audit event with the origin client computer.

For details, see OCSF Schema Audit Messages and mongo Schema Audit Messages.

connectionStatus Connection UUID

Starting in MongoDB 8.1, you can access the currently connected client's UUID through connectionStatus.authInfo.UUID.

Disk Space

Starting in MongoDB 8.1 (and 8.0.5), if disk space is running low, MongoDB will fail queries that are spilling to disk.

$geoNear Improvements

Starting in MongoDB 8.1, some previously failing $geoNear queries with hidden 2d or 2dsphere indexes will now succeed. In previous releases, some $geoNear queries used to unnecessarily fail with an IndexNotFound error when they included a hidden index due to confusion over which index to use.

Improved Accuracy for Operation Duration Metric

Starting in MongoDB 8.1, the durationMillis metric reported in slow query logs accounts for time spent processing authorization and parsing the command. As a result, durationMillis more closely reflects the full command duration.

Inconsistency Types

Starting in MongoDB 8.1, the following inconsistency types are available:

• CollectionAuxiliaryMetadataMismatch

$lookup Support for Encrypted Collections

Starting in MongoDB 8.1, you can reference multiple encrypted collections in a $lookup stage.

To learn more, see:

• $lookup with Encrypted Collections

• Supported Operations for Automatic Encryption

• Supported Operations for Queryable Encryption

$merge Missing Fields

Starting in MongoDB 8.1, if the $merge aggregation stage's supporting index is not sparse, the fields specified for the on option can be missing or contain a null value.

Query Statistics

Starting in MongoDB 8.1, query statistics are collected and reported for count and distinct commands. For details, see count Command Query Shape and distinct Command Query Shape.

Server Parameters

Starting in MongoDB 8.1, the following server parameters are available:

• enableAutoCompaction

• upsertMaxRetryAttemptsOnDuplicateKeyError

• AbortExpiredTransactionsSessionCheckoutTimeout (also available in 8.0.13)

• JWKSMinimumQuiescePeriodSecs

• catalogCacheCollectionMaxEntries

• catalogCacheDatabaseMaxEntries

• catalogCacheIndexMaxEntries

• wiredTigerSessionMax

serverStatus Metrics

Starting in MongoDB 8.1 (and 8.0.4 and 7.0.14), the indexStats section of the serverStatus command output tracks indexes in prepareUnique state.

MongoDB 8.1 adds the following server status metrics:

• maxTimestampEligibleForTruncate in changeStreamPreImages.purgingJob

• metrics.ttl.invalidTTLIndexSkips

• metrics.repl.timestamps

• metrics.repl.timestamps.oldestTimestamp

• query.planning.fastPath.express

• query.planning.fastPath.idHack

• metrics.abortExpiredTransactions.successfulKills (also available in 8.0.13)

• metrics.abortExpiredTransactions.timedOutKills (also available in 8.0.13)

• wiredTiger.version

Slow Query Metrics for Disk Spilling

Starting in MongoDB 8.1, log messages for slow queries contain new metrics if the query execution writes temporary files to disk. These metrics are prefixed by the query execution stage that caused the query to exceed the memory limit. For example, sortSpills indicates the number of times that the sort stage of query execution wrote temporary files to disk.

For more information on writing temporary files to disk, see allowDiskUse().

Stable API

Starting in MongoDB 8.1, the renameCollection command and corresponding shell method, db.collection.renameCollection(), are included in Stable API V1.

Support for Search Stages in Explain Results

Starting in MongoDB 8.1, the explain results include execution stats for the $search, $searchMeta, and $vectorSearch stages.

To learn more, see:

• Execution Plan Statistics for Search Queries

• Explain Search Results

• Explain MongoDB Vector Search Results

Support for Search Index Commands on Views

Starting in MongoDB 8.1, you can run createSearchIndexes, updateSearchIndex, dropSearchIndex, and $listSearchIndexes to create, modify, drop, and list Atlas Search indexes and Atlas Vector Search indexes on compatible standard views that contain only the following stages:

• $addFields

• $set

• $match wrapping an $expr operation

You can run aggregation pipelines that contain $search and $searchMeta stages on views that use a search index. You can also run aggregation pipelines that contain a $vectorSearch stage on views that contain a vector search index.

Validate Command Index Specifications Output

Starting in MongoDB 8.1, the validate command includes index specifications in the validate.indexDetails output field.

Validation Action for Handling Invalid Documents

Starting in MongoDB 8.1, you can set your schema's validationAction option to errorAndLog, in which MongoDB rejects any insert or update that violates the validation criteria and logs the error to the mongod log file.

For more information, see Choose How to Handle Invalid Documents.

Only Single-Version Downgrades are Supported

MongoDB only supports single-version downgrades. You cannot downgrade to a release that is multiple versions behind your current release.

For example, you can downgrade a 8.2-series to a 8.0-series deployment. However, further downgrading that 8.0-series deployment to a 7.0-series deployment is not supported.

Downgrade Policy

• Binary downgrades aren't supported for MongoDB Community Edition.

• You cannot downgrade your deployment's FCV to or from a minor release version of MongoDB.

• If you upgrade or downgrade your deployment's FCV, you cannot downgrade your Enterprise deployment's binary version without assistance from support.