版本说明

5.11.1 中的新功能

要学习；了解有关此发布的更多信息，请参阅 GitHub 上的 v..5 发布说明。111

5.11 中的新功能

5.11驾驶员发布不包含应用于Kotlin驾驶员的任何更改、修复或功能。

要学习；了解有关此发布的更多信息，请参阅 GitHub 5上的 v.11 发布说明。

5.10 中的新功能

5.10驱动程序发布包括以下更改、修复和功能：

• 修复了以下问题： Kotlin数据类中的 ByteArray字段被编码为 Int32 值的BSON大量而不是BSON二进制，这可能会显着增加文档大小。此发布恢复了BSON二进制编码，与 v5.1.3 之前的行为匹配。驾驶员仍会对以大量格式写入的数据进行解码，但此数据的任何非驱动程序使用者可能需要更新才能处理新的编码。

• 新增 $scoreFusion聚合阶段，可合并并规范化多个搜索管道的分数。此阶段需要MongoDB 8.2 或更高版本。

• 为 $score聚合阶段添加了流式构建器API 。使用此API可配置分数规范化、权重和分数详细信息。此功能需要MongoDB 8.2 或更高版本。

• Adds the parentFilter and nestedOptions options, which allow nested embeddings and arrays of embeddings in $vectorSearch queries.

To learn more about this release, see the v5.10 Release Notes on GitHub.

5.9.2 中的新功能

5.9.2驱动程序补丁发布包括以下更改：

• 修复了以下问题： ProxySettings.toString()包含 SOCKS 代理用户名和密码，导致这些凭证出现在应用程序日志中。此问题会影响驾驶员版本54.11.0 到5.9.1 。要学习；了解详情，请参阅 JAVA-6266 和 CVE-2026 -18710 。

To learn more about this release, see the v5.9.2 Release Notes on GitHub.

5.9 的新增功能

5.9驱动程序发布包括以下更改、修复和功能：

• 将 Queryable Encryption (QE) 前缀、后缀和子字符串查询提升为全面可用 (GA)。MongoDB 9.0 及更高版本支持这些查询类型。要了解有关 QE 的更多信息，请参阅正在使用的加密。

• 将 QE string 查询的显式加密 API 从 Text 重命名为 String。要执行 QE string 查询，请进行以下更改：

  • 使用 StringOptions 类而不是 TextOptions。

  • 使用 EncryptOptions.stringOptions() 方法而不是 textOptions() 方法。

  • 使用 EncryptOptions.getStringOptions() 方法而不是 getTextOptions() 方法。

  • 将加密算法设置为 "String"。

• 将 libmongocrypt 版本升级到 1.20.0。

To learn more about this release, see the v5.9 Release Notes on GitHub.

5.8 的新增功能

5.8驱动程序发布包括以下更改、修复和功能：

• 为向量搜索索引定义添加类型化的构建者 API。

• 新增对 $rerank 聚合阶段的支持。连接到运行 MongoDB 8.3 或更高版本的 Atlas 集群时，可以使用 Aggregates.rerank() 构建者方法创建此阶段。

• 新增对 $search 管道阶段中 vectorSearch 操作符的支持。您可以使用 SearchOperator.vectorSearch() 构建者方法执行近似最近邻 (ANN) 向量搜索，或使用 SearchOperator.vectorSearchExact() 执行精确最近邻 (ENN) 搜索。返回的 VectorSearchOperator 支持 filter() 方法应用词汇预过滤器。

• 通过在 VectorSearchIndexDefinition 类中使用 storedSource() 方法，增加了对在向量搜索索引定义上配置存储源的支持。

• 通过在 VectorSearchOptions 类中使用 returnStoredSource() 方法，增加了对在 $vectorSearch 结果中请求存储源字段的支持。

• 通过消除中间分配来优化 RawBsonDocument 编码和解码性能。

• 修复当 Micrometer 不存在时发生的 OSGi 包解析失败。

• 将 Javadoc 文档添加到 MongodbObservation 和 MongodbObservationContext 类。

