Release Notes for MongoDB 8.2MongoDB 8.2发行说明

8.2.1 - Oct 3, 2025

Issues fixed:问题已解决：

• SERVER-94681: Move sampling to the oplog cap maintainer thread：将取样移至oplog盖保持器螺纹
• SERVER-106469: Starting mongocryptd fails on latest build, windows.：在最新版本windows上启动mongocryptd失败。
• SERVER-109626: Adjust behavior for emitting additional fields in change streams：调整在更改流中发出其他字段的行为
• SERVER-110250: Use existing session when dropping spill WT ident：在丢弃泄漏WT标识时使用现有会话
• WT-15225: Fix newly created table and drop() EBUSY issue：修复新创建的表和drop()EBUSY问题
• 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.MongoDB 8.2添加了terminateSecondaryReadsOnOrphanCleanup参数，该参数控制在块迁移后删除孤立文档之前，辅助节点上的长时间运行的读取操作是否自动终止。

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. 默认情况下，此参数设置为true。如果在块迁移提交之前在辅助节点上开始读取操作，MongoDB会在删除孤立文档之前自动终止该操作。In MongoDB versions before 8.2, these operations continue executing after orphaned document deletion and may silently miss documents without returning an error.在8.2之前的MongoDB版本中，这些操作在删除孤立文档后继续执行，可能会默默地错过文档而不返回错误。

To support this new behavior, the default value for orphanCleanupDelaySecs is now 3600 (previously 900).为了支持这一新行为，orphanCleanupDelaySecs的默认值现在是3600（以前是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.从MongoDB 8.2开始，初始同步期间的索引构建默认使用10%的可用RAM。您可以使用initialSyncIndexBuildMemoryPercentage参数为MongoDB指定不同的内存百分比。

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:默认情况下，可用内存量必须在200 MB到16 GB之间（包括200 MB和16 GB）。您可以使用以下参数指定不同的内存使用最小和最大阈值：

• initialSyncIndexBuildMemoryMinMB
• initialSyncIndexBuildMemoryMaxMB

Query Statistics查询统计信息

Starting in MongoDB 8.2, the $queryStats output includes the following metrics on delinquent tickets:从MongoDB 8.2开始，$queryStats输出包括以下关于拖欠票据的指标：

• metrics.delinquentAcquisitions
• metrics.totalAcquisitionDelinquencyMillis
• metrics.maxAcquisitionDelinquencyMillis

MongoDB considers an execution ticket as delinquent when acquisition takes too long.当获取时间过长时，MongoDB将执行票视为拖欠。

WiredTiger Cache Size Configuration as a PercentageWiredTiger缓存大小配置百分比

Starting in MongoDB 8.2, you can configure the WiredTiger internal cache size using a new percentage-based option. 从MongoDB 8.2开始，您可以使用新的基于百分比的选项配置WiredTiger内部缓存大小。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.除了现有的基于--wiredTigerCacheSizeGB和storage.wiredTiger.engineConfig.cacheSizeGB千兆字节的设置外，您现在还可以使用--wiredTigerCacheSizePct和storage.wiredTiger.engineConfig.cacheSizePct选项将缓存大小指定为可用内存的百分比。

New Inconsistency Type: Range Deletion Missing Shard Key Index新的不一致类型：范围删除缺少分片键索引

Starting in MonogDB 8.2, a new inconsistency type RangeDeletionMissingShardKeyIndex is implemented. 从MonoDB 8.2开始，实现了一种新的不一致类型RangeDeletionMissingShardKeyIndex。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.从MongoDB 8.2开始，您可以使用$currentDate和aggregate()来返回服务器上的当前时间。

New $currentOp Field新的$currentOp字段

The $currentOp aggregation stage now includes the versionContext field, which provides information on the Feature Compatibility Version (FCV) of the operation.$currentOp聚合阶段现在包括versionContext字段，该字段提供有关操作的功能兼容性版本（FCV）的信息。

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.从MongoDB 8.2开始，溢出到磁盘的阶段的解释结果现在包括一致字段名下的标准化指标。此更新提供了一种更一致性的方法来跟踪内存密集型操作的磁盘使用情况。

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.从MongoDB 8.2开始，validate命令和db.collection.validate()辅助方法返回一个新的repairMode字段，该字段指示validate命令尝试修复哪些类型的数据不一致（如果检测到）。

