Skip to content

2026

  • 2 min read

0.30.0 • BSON refactor, type-aware operators and Multiplatform progress

This is KtMongo's greatest release yet. It contains multiple breaking changes, though they should not impact users in major ways.

The BSON refactor

With the growth of the library, we have noticed that the design of the BSON classes was suboptimal.

  • Bson has been renamed to BsonDocument
  • BsonValue has been created
  • BsonDocumentReader has been removed (its functionality is now included directly in BsonDocument)
  • BsonArrayReader has been removed (its functionality is now included directly in BsonArray)
  • BsonValueReader has been removed (its functionality is now included directly in BsonValue)
  • All reading methods have been renamed to encode variants
  • The API to access data from BsonDocument, BsonArray and BsonValue has been rewritten, with conversion functions to Map, List, Iterable and Sequence
  • All implementations now throw the same BsonDecodingException on failure
  • We now test KtMongo against both the official's reflection-based and KotlinX.Serialization-based libraries
  • BsonDocument, BsonArray and BsonValue has a factory property to access the factory which created them (0fb55a77)
  • The types BsonDocument, BsonArray and BsonValue can now be serialized and deserialized, which is convenient for handling dynamic or untyped data (!238)

Related changes in the official BSON implementation:

  • BsonFactory is changed from an interface to an expect class
  • Kotlin primitive types can now be serialized and deserialized without additional configuration (60a016ae)

For more information, see #112 and !223.

The operators refactor

The KtMongo DSL now has a templating engine, which allows generating convenience overloads for most operators. In most situations, aggregation queries don't need the of() operator anymore.

Before: 

Target::score set (of(2) * of(Target::score) * of(3))

After: 

Target::score set (2 * Target::score * 3)

All operators now have an additional overload that accepts KType as a last parameter. These overloads are not meant to be called directly by users, you should almost always call the overload that doesn't have a KType parameter.

Operators are now inline reified, which allows the serialization library to know about type parameters (which were previously stripped during compilation). This information is not yet used in all situations.

Additionally:

Route to Multiplatform

  • The entire DSL can now compile and run on KotlinJS in addition to the JVM (!239). More platforms are coming in the future.
  • The repository now contains a prototype Multiplatform driver (!240).