• 将 libmongocrypt 版本升级到 1.18.1。

To learn more about this release, see the v5.8 Release Notes on GitHub.

5.7.1 中的新功能

5.7.1驱动程序补丁发布包括以下更改：

• 修复 Micrometer 集成中的 Javadoc 警告。

• 将 Micrometer OSGi 导入标记为可选，以解决 OSGi 运行时环境中的绑定包解析问题。

To learn more about this release, see the v5.7.1 Release Notes on GitHub.

5.7 中的新增功能

5.7驱动程序发布包括以下更改、修复和功能：

• 重要提示：即将发布的次要发布将不再支持MongoDB Server版本4.2 ，并将支持的最低版本提高到4.4 。此更改与MongoDB软件生命周期时间表一致。

  We recommend making changes to your application to accommodate breaking changes. To learn more about upgrading your server version, see the Release Notes section in the MongoDB Server manual.

• 添加了Scala 3支持。

• 添加自动嵌入支持，作为向量搜索API 的一部分。

• 为响应式流驱动程序添加了 Micrometer/OpenTelemetry 跟踪支持，并包含一般性的 Micrometer支持改进。

• 添加带有蹦床模式的堆栈安全异步循环支持，以防止 Stack Overflow 错误。

• 改进客户端超时处理，以更好地考虑往返时间 (RTT) 变化，以及各种与超时相关的小改进。

• 重复使用 ConnectionSource 以避免额外的服务器选择。

• 恢复 RawBsonDocument 编码的优化编解码器路径，修复性能回归问题。

• 释放 AsyncCommandCursor 中空的 getMore 响应之间的连接，防止空闲变更流到达 maxPoolSize 时耗尽连接池。

• 加密客户端现在使用 writeConcern 多数。

• 处理来自KMS的意外流结束错误。

• 修复了 JsonPrimitive 数字的 JsonBsonEncoder 解析，其中科学格式的数字被解析为普通 Int 或 Long。

• 简化 ServerMonitor 线程名称并删除 = 字符，某些监控系统无法进程该字符。

• 修复了可选的Kotlin BSON解码问题。

• 将 libmongocrypt 升级到 1.17.3。

• 使用 ZstdInputStreamNoFinalizer 进行 Zstandard 解压缩。

• 将 Netty 更新到最新版本。

• 更新 Snappy 以获取最新的安全修复程序。

• 将 JUnit 5 更新到最新版本。

• 从集群中删除服务器时，将日志级别调整为警告。

5.6 中的新增功能

5.6驱动程序发布包括以下更改、修复和功能：

• 添加对Queryable Encryption前缀、后缀和子字符串查询的实验性支持。要学习；了解有关 QE 的更多信息，请参阅正在使用的加密。

  注意

  实验功能

  Queryable Encryption的前缀、后缀和子字符串查询不稳定，在普遍可用 (GA) 之前无法保证其安全性。仅在实验性工作负载中使用它们。

• 将 nsType字段添加到 ChangeStreamDocument 对象。该字段包含变更事件的命名空间类型（COLLECTION、TIMESERIES 或 VIEW）。

• 为 OIDC身份验证添加实验性客户端操作超时 (CSOT)支持。

  注意

  实验功能

  CSOT功能是实验性的，可能在未来的驱动程序发布中发生变化。

• 当为 CSOT 设立 timeoutMS 时，驱动程序将忽略 maxWaitTime 连接设置的值。

• 将 appendMetadata() 方法添加到 MongoClient 类。您可以使用此方法将元数据附加到现有客户端的元数据中。最大元数据大小为 512 MB。

• 向 RewrapManyDataKeyOptions 类添加一个公共构造函数。

• 将 AsyncReadOperation 和 AsyncWriteOperation 接口合并为 ReadOperation 和 WriteOperation 接口。您可以使用 Operations 类中的构建器方法创建读取和写入操作。

• 弃用了 MongoNamespace.COMMAND_COLLECTION_NAME 常量。

