Release Notes

What's New in 5.6

The 5.6 driver release includes the following changes, fixes, and features:

• Adds experimental support for Queryable Encryption prefix, suffix, and substring queries. To learn more about QE, see In-Use Encryption.

  Note

  Experimental Feature

  Queryable Encryption prefix, suffix, and substring queries are unstable, and their security is not guaranteed until they're generally available (GA). Use them in experimental workloads only.

• Adds an nsType field to ChangeStreamDocument objects. This field contains the namespace type (COLLECTION, TIMESERIES, or VIEW) of the change event.

• Adds client-side operation timeout (CSOT) support for OIDC authentication.

• When timeoutMS is set for CSOT, the driver ignores the value of the maxWaitTime connection setting.

• Adds an appendMetadata() method to the MongoClient class. You can use this method to append metadata to an existing client's metadata. The maximum metadata size is 512 MB.

• Adds a public constructor to the RewrapManyDataKeyOptions class.

• Merges the AsyncReadOperation and AsyncWriteOperation interfaces into the ReadOperation and WriteOperation interfaces. You can create read and write operations by using builder methods in the Operations class.

• Deprecates the MongoNamespace.COMMAND_COLLECTION_NAME constant.

• Fixes a bug that prevented OIDC reauthentication within a session.

• When serializing a POJO annotated with @BsonDiscriminator, if the property's readName matches the discriminator key, the driver serializes the field only once.

• After you call the next() or tryNext() method on a CommandCursorResult instance, the driver clears the CommandCursorResult.results property to free memory.

• The PojoBuilderHelper class creates property models that include properties from abstract classes and interfaces.

• The driver publishes and logs the following events when the cluster topology changes:

  • ClusterOpeningEvent: Published when the topology opens

  • ClusterDescriptionChangedEvent: Published when the topology description changes

  • ClusterClosedEvent: Published when the topology closes

• The driver throws a MongoStalePrimaryException when the primary replica set member becomes stale for one of the following reasons:

  • A new primary member is elected or discovered.

  • The value of the electionId or setVersion field in the primary member doesn't match the values of these fields in the other replica set members.

  To learn more about replica sets, see Replication in the MongoDB Server manual.

What's New in 5.5.1

The 5.5.1 driver patch release includes the following changes:

• Fixes an issue where OIDC reauthentication failed when triggered by an operation run in a session, including operations run in a transaction.

What's New in 5.5

The 5.5 driver release includes the following changes, fixes, and features:

• Introduces performance improvements that are reflected in the driver performance benchmarks. To view the results of the performance benchmark tests, see the following Performance Improvements section.

What's New in 5.4

The 5.4 driver release includes the following changes, fixes, and features:

• Supports $lookup operations for CSFLE and QE. To learn more, see the following references in the Server manual:

  • $lookup and $graphLookup Behavior for CSFLE

  • $lookup and $graphLookup Behavior for QE

• Introduces a Bill of Materials (BOM) to manage versions of MongoDB JVM artifacts that you might use in your application. To view instructions on adding the BOM to your application, see the Add the Java driver Bill of Materials step of the Get Started tutorial.

• Updates AWS SDK dependencies to 2.30.31 and 1.12.782 for testing the MONGODB-AWS authentication mechanism.

• Adds a sort option to the ClientUpdateOneOptions and ClientReplaceOneOptions classes. This change allows you to set a sort order for update and replace operations in client bulk writes. To learn more, see the Update Example and Replace Example sections of the Bulk Operations guide.

• Adds Kubernetes support for OIDC authentication. To learn more, see the Kubernetes section of the OIDC (Workload Identity Federation) guide.

• Adds first class support for the following MongoDB Search query operators:

  • phrase

  • regex

  • queryString

  • equals

  • moreLikeThis

  • in

  • wildcard

  To learn more, see the Create Pipeline Search Stages section of the MongoDB Search guide.

• Updates cursors to refresh the timeoutMS setting when you call close() without affecting the operation timeout.

• Enables you to use an index when calling the distinct() method by specifying a hint option.

To view a full list of changes in this release, see the v5.4 release notes on GitHub.

What's New in 5.3

The 5.3 driver release includes the following changes, fixes, and features:

• Important: The next minor release will drop support for MongoDB Server version 4.0 and raise the minimum supported version to 4.2. We recommend making changes to your application to accommodate breaking changes. See the Release Notes section in the Server manual to learn more about upgrading.

• Adds the BinaryVector class to implement BSON Binary Subtype 9 for vector storage and retrieval. This class provides more effective storage of values compared a list of Double instances. You can create the following vector types based on the type of elements your vector contains:

  • Int8BinaryVector: Vector of 8-bit signed integers

  • Float32BinaryVector: Vector of floating-point numbers

  • PackedBitBinaryVector: Binary quantized vector (In beta and subject to change before becoming generally available)

  To learn more about this feature, see Vector Quantization in the Atlas documentation. To learn about how to use this type when using the MongoDB Vector Search feature, see the MongoDB Vector Search guide.

• Removes explicit fairness from the connection pool implementation. This change might contribute to better throughput when you use a MongoClient instance in many application threads. However, this change might cause increased tail latency.

• Adds a sort option to the updateOne() and replaceOne() methods. This change also allows you to set a sort as an option when creating ReplaceOneModel and UpdateOneModel instances. To learn more, see the Update Documents and Bulk Write Operations guides.

• Adds a client bulk write API that allows you to perform write operations on multiple databases and collections at once. To learn more about this feature, see the Client Bulk Write section of the Bulk Operations guide.

What's New in 5.2.1