Support for zstd Fast Compression支持zstd快速压缩

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.从MongoDB 8.2开始，storage.wiredTiger.engineConfig.zstdCompressionLevel设置支持负值以实现快速zstd压缩。负值以压缩比为代价提供更快的压缩和解压缩速度。新支持的范围是-7到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.从MongoDB 8.2开始，您可以通过标记节点进行读取镜像，将读取操作选择性地镜像到需要预热缓存的特定服务器。与常规镜像读取不同，目标读取镜像允许您定位隐藏节点并从主节点和次节点进行镜像。

You can configure targeted mirrored reads using the targetedMirroring field in the mirrorReads parameter.您可以使用mirrorReads参数中的targetedMirroring字段配置目标镜像读取。

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.从MongoDB 8.2开始，您可以为入口连接启用速率限制，以在过载期间保护CPU资源。启用后，您可以看到传入连接的速率何时超过他们指定的连接建立速率，并配置参数以指定MongoDB部署如何处理多余的连接。

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. MongoDB 8.2允许您在启用了可查询加密的集合中的加密字符串字段上启用前缀、后缀和子字符串查询。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.从MongoDB 8.1（和8.0.4）开始，您可以使用setQuerySettings向查询设置添加注释。例如，添加一条注释，说明添加查询设置的原因。

Aggregation Accumulators聚合累加器

Starting in MongoDB 8.1, the following aggregation accumulators are available:从MongoDB 8.1开始，以下聚合累加器可用：

• $concatArrays
• $setUnion

Aggregation Stages聚合阶段

Starting in MongoDB 8.1, the following aggregation stages are available:从MongoDB 8.1开始，可以使用以下聚合阶段：

• $listClusterCatalog

Audit Log Improvements审计日志改进

Starting in MongoDB 8.1, if a client application connects to mongos 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.从MongoDB 8.1开始，如果客户端应用程序通过负载均衡器连接到mongos，则源客户端计算机和负载均衡器IP地址和端口将包含在审计日志中。您可以使用日志将审核事件与源客户端计算机进行匹配。

For details, see OCSF Schema Audit Messages and mongo Schema Audit Messages.有关详细信息，请参阅OCSF架构审计消息和mongo架构审计消息。

connectionStatus Connection UUID连接UUID

Starting in MongoDB 8.1, you can access the currently connected client's UUID through connectionStatus.authInfo.UUID.从MongoDB 8.1开始，您可以通过connectionStatus.authInfo.UUID访问当前连接的客户端的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.从MongoDB 8.1（和8.0.5）开始，如果磁盘空间不足，MongoDB将失败溢出到磁盘的查询。

$geoNear Improvements改进

Starting in MongoDB 8.1, some previously failing $geoNear queries with hidden 2d or 2dsphere indexes will now succeed. 从MongoDB 8.1开始，一些以前失败的带有隐藏2d或2dsphere索引的$geoNear查询现在将成功。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.在以前的版本中，一些$geoNear查询在包含隐藏索引时由于对使用哪个索引的混淆而不必要地失败，并出现IndexNotFound错误。

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. 从MongoDB 8.1开始，慢速查询日志中报告的durationMillis指标反映了处理授权和解析命令所花费的时间。As a result, durationMillis more closely reflects the full command duration.因此，durationMillis更准确地反映了完整的命令持续时间。

Inconsistency Types不一致类型

Starting in MongoDB 8.1, the following inconsistency types are available:从MongoDB 8.1开始，以下不一致类型可用：

• CollectionAuxiliaryMetadataMismatch

$lookup Support for Encrypted Collections支持加密集合

Starting in MongoDB 8.1, you can reference multiple encrypted collections in a $lookup stage.从MongoDB 8.1开始，您可以在$lookup阶段引用多个加密集合。