• 修复了导致 OIDC 在会话中重新进行身份验证的错误。

• 序列化用 @BsonDiscriminator 注解的 POJO 时，如果属性的 readName 与鉴别器键匹配，则驱动程序仅将该字段序列化一次。

• 对 CommandCursorResult实例调用 next() 或 tryNext() 方法后，驱动程序会清除 CommandCursorResult.results属性以释放内存。

• PojoBuilderHelper 类创建属性模型，其中包括来自抽象类和接口的属性。

• 当集群拓扑结构更改时，驱动程序会发布并记录以下事件：

  • ClusterOpeningEvent：拓扑结构打开时发布

  • ClusterDescriptionChangedEvent：拓扑结构描述更改时发布

  • ClusterClosedEvent：拓扑结构关闭时发布

• 当主节点副本集成员因以下原因之一而过时时，驱动程序会抛出 MongoStalePrimaryException：

  • 选举或发现新的主节点 (primary node in the replica set)成员。

  • 主节点 (primary node in the replica set)节点中 electionId 或 setVersion字段的值与其他副本集中这些字段的值不匹配。

  要学习；了解有关副本集的更多信息，请参阅MongoDB服务器手册中的复制。

5.5.1 中的新功能

5.5.1驱动程序补丁发布包括以下更改：

• 修复由会话中运行的操作（包括ACID 事务中运行的操作）触发时，OIDC 重新身份验证失败的问题。

5.5 中的新增功能

5.5驱动程序发布包括以下更改、修复和功能：

• 添加了在使用默认TLS 传输层时对 connectTimeoutMS 选项的支持。

• 引入性能改进，这些改进反映在驱动程序性能基准测试中。要查看性能基准测试结果，请参阅以下性能改进部分。

5.4 的新增功能

5.4驱动程序发布包括以下更改、修复和功能：

• 添加了对序列化期间 bson-kotlinx 蛇形大小写转换的 BsonConfiguration支持。要学习；了解更多信息，请参阅“序列化”页面上的实施蛇形命名策略部分。

• 支持 CSFLE 和 QE 的 $lookup 操作。要学习；了解更多信息，请参阅服务器手册中的以下参考资料：

  • $lookup and $graphLookup Behavior for CSFLE

  • $lookup and $graphLookup Behavior for QE

• 引入物料清单 (BOM) 来管理您可能在应用程序中使用的MongoDB Java虚拟机（JVM）工件的版本。要查看有关将 BOM 添加到应用程序的说明，请参阅快速入门的“添加驱动程序程序物料清单”步骤。

• 将Amazon Web Services SDK 依赖项更新为 2.30.31 和 1.12.782，以测试 MONGODB-AWS身份验证机制。

• 向 ClientUpdateOneOptions 和 ClientReplaceOneOptions 类添加排序选项。此变更允许您为客户端批量写入中的更新和替换操作设置排序。要了解更多信息，请参阅批量操作指南的“更新操作”和“替换操作”部分。

• 添加Kubernetes对 OIDC身份验证的支持。要学习；了解更多信息，请参阅《企业身份验证机制》指南中的 MONGODB-OIDC： Kubernetes 部分。

• 新增对以下MongoDB 搜索查询操作符的一类支持：

  • phrase

  • regex

  • queryString

  • equals

  • moreLikeThis

  • in

  • wildcard

  要学习；了解更多信息，请参阅 聚合构建器指南的 搜索操作符方法 部分。

• 更新游标以在调用 close() 时刷新 timeoutMS 设置，而不影响操作超时。

• 使您能够在通过指定 hint 选项调用 distinct() 方法时使用索引。

要查看此发布中更改的完整列表，请参阅 GitHub 上的 v.5 发布说明。4

5.3 中的新增功能

5.3驱动程序发布包括以下新功能、改进和修复：

• 重要提示：下一个次要发布将不再支持MongoDB Server版本4.0 ，并将支持的最低版本提高到4.2 。我们建议对应用程序进行更改以适应重大更改。请参阅服务器手册中的“发布说明”部分，学习；了解有关升级的更多信息。

