版本说明

了解以下版本中的新功能：

版本 5.5.1
版本 5.5
版本 5.4
版本 5.3
版本 5.2.1
版本 5.2
版本 5.1.3
版本 5.1.2
版本 5.1.1
版本 5.1
版本 5.0
版本 4.11
版本 4.10

5.5.1 中的新功能

5.5.1 驾驶员补丁发布包括以下更改：

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

5.5 中的新增功能

重要

删除对MongoDB Server 4.0 的支持

Java驾驶员v5.5 删除了对MongoDB Server 4.0 的支持。要学习；了解有关服务器兼容版本的详情，请参阅兼容性。

5.5驾驶员发布包括以下更改、修复和功能：

引入性能改进，这些改进反映在驾驶员性能基准测试中。要查看性能基准测试结果，请参阅以下性能改进部分。

性能改进

本节中的表格显示了同步Java驾驶员的性能测试结果。测试在具有以下配置的MongoDB Server 8.0部署上进行：

在 localhost 上运行，网络延迟可以忽略不计。在延迟较高的环境中，性能改进可能不太明显。
身份验证已禁用。
TLS 已禁用。

我们预计所有MongoDB Java驱动程序都会有类似的性能提升，因为它们股票改进的 driver-core API。

标准传输设置

下表显示了对配置有标准传输设置的驾驶员v5.5 进行性能测试的结果。每行都包含测试的功能、性能改进百分比和 z 分数。

功能	改进百分比	Z 分数
深度BSON解码	19.44%	5.4
深度BSON编码	102%	22.8
查找多个并清空游标	25.08%	13.72
通过ID查找	2.7%	3.16
平面BSON解码	31.2%	9.38
平面BSON编码	199.5%	12.34
完整BSON解码	16.5%	7.23
完整BSON编码	147.3%	10.39
JSON-LD 多文件导入	21.8%	8.21
包含大型文档的客户端批量插入	91.3%	24.44
包含大型文档的集合批量插入	96.5%	8.79
批量插入大型文档	93.3%	8.11
批量插入小文档	39.3%	5.72
插入包含大型文档的文档	82.4%	7.28
包含小文档的客户端批量插入	49.5%	17.99
包含小文档的集合批量插入	47.8%	6.44

Netty 传输设置

下表显示了使用 Netty 传输设置配置的驾驶员v5.5 的性能测试结果。每行都包含测试的功能、性能改进百分比和z 分数。

功能	改进百分比	Z 分数
查找多个并清空游标	40.3%	14.81
通过ID查找	4.4%	4.12
JSON-LD 多文件导入	16.9%	3.77
包含大型文档的客户端批量插入	54.8%	14.49
包含大型文档的集合批量插入	104.9%	38.72
批量插入大型文档	74.6%	65.55
插入包含大型文档的文档	66.6%	58.65
包含小文档的客户端批量插入	36.1%	15.41
包含小文档的集合批量插入	39.3%	37.38
批量插入小文档	35.1%	41.51

提示

要进一步学习；了解我们如何进行驾驶员性能基准测试，请参阅性能基准测试规范。

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部分。
新增对以下Atlas Search查询符的一级支持：
- phrase
- regex
- queryString
- equals
- moreLikeThis
- in
- wildcard
要学习；了解更多信息，请参阅Atlas Search指南的创建管道搜索阶段部分。
更新游标以在调用 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文档中的矢量量化。要学习；了解如何在使用Atlas Vector Search功能时使用此类型，请参阅Atlas 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 中的新增功能

重要

删除对MongoDB Server 3.6 的支持

Java驾驶员v5.2 删除了对MongoDB Server 3.6 的支持。要学习；了解有关服务器兼容版本的更多信息，请参阅兼容性。

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实例上设立单个超时，该超时适用于使用该客户端执行的所有操作。要学习；了解更多信息，请参阅限制服务器执行时间指南。
重要
已弃用的超时选项
以下超时选项已弃用：
- waitQueueTimeoutMS
- socketTimeoutMS
- wTimeoutMS
- maxTimeMS
- maxCommitTimeMS
使用 CSOT功能来替换这些选项的功能。
添加SearchIndexType类，您可以在构造SearchIndexModel实例时传递该类。此更改允许您在创建Atlas Search或 Vector Search索引时指定索引类型。要学习；了解更多信息，请参阅索引指南中的Atlas Search和 Vector Search 索引。
将实施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驾驶员v 5.1.4和 v 4.11.4 。
当分片集群操作不成功时，如果有其他mongos服务器可用，则驾驶员会避免选择同一mongos服务器进行操作重试。
添加应用程序使用 GraalVM 原生映像时所需的可访问性元元数据。此元数据取代了在使用驾驶员程序库时收集可达性元数据的需要。要学习；了解更多信息，请参阅 GraalVM 文档中的可达性元数据。
此更改不会添加 libjnidispatch 和 libmongocrypt资源条目，因为为所有支持的平台（目标）添加条目会显着影响使用 GraalVM 原生映像构建的原生可执行文件的大小。查看驾驶员Github存储库中的示例资源配置.json文件，了解在应用程序依赖于 org.mongodb:mongodb-crypt 库的情况下如何显式指定这些条目。
通过扩展VectorSearchOptions API引入以下特定选项子类型，从而启用精确向量搜索：
- ExactVectorSearchOptions：使用此选项类型可启用精确匹配，确保结果是与给定查询向量最接近的向量。
- ApproximateVectorSearchOptions：使用此选项类型可以启用可能不会返回精确的最近向量的搜索。实例化此类型时，您可以传递numCandidates参数，以指定要考虑的最近邻数量。
要学习；了解有关使用Atlas Vector Search功能的更多信息，请参阅聚合构建指南中的Atlas 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 中的新增功能

