版本说明

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。

要学习；了解有关此发布的更多信息，请参阅Github上的 v5.8 发布说明。

5.7 中的新增功能

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

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

  我们建议对应用程序进行更改以适应破坏性变更 (breaking change)。要学习；了解有关升级服务器版本的更多信息，请参阅MongoDB Server手册中的发布说明部分。

• 添加了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 Server手册中的复制。

5.5.1 中的新功能

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

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

5.5 中的新增功能

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

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

5.4 的新增功能

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

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

  • CSFLE 的 $lookup 和 $graphLookup 行为

  • QE 的 $lookup 和 $graphLookup 行为

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

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

• ClientUpdateOneOptions为 和ClientReplaceOneOptions 类添加排序选项。此更改允许您为客户端批量写入中的更新和替换操作设立排序顺序。要学习；了解更多信息，请参阅批量操作指南的更新示例和替换示例部分。

• 添加Kubernetes对 OIDC身份验证的支持。要学习；了解更多信息，请参阅 OIDC（工作负载身份联合）指南的Kubernetes部分。

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

  • phrase

  • regex

  • queryString

  • equals

  • moreLikeThis

  • in

  • wildcard

  要了解更多信息，请参阅MongoDB搜索指南的创建管道搜索阶段部分。

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

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

要查看此发布中的完整更改列表，请参阅Github上的v5.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 实例时将排序设立为选项。要学习；了解更多信息，请参阅更新文档和批量写入操作指南。

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

5.2.1 中的新功能

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

• 修复了导致使用 Quarkus 构建的应用程序在初始化 libmongocrypt 绑定时抛出 java.lang.UnsatisfiedLinkError 的问题。

• 修复导致 mongodb-driver-core包在部署到 OSGi 运行时时出错的问题。 Import-Package org.mongodb:mongodb-driver-core 清单属性不再需要 com.oracle.svm.core.annotate.* 包。

5.2 中的新增功能

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

• 连接 URI 中托管名和客户端选项之间的正斜杠 (/) 字符是可选的。驱动程序以相同的方式解析以下连接 URI 示例：

  // Connection URI with delimiting forward-slash
  String uri = "mongodb://example.com/?w=majority";
  // Connection URI without delimiting forward-slash
  String uri = "mongodb://example.com?w=majority";

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

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

  • waitQueueTimeoutMS

  • socketTimeoutMS

  • wTimeoutMS

  • maxTimeMS

  • maxCommitTimeMS

  重要

  实验功能

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

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

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

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

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

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

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

  • Linux ：直接在文件系统上安装libmongocrypt.so ，而不是使用mongodb-crypt JAR文件中捆绑的文件。 您可以在服务器手册中找到安装libmongocrypt的Linux说明。 如果使用包管理器安装libmongocrypt ， Java Native Access (JNA) 将在那里找到它，而无需进一步配置。 或者，您可以通过将LD_LIBRARY_PATH环境变量设置为libmongocrypt包的文件路径来指定搜索路径。

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

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

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

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

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

  此更改不会添加 libjnidispatch 和 libmongocrypt资源条目，因为为所有支持的平台（目标）添加条目会显着影响使用 GraalVM 原生映像构建的原生可执行文件的大小。查看驱动程序GitHub存储库中的此示例 资源-配置.json 文件，了解在您的应用程序依赖于 org.mongodb:mongodb-crypt 库的情况下如何显式指定这些条目。

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

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

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

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

5.1.3 中的新功能

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

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

5.1.2 中的新功能

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

• 修复了在您将扩展泛型基类的基类指定为 MongoCollection实例的泛型类型时，驱动程序无法对扩展泛型基类的具体类进行编码和解码的问题。

• 修复了使用 SOCKS 5代理功能时如何验证域名的相关问题，从而允许在顶级域中使用六个字符以上的域名。

5.1.1 中的新功能

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

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

• 通过删除冗余字节大量克隆来优化GridFS吞吐量。 GridFSDownloadStream和GridFSUploadStream类型使用BsonDocument类型而不是Document 。

5.1 中的新增功能

本部分包括以下信息：

• 5.1 中的弃用
• 5.1 中的改进
• 5.1 中的新功能

5.0 中的新增功能

本部分包括以下信息：

• 5.0 中的弃用内容
• 5.0 中的行为变更
• 5.0 中的新功能

4.11 中的新增功能

本部分包括以下信息：

• 4.11 中的弃用
• 4.11 中的新增功能

4.10 中的新增功能

4.10 版驱动程序的新增功能包括：

• 实现统计聚合的 Accumulators.percentile() 和 Accumulators.median() 方法。

• com.mongodb.client.model.search 包中的接口现在标记为 @Sealed，而不是 @Evolving。密封接口不得由库的用户扩展或实现。

• 解决了驱动程序为重试操作发出重复日志消息的问题。驱动程序现在为每个重试操作正确发出一条日志消息。

• org.bson.codecs.Parameterizable 接口已弃用。如果解码器适用于参数化类型，请重写编解码器的 CodecProvider 上的 CodecProvider.get() 方法，而不是在自定义 Codec 类型上实现此接口。

• 支持自定义 DNS 解析程序。

• 支持可查询加密 (QE)。要详细了解使用 QE 功能的要求，请参阅可查询加密驱动程序兼容性表。