To learn more, see:要了解更多信息，请参阅：

• $lookup with Encrypted Collections使用加密集合进行$查找
• Supported Operations for Automatic Encryption支持的自动加密操作
• Supported Operations for Queryable Encryption支持的可查询加密操作

$merge Missing Fields$merge缺少的字段

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.从MongoDB 8.1开始，如果$merge聚合阶段的支持索引不是稀疏的，则为on选项指定的字段可能会丢失或包含空值。

Query Statistics查询统计信息

Starting in MongoDB 8.1, query statistics are collected and reported for count and distinct commands. 从MongoDB 8.1开始，集合并报告count（计数）和distinct（不同）命令的查询统计信息。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:从MongoDB 8.1开始，以下服务器参数可用：

• 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（以及8.0.4和7.0.14）开始，serverStatus命令输出的indexStats部分跟踪prepareUnique状态下的索引。

MongoDB 8.1 adds the following server status metrics:MongoDB 8.1增加了以下服务器状态指标：

• 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. 从MongoDB 8.1开始，如果查询执行将临时文件写入磁盘，则慢速查询的日志消息将包含新的指标。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.这些指标以导致查询超过内存限制的查询执行阶段作为前缀。例如，sortSpills表示查询执行的排序阶段将临时文件写入磁盘的次数。

For more information on writing temporary files to disk, see allowDiskUse().有关将临时文件写入磁盘的更多信息，请参阅allowDiskUse()。

Stable APIAPI稳定

Starting in MongoDB 8.1, the renameCollection command and corresponding shell method, db.collection.renameCollection(), are included in Stable API V1.从MongoDB 8.1开始，renameCollection命令和相应的shell方法db.collection.renameCollection()包含在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.从MongoDB 8.1开始，解释结果包括$search、$searchMeta和$vectorSearch阶段的执行统计数据。

To learn more, see:要了解更多信息，请参阅：

• Execution Plan Statistics for Search Queries搜索查询的执行计划统计
• Explain Search Results解释搜索结果
• Explain MongoDB Vector Search Results解释MongoDB矢量搜索结果

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:从MongoDB 8.1开始，您可以运行createSearchIndexes、updateSearchIndex、dropSearchIndex和$listSearchIndexes，在仅包含以下阶段的兼容标准视图上创建、修改、删除和列出Atlas搜索索引和Atlas矢量搜索索引：

• $addFields
• $set
• $match wrapping an $expr operation包装$expr操作

You can run aggregation pipelines that contain $search and $searchMeta stages on views that use a search index. 您可以在使用搜索索引的视图上运行包含$search和$searchMeta阶段的聚合管道。You can also run aggregation pipelines that contain a $vectorSearch stage on views that contain a vector search index.您还可以在包含向量搜索索引的视图上运行包含$vectorSearch阶段的聚合管道。

Validate Command Index Specifications Output验证命令索引规范输出

Starting in MongoDB 8.1, the validate command includes index specifications in the validate.indexDetails output field.从MongoDB 8.1开始，validate命令在validate.indexDetails输出字段中包含索引规范。

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.从MongoDB 8.1开始，您可以将模式的validationAction选项设置为errorAndLog，在该选项中，MongoDB拒绝任何违反验证标准的插入或更新，并将错误记录到mongod日志文件中。

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.MongoDB只支持单版本降级。您不能降级到比当前版本落后多个版本的版本。

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.例如，您可以将8.2系列部署降级为8.0系列部署。但是，不支持将8.0系列部署进一步降级为7.0系列部署。

Downgrade Policy降级政策

• Binary downgrades aren't supported for MongoDB Community Edition.MongoDB社区版不支持二进制降级。
• You cannot downgrade your deployment's FCV to or from a minor release version of MongoDB.您不能将部署的FCV降级到MongoDB的次要版本或从MongoDB的次要发布版本降级。
• If you upgrade or downgrade your deployment's FCV, you cannot downgrade your Enterprise deployment's binary version without assistance from support.如果升级或降级部署的FCV，则在没有支持人员帮助的情况下，无法降级企业部署的二进制版本。