GeoJSON

  • Added the seven GeoJSON data types under the Geo interface (#76, !241)
  • For now, no operators use them. However, they are serializable.

Deployment

  • Apple x64 targets have been removed, because they are deprecated

Documentation

  • 1 min read

0.29.0 • ### MongoDB support

Due to a tcmalloc bug, MongoDB 8.x cannot run under the Linux kernel 6.19+. Because our testing infrastructure runs under such a kernel, we are not able to continue testing the library with MongoDB 8.x. We are not aware of any differences in MongoDB 8.x that could affect KtMongo. Testing will MongoDB 8.x will restart once tcmalloc is fixed. Follow this issue to learn more.

Additionally, we will no longer support MongoDB 6.x releases, as MongoDB themselves have stopped supporting it.

BSON

  • Added support for JSONPath filter expressions: BsonPath("$.[?a>b]") (#93, !183)

BSON (Multiplatform)

  • Removed useless logging (!217)

DSL

  • Added the $median and $percentile accumulators (#7, !213)

Drivers

  • Added MongoCollection.exists {} to efficiently test if a document exists (#56, !218)

Documentation

  • The API reference will now be built with Dokka MkDocs 0.6.1, which provides many major improvements. Your bookmarks may have become invalid.
  • 1 min read

0.28.0 • BSON Vector support, easily create ObjectId instances, usability improvements

BSON

  • Added support for vector types: Vector, ByteVector, FloatVector and BooleanVector (#106, !194)

Drivers (official)

  • Added the method MongoCollection.newId() to easily generate new ObjectId instances using the collection's generator (!203)
  • Fixed a dependency declaration issue which lead to JvmBsonContext not being available to users (!207)

DSL

  • Fixed gteNotNull and similar operators breaking when the optional filter is not present (!204)
  • Nullable numbers are now allowed in aggregation accumulators (!205)
  • 1 min read

0.27.0 • Update return type, Java document conversions and improved documentation

BSON

  • Improved the documentation of ObjectId and ObjectIdGenerator (#109, 1c2765f4, !198)
  • Improved the documentation of ObjectId.Serializer and Timestamp.Serializer (#108, !199)
  • Fixed documentation mistakes regarding the bounds of ObjectId (0055e7a6, !198)

BSON (official)

  • Added JvmBsonFactory.readDocument(), readArray() and readValue() to convert from official types to their KtMongo equivalents (bce89d5b)

DSL

  • Added Field<T, V>.toBsonPath() (#113, !201)

Drivers

  • Added UpdateResult and UpsertResult, the return types of updateOne, updateMany, upsertOne and their aggregation equivalents (#110, !197)

Dependencies

  • Kotlin 2.3.10
  • 1 min read

0.26.2 • KotlinX.Serialization unity

BSON (Official)

The MongoDB official driver has two main serialization modes: :bson-kotlin (based on reflection) and :bson-kotlinx (based on KotlinX.Serialization). These two systems serialize objects slightly differently.

Most notably, the newly-added types kotlin.time.Instant and kotlin.uuid.Uuid are both serialized by :bson-kotlinx as strings, but are serialized to the corresponding BSON type by :bson-kotlin. This release introduces the serializers InstantAsBsonDatetimeSerializer and UuidAsBsonBinarySerializer which use the BSON type no matter what serialization library is used, but also support JSON serialization as strings. Users have to enable them explicitly (see their documentation to learn how).

In this version, we also ensured that the KtMongo types (ObjectId and Timestamp) are serialized correctly using both serialization strategies.

  • 2 min read

0.26.0 • BSON equality and diffing, expanded BsonPath, Java driver, and improved documentation

BSON

  • Added equals and hashCode implementations for all BSON types, to allow checking if two BSON documents are identical (a073e815, !176)
  • Added BsonDocumentReader.names to iterate the field names (d26da4fb, !184)
  • Added BsonArrayReader.indices and .size to iterate over elements (ea9e5817, 3b354010, !184)
  • The official and multiplatform implementations are now tested with the same suite (bba1d7bf, !173)
  • Fixed broken documentation links in Bson and BsonArray (d265b02b)
  • Improved the documentation of BsonType (3da19f42, !185)
  • Explicitly document that BsonType.ordinal shouldn't be used (4ef5848e, !185)

BSON (official)

  • Fixed BsonValueReader.read when reading a primitive JVM type (fbdfd880)
  • Fixed BsonValueReader.toString() which did not return a JSON representation (19a34ea5)

BSON (multiplatform)

  • Fixed thread safety issue in Bson.eager() and BsonArray.eager() (#102, !179)

BsonPath

  • Renamed the parsing method from BsonPath.parse("$.a") to BsonPath("$.a") (30a09f83, #93, !165)
  • Add Bson.select("$.a") as a shorthand for Bson.select(BsonPath("$.a")) (a7b68c1a, #93, !165)
  • Add support for BsonPath.all/$.* (5e8db0f2, #93, !165)
  • Add support for BsonPath.sliced/$[1:5:2] (10f2c1c5, #93, !165)
  • Add support for BsonPath[-1]/$[-1] (01a0781f, #93, !165)
  • Add support for BsonPath.any()/$["foo", "bar"] (895c2fda, #93, !182)
  • Improve testing of BsonPath expressions

BSON diff

  • Add doc1 diff doc2 to display a human-readable difference of two BSON values, primarily intended for tests (#98, !177)

Java driver

  • Fixed publishing issue. The Java module should now be published alongside all other modules (!180)

Documentation

  • Improved the module-level documentation for all modules (#88, !181)