The 5.2.1 driver patch release includes the following changes:

• Fixes an issue that caused applications built with Quarkus to throw a java.lang.UnsatisfiedLinkError when initializing libmongocrypt bindings.

• Fixes an issue that caused the mongodb-driver-core package to error when deployed to an OSGi runtime. The Import-Package org.mongodb:mongodb-driver-core manifest attribute no longer requires the com.oracle.svm.core.annotate.* packages.

What's New in 5.2

The 5.2 driver release includes the following changes, fixes, and features:

• A forward-slash (/) character between the host names and client options in a connection URI is optional. The driver parses the following connection URI examples in the same way:

  // 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";

• Enables setting a client-side operations timeout (CSOT). This feature allows you to set a single timeout on your MongoClient instance that applies to all operations performed with that client. To learn more, see the Limit Server Execution Time guide.

  Important

  Deprecated Timeout Options

  The following timeout options are deprecated:

  • waitQueueTimeoutMS

  • socketTimeoutMS

  • wTimeoutMS

  • maxTimeMS

  • maxCommitTimeMS

  Use the CSOT feature to replace the functionality of these options.

• Adds the SearchIndexType class, which you can pass when constructing a SearchIndexModel instance. This change allows you to specify the index type when creating an Atlas Search or Vector Search index. To learn more, see MongoDB Search and Vector Search Indexes in the Indexes guide.

• Delegates the implementation of the algorithms that implement the SCRAM-SHA-1 and SCRAM-SHA-256 authentication mechanisms to the configured JCA provider. This change means that your application can use a configured FIPS-compliant JCA provider to provide a higher level of security.

• Revises the mongodb-crypt dependency versioning to match the versioning for the JVM drivers. Future versions of mongodb-crypt will be released alongside the driver and will share the same version number. You must upgrade your mongodb-crypt dependency to v5.2.0 when upgrading your driver for this release. To learn more, see the In-Use Encryption guide.

• Performance improvements due to implementation of native cryptography on all supported platforms. The following list describes the actions needed to implement this improvement depending on your operating system:

  • Windows: Upgrade your mongodb-crypt version to v5.2.0.

  • Mac: Upgrade your mongodb-crypt version to v5.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.

    We recommend direct installation because the bundled shared library does not link with OpenSSL due to the potential for OpenSSL binary incompatibilities.

    The shared library loading is handled by JNA. You can view the rules for library loading search path order in the NativeLibrary class documentation.

• Fixes an issue that caused the InsertOneResult.getInsertedId() and InsertManyResult.getInsertedIds() methods to return incorrect document IDs in some situations. This change is backported to Java driver v5.1.4 and v4.11.4.

• When a sharded cluster operation is unsuccessful, the driver avoids selecting the same mongos server for operation retry attempts if other mongos servers are available.

• Adds reachability metadata needed when your application uses GraalVM Native Image. This metadata replaces the need for collecting reachability metadata when using the driver libraries. To learn more, see Reachability Metadata in the GraalVM documentation.

  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.

• Enables exact vector search by extending the VectorSearchOptions API to introduce the following specific option subtypes:

  • ExactVectorSearchOptions: Use this options type to enable precise matching, ensuring that results are the closest vectors to a given query vector.

  • ApproximateVectorSearchOptions: Use this options type to enable searches that might not return the exact closest vectors. You can pass a numCandidates parameter when instantiating this type to specify the number of nearest neighbors to consider.

  To learn more about using the MongoDB Vector Search feature, see MongoDB Vector Search in the Aggregates Builders guide.

What's New in 5.1.3

The 5.1.3 driver patch release includes the following changes:

What's New in 5.1.2

The 5.1.2 driver patch release includes the following changes:

• Fixes an issue that prevents the driver from encoding and decoding concrete classes that extend generic base classes, in cases that you specify the base class as the generic type of the MongoCollection instance.

• Fixes an issue related to how domain names are validated when you use SOCKS5 proxy functionality, allowing you to use domain names with more than six characters in the top-level domain.

What's New in 5.1.1

The 5.1.1 driver patch release includes the following changes:

• When using the MONGODB-OIDC authentication mechanism, you must not include comma characters in the authMechanismProperties connection string value. To learn more about this behavior, see the MONGODB-OIDC guide.

• Optimizes GridFS throughput by removing redundant byte array cloning. The GridFSDownloadStream and GridFSUploadStream types use the BsonDocument type instead of Document.

What's New in 5.1

This section includes the following information:

• Deprecations in 5.1

• Improvements in 5.1

• New Features in 5.1

What's New in 5.0

This section includes the following information:

• Deprecations in 5.0

• Behavioral changes in 5.0

• New features in 5.0

What's New in 4.11

This section includes the following information:

• Deprecations in 4.11

• New Features in 4.11

What's New in 4.10

New features of the 4.10 driver release include:

• Implementation of the Accumulators.percentile() and Accumulators.median() methods for statistical aggregations.

• Interfaces in the com.mongodb.client.model.search package are now marked as @Sealed instead of @Evolving. Sealed interfaces must not be extended or implemented by consumers of the library.

• Resolved an issue where the driver emitted duplicate log messages for retry operations. The driver now correctly emits one log message for each retry operation.

• The org.bson.codecs.Parameterizable interface is deprecated. Instead of implementing this interface on a custom Codec type, override the CodecProvider.get() method on the codec's CodecProvider if the codec is intended for a parameterized type.

• Support for custom DNS resolvers.

• Support for Queryable Encryption (QE). To learn more about the requirements for using the QE feature, see the Queryable Encryption Driver Compatibility Table.