• 添加 BinaryVector 类以实现用于向量存储和检索的BSON二进制子类型 9。 与 Double 实例列表相比，此类可更有效地存储值。 您可以根据向量包含的元素类型创建以下向量类型：

  • Int8BinaryVector：8 位有符号整数的向量

  • Float32BinaryVector：浮点数向量

  • PackedBitBinaryVector：二进制量化向量（处于beta，在正式发布之前可能会有更改）

  要学习；了解有关此功能的更多信息，请参阅Atlas文档中的矢量量化。要学习；了解如何在使用MongoDB Vector Search功能时使用此类型，请参阅MongoDB Vector Search指南。

• 从连接池实施中删除显式公平性。 当您在许多应用程序线程中使用 MongoClient实例时，此更改可能会提高吞吐量。 但是，此更改可能会导致尾部延迟增加。

• 为 updateOne() 和 replaceOne() 方法添加排序选项。此更改还允许您在创建 ReplaceOneModel 和 UpdateOneModel 实例时将排序设立为选项。要学习；了解更多信息，请参阅更新文档和批量操作指南。

• 支持直接将构建者类方法与数据类属性结合使用。要了解更多信息，请参阅将构建者与数据类结合使用指南。此功能由本版本发布的 Kotlin 驱动程序扩展包提供支持。

• 实现客户端批量写入API ，允许您在同一调用中对多个数据库和集合执行写入操作。要学习；了解有关此功能的更多信息，请参阅批量操作指南中的客户端批量写入部分。

5.2 中的新增功能

5.2驱动程序发布包括以下新功能、改进和修复：

• 允许设置客户端操作超时 (CSOT)。此功能允许您在 MongoClient实例上设立单个超时，该超时适用于使用该客户端执行的所有操作。要学习；了解更多信息，请参阅限制服务器执行时间指南。

  当且仅当启用了 CSOT功能时，驱动程序才会忽略以下超时选项：

  • waitQueueTimeoutMS

  • socketTimeoutMS

  • wTimeoutMS

  • maxTimeMS

  • maxCommitTimeMS

  重要

  实验功能

  CSOT 是一项实验性功能，尚未准备好投入生产。在当前发布中，此功能是可选的，现有的超时选项仍然有效。

• 添加 SearchIndexType 类，您可以在构造 SearchIndexModel实例时传递该类。此更改允许您在创建Atlas 搜索或向量搜索索引时指定索引类型。要学习更多信息，请参阅 索引指南中的MongoDB Search 和MongoDB Vector Search 索引。

• 将实施SCRAM-SHA-1和SCRAM-SHA-256身份验证机制的算法委托给已配置的 JCA提供商来实现。 此更改意味着您的应用程序可以使用已配置的 FIPS 兼容 JCA提供商来提供更高级别的安全性。

• 修改 mongodb-crypt 依赖项版本控制以匹配Java虚拟机（JVM）驱动程序的版本控制。未来版本的mongodb-crypt 将与驾驶员一起发布，并股票相同的版本号。升级此发布的驾驶员时，必须将mongodb-crypt 依赖项升级到 v..5 20。要学习；了解更多信息，请参阅《正在使用的加密》指南。

• 由于在所有支持的平台上实施了原生加密，因此性能得到提升。 以下列表描述了根据您的操作系统实现此改进所需的操作：

  • Windows ：将mongodb-crypt版本升级到 v 5.2.0 。

  • Mac ：将mongodb-crypt版本升级到 v 5.2.0 。

  • Linux: Install libmongocrypt.so directly on the file system, instead of using the file that is bundled within the mongodb-crypt JAR file. You can find Linux instructions to install libmongocrypt in the Server manual. If you use a package manager to install libmongocrypt, Java Native Access (JNA) will find it there without further configuration. Alternatively, you can specify the search path by setting the LD_LIBRARY_PATH environment variable to the file path of the libmongocrypt package.

    我们建议直接安装，因为 OpenSSL 二进制文件可能不兼容，因此捆绑的共享库不会与 OpenSSL 链接。

    共享库加载由 JNA 处理。您可以在NativeLibrary 类文档中查看库加载搜索路径顺序的规则。