警告

此版本中的弃用内容

为避免驱动程序的未来主要版本发生破坏性变更 (breaking change)，请替换任何依赖于已弃用程序元素的应用程序代码。

本部分包括以下信息：

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

5.1 中的弃用

对MongoDB Server v 3.6的支持已弃用，并将在下一驾驶员发布中删除。要学习；了解如何升级MongoDB Server部署，请参阅MongoDB Server手册中的发布说明。

5.1 中的改进

GraalVM 原生映像技术的内部测试。这些测试涉及使用 GraalVM 原生映像工具构建原生应用程序。
增强对 MONGODB-OIDC身份验证机制的支持。有关 OIDC 的更多信息，请参阅 OIDC（工作负载身份联合）指南。

5.1 中的新功能

引入serverMonitoringMode 连接 URI 选项。有关此选项的更多信息，请参阅 Stable API指南。

5.0 中的新增功能

警告

此版本中的破坏性变更 (breaking change)

此驱动程序版本引入了破坏性变更 (breaking change)。有关这些更改的列表，请参阅升级指南中的版本 5.0 破坏性变更 (breaking change)。

警告

此版本中的弃用内容

为避免驱动程序的未来主要版本发生破坏性变更 (breaking change)，请替换任何依赖于已弃用程序元素的应用程序代码。

本部分包括以下信息：

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

5.0 中的弃用内容

org.mongodb.scala.Observable.completeWithUnit() 方法已弃用。此方法不再可用，因为驱动程序现在公开的是 org.mongodb.scala.Observable[Unit]，而不是 org.mongodb.scala.Observable[Void]。这与本版本中有关 Observables 的破坏性变更有关。

5.0 中的行为变更

com.mongodb.event.ConnectionReadyEvent上的getElapsedTime()方法包括交付ConnectionCreatedEvent所需的时间。也就是说，返回的时间包括com.mongodb.event.ConnectionPoolListener.connectionCreated()方法的持续时间。
com.mongodb.event.ConnectionCheckedOutFailedEvent和com.mongodb.event.ConnectionCheckedOutEvent上的getElapsedTime()方法包括传送com.mongodb.event.ConnectionCheckOutStartedEvent所需的时间。也就是说，返回的时间包括com.mongodb.eventConnectionPoolListener.connectionCheckOutStarted()方法的持续时间。

5.0 中的新功能

5.0 驱动程序版本引入了以下功能：

添加对listCollections命令的authorizedCollection选项的支持。这是通过更改com.mongodb.client.MongoDatabase.listCollectionNames()方法来实现的。返回类型现在为com.mongodb.client.ListCollectionNamesIterable ，而以前是MongoIterable<String> 。此更改允许使用ListCollectionNamesIterable.authorizedCollections()方法并指定authorizedCollections选项来配置返回值。对以下类和接口进行了等效更改：
- com.mongodb.reactivestreams.client.MongoDatabase
- org.mongodb.scala.MongoDatabase
- com.mongodb.kotlin.client.MongoDatabase
- com.mongodb.kotlin.client.coroutine.MongoDatabase
这些更改对 listCollectionsNames() 方法引入了二进制重大更改。有关 MongoDatabase.listCollectionNames() 方法和 authorizedCollections 选项的更多信息，请参阅listCollections MongoDB Server手册页或获取集合列表。

注意

v 5.0.2 补丁发布修复了与使用 SOCKS 5代理功能时如何验证域名相关的问题，允许您在顶级域中使用六个字符以上的域名。

4.11 中的新增功能

本部分包括以下信息：

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

4.11 中的弃用

警告

此版本中的弃用内容

为避免驱动程序未来的主要版本出现破坏性更改，请替换任何依赖于弃用方法和类型的应用程序代码。

4.11 版驱动程序已弃用以下内容：

DBCollection 类的 getStats() 和 isCapped() 实例方法已被弃用。相应的服务器命令在 MongoDB v6.2 及更高版本中已弃用。请改用 $collStats 聚合管道阶段来检索这些方法提供的信息。您可以按照以下代码示例所示运行聚合：

Cursor cursor = collection.aggregate(Arrays.asList(
        new BasicDBObject("$collStats",
                new BasicDBObject("storageStats", new BasicDBObject()))),
        AggregationOptions.builder().build()
);