• 修复了导致 InsertOneResult.getInsertedId() 和 InsertManyResult.getInsertedIds() 方法在某些情况下返回不正确文档ID 的问题。此更改将向后移植到Kotlin驱动程序v5.1.4 和 v4.11.4。

• 当分片集群操作不成功时，如果有其他 mongos 服务器可用，则驱动程序会避免选择同一 mongos服务器进行操作重试。

• 添加应用程序使用 GraalVM 原生映像时所需的可访问性元数据。此元数据取代了在使用驱动程序库时收集可达性元数据的需要。要学习；了解更多信息，请参阅 GraalVM 文档中的可达性元数据。

  This change does not add the libjnidispatch and libmongocrypt resource entries, because adding entries for all supported platforms (targets) significantly affects the size of native executables built using GraalVM Native Image. View this sample resource-config.json file in the driver GitHub repository to see how to specify these entries explicitly if your application depends on the org.mongodb:mongodb-crypt library.

• 通过扩展VectorSearchOptions API引入以下特定选项子类型，从而启用精确向量搜索：

  • ExactVectorSearchOptions：使用此选项类型可启用精确匹配，确保结果是与给定查询向量最接近的向量。

  • ApproximateVectorSearchOptions：使用此选项类型可以启用可能不会返回精确的最近向量的搜索。 实例化此类型时，您可以传递numCandidates参数，以指定要考虑的最近邻数量。

  要学习；了解有关使用MongoDB Vector Search功能的更多信息，请参阅 Aggregates Builders指南中的MongoDB Vector Search。

• 添加对来自kotlinx-datetime库的序列化器的支持，该支持允许您将Kotlin日期和时间类型映射到BSON作为预期类型，而不是作为字符串。 要学习；了解更多信息，请参阅Kotlin序列化指南的序列化日期和时间部分。

• Supports serialization of JsonElement values. To work with the JsonElement type, you must add the kotlinx-serialization-json library as a dependency in your application.

5.1.3 中的新功能

5.1.3驱动程序补丁发布包括以下更改：

• 修复了使用Cursor类型时可能导致断言错误的问题。

5.1.2 中的新功能

5.1.2驱动程序补丁发布包括以下更改：

• 支持使用可为 null 的泛型参数类型编码Kotlin数据类。 示例，您可以在以下代码中对Container类进行编码：

  @Serializable
  data class Box<T>(
      val boxed: T
  )
  @Serializable
  data class Container(
      val box: Box<String?>
  )

5.1.1 中的新功能

5.1.1驱动程序补丁发布包括以下更改：

• 使用 MONGODB-OIDC身份验证机制时，不得在 authMechanismProperties 连接string值中包含逗号字符。 要学习；了解有关此行为的更多信息，请参阅 Enterprise Authentication指南的MONGODB-OIDC部分。

5.1 中的新增功能

本部分包括以下信息：

• 5.1 中的弃用

• 5.1 中的改进

• 5.1 中的新功能

5.0 中的新增功能

5.0 驱动程序版本的新功能包括：

• KotlinSerializerCodecProvider构造函数现在接受serializersModule和bsonConfiguration对象：

  KotlinSerializerCodec.create(clazz.kotlin, serializersModule=serializersModule, bsonConfiguration=bsonConfiguration)

  这样可以更轻松地自定义配置。

• 修复了导致container类型擦除的 Kotlin 反射错误。

4.11 中的新增功能

本部分包括以下信息：

• 4.11 中的弃用

• 4.11 中的新增功能

4.10 中的新增功能

• 支持 Kotlin 服务器端使用，包括协程和同步应用程序。

• 编解码器对 Kotlin 数据类的支持。

• 支持kotlinx.serialization库