要确定集合是否为上限集合，请访问前面示例聚合中的 Cursor 实例返回的 storageStats.capped 字段的值。

如需了解有关 $collStats 聚合操作符的更多信息，请参阅“$collStats（聚合）服务器”手册条目。

以下与网络地址相关的方法已弃用，并将在 v5.0 中删除：
- ServerAddress 方法 getSocketAddress() 和 getSocketAddresses()。
  使用 java.net.InetAddress 的 getByName() 实例方法，而不是 getSocketAddress()。
  使用 java.net.InetAddress 的 getAllByName() 实例方法，而不是 getSocketAddresses()。
- UnixServerAddress 方法 getUnixSocketAddress()。
  构建 jnr.unixsocket.UnixSocketAddress 实例，而不是 getUnixSocketAddress()。将 UNIX 套接字文件的完整路径传递给构造函数。默认情况下，MongoDB 会创建位于 "/tmp/mongodb-27017.sock" 的 UNIX 套接字文件。要了解有关 UnixSocketAddress 的详情，请参阅 UnixSocketAddress API 文档。

以下与StreamFactory接口相关的方法和类型已弃用，并计划在 v5.0 中删除：

streamFactoryFactory() 方法来自 MongoClientSettings.Builder
getStreamFactoryFactory() 方法来自 MongoClientSettings
NettyStreamFactoryFactory class
NettyStreamFactory class
AsynchronousSocketChannelStreamFactory class
AsynchronousSocketChannelStreamFactoryFactory class
BufferProvider class
SocketStreamFactory class
Stream class
StreamFactory class
StreamFactoryFactory class
TlsChannelStreamFactoryFactory class

如果使用 MongoClientSettings.Builder.streamFactoryFactory() 来配置 Netty，则代码可能如下所示：

import com.mongodb.connection.netty.NettyStreamFactoryFactory;
// ...
MongoClientSettings settings = MongoClientSettings.builder()
        .streamFactoryFactory(NettyStreamFactoryFactory.builder().build())
        .build();

将此代码替换为 TransportSettings.nettyBuilder()，如下例所示：

import com.mongodb.connection.TransportSettings;
// ...
MongoClientSettings settings = MongoClientSettings.builder()
        .transportSettings(TransportSettings.nettyBuilder().build())
        .build();

4.11 中的新增功能

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

支持使用 SOCKS5 代理连接到 MongoDB。要了解详情，请参阅使用 SOCKS5 代理连接到 MongoDB。

注意

v 4.11.3 补丁发布修复了与使用 SOCKS 5代理功能时如何验证域名相关的问题，允许您在顶级域中使用六个字符以上的域名。

向 ChangeStreamDocument 类添加 getSplitEvent() 方法，从而识别超过 16 MB 的变更流事件的片段。您必须在变更流中使用聚合阶段 $changeStreamSplitLargeEvent 来处理超过 16 MB 的事件。要了解详情，请参阅分割大型变更流事件。
已为 $vectorSearch 添加了聚合阶段构建器。要了解详细信息，请参阅 Atlas Vector Search。
添加了 Atlas Search 索引管理助手。如需了解更多信息，请参阅“Atlas Search 索引”。
更新了 Snappy 和zstd压缩库依赖项版本。要学习；了解有关当前依赖项版本的更多信息，请参阅压缩网络流量。
为以下类添加 getElapsedTime() 方法，以监控连接池事件的持续时间：
支持 Java 21 虚拟线程和结构化并发。驱动程序内部结构已更新，以避免不必要地虚拟线程绑定，并保留线程中断状态，后者对于用于取消的结构化并发很重要。
要了解有关虚拟线程的详细信息，请参阅虚拟线程 JDK 增强提案。要了解有关结构化并发的详细信息，请参阅结构化并发 JDK 增强提案。
已更新以下类型的 API 文档：

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 功能的要求，请参阅可查询加密驱动程序兼容性表。

后退

第三方集成

来年

兼容性

5.5.1 中的新功能

5.5 中的新增功能

重要

删除对MongoDB Server 4.0 的支持

性能改进

标准传输设置

Netty 传输设置

提示

5.4 的新增功能

5.3 中的新增功能

5.2.1 中的新功能

5.2 中的新增功能

重要

删除对MongoDB Server 3.6 的支持

重要

已弃用的超时选项

5.1.3 中的新功能

5.1.2 中的新功能

5.1.1 中的新功能

5.1 中的新增功能

警告

此版本中的弃用内容

5.1 中的弃用

5.1 中的改进

5.1 中的新功能

5.0 中的新增功能

警告

此版本中的破坏性变更 (breaking change)

警告

此版本中的弃用内容

5.0 中的弃用内容

5.0 中的行为变更

5.0 中的新功能

注意

4.11 中的新增功能

4.11 中的弃用

警告

此版本中的弃用内容

4.11 中的新增功能

注意

4.10 中的新增功能