OpenSavvy KtMongo

0.31.0 • Array update operators, GeoJSON operators, KMongo migration documentation and Multiplatform insertOne

Sun, 21 Jun 2026 00:00:00 +0000

0.31.0 • Array update operators, GeoJSON operators, KMongo migration documentation and Multiplatform insertOne

BSON

Allow re-encoding a Bson value to another implementation (832b763e)
Added Geo.CoordinateReferenceSystem (a79a3e56)
Added Geo.writeTo(BsonFieldWriter) for easy serialization (0c63ce67)

DSL

Update operators:

Added arrayFilters support (#3, !242)
Added $pop support (8366d4a0, !246)
Added $pull support (fe025cca, !246)
Added $bit support (!252)

Filter operators:

Added $near (f2e71695, !248)
Added $nearSphere (857941aa, !248)
Added $geoWithin (4904317e, !248)
Added $geoIntersects (bfcd4318, !248)
Added $mod (6e0b89a2, !250)

Everything else:

Merge different calls to the sort option (5b3e4412)

Drivers

KMongo compat: Allow overriding the PropertyNameStrategy in asKtMongo() (dd15b39e)

Multiplatform

Ability to connect to the database! (!172)
Added insertOne support (!172)

Documentation

Added the KMongo setup guide
Rewrote the KMongo operator migration guide
Fixed incorrect example of the sort option (8cbe186a)

Dependencies

Kotlin 2.4.0

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

Sun, 17 May 2026 00:00:00 +0000

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: kotlin Target::score set (of(2) * of(Target::score) * of(3))

After: kotlin 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:

The syntax of the switch conditional aggregation operator has changed: the value is now defined with then instead of to
The addToSet overload that accepts a list has been renamed to addEachToSet
Added Field.unsafeCast<T>() (7a5170bd)
Added the $push update operator with its different options (!236)

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

The tutorial pages now link directly to the API reference (624fb8c4)
Reworked the Getting Started page to mention the different KtMongo flavors (806fc7ed)
Added detailed pages on KotlinX.Serialization, Reflection and custom serialization strategies.
Java driver: fixed missing pages and incorrect examples (abfb3301, 6317e9ef)

0.29.1 • Documentation improvements

Tue, 14 Apr 2026 00:00:00 +0000

0.29.1 • Documentation improvements

DSL

The FieldDsl constructor only needs a PropertyNameStrategy, not a full BsonContext (43f4c7ca)

Documentation

Fixed documentation implying that the indexing operator is written .$0. instead of .0. (dccf5246)
Fixed links, improved phrasing (5c83aea8, 67399f3e)

Deployment

Removed Intel-based Apple targets, as they are deprecated by Apple (!224)

0.29.0 • ### MongoDB support

Tue, 24 Mar 2026 00:00:00 +0000

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.

0.28.1 • Improved documentation

Sat, 21 Mar 2026 00:00:00 +0000

0.28.1 • Improved documentation

DSL

Added the FieldDsl constructor (d0472ba2, !214)

Documentation

Renamed the documentation page titles (!206)
Renamed the module titles (!209)

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

Wed, 11 Mar 2026 00:00:00 +0000

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)

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

Tue, 03 Mar 2026 00:00:00 +0000

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

0.26.3 • Fixes for the official drivers' codecs

Sat, 28 Feb 2026 00:00:00 +0000

0.26.3 • Fixes for the official drivers' codecs

BSON

The kotlin.time.Instant has been stabilized in Kotlin 2.3.0. The @ExperimentalTime annotation has thus been removed from all methods that use it internally (!196)

Drivers (official)

Fixed the drivers not using the configured KtMongo codecs in their methods (!195)

Dependencies

Kotlin 2.3.0

0.26.2 • KotlinX.Serialization unity

Mon, 16 Feb 2026 00:00:00 +0000

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.

0.26.1 • Fix MavenCentral publication

Wed, 04 Feb 2026 00:00:00 +0000

0.26.1 • Fix MavenCentral publication

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

Fri, 30 Jan 2026 00:00:00 +0000

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)

0.25.1 • Technical fixes

Fri, 02 Jan 2026 00:00:00 +0000

0.25.1 • Technical fixes

Fixed a technical issue in the documentation website.

0.25.0 • BsonContext/BsonFactory split, serialization annotation support, experimental BsonPath and eager multiplatform BSON

Sun, 21 Dec 2025 00:00:00 +0000

0.25.0 • BsonContext/BsonFactory split, serialization annotation support, experimental BsonPath and eager multiplatform BSON

BsonContext and BsonFactory

Breaking change

Impacted modules: :bson, :dsl

See: #95, !157

Since the start of the project, the configuration of BSON documents is stored by the BsonContext interface. However, it was starting to become too big. Initially, BsonContext was used for BSON object creation. In 0.19.0, it obtained the capability of creating ObjectId instances. In this version, it would also have obtained the configuration for serializing paths.

In this release, it is changed as follows:

The BsonContext is removed from :bson.
The new BsonFactory interface becomes responsible from creating BSON documents.
The capability of creating new ObjectId instances remains in ObjectIdGenerator.
A new BsonContext interface is created in :dsl, which aggregates the capabilities required by the DSL.

If you created custom operators, you will need to switch the imports from the old BsonContext to the new one.

Otherwise, end-users should not be impacted.

PropertyNameStrategy

Impacted modules: :dsl, :driver-sync-kmongo, :driver-coroutines-kmongo

See: #89, !151, !157

The new interface PropertyNameStrategy was added to configure how the Foo::user / User::name syntax is converted into MongoDB paths. Users can override the default implementation when initializing the KtMongo library. For example, this can be used to look up annotations on the fields to change their name.

When using one of the KMongo compatibility modules, the strategy used understands @BsonId and KotlinX.Serialization's @SerialName, as recommended by the KMongo documentation for the KotlinX.Serialization library.

If you use Jackson or want to use KotlinX.Serialization annotations with the regular driver modules (without using the KMongo compatibility modules) you can override the PropertyNameStrategy used by the driver.

We do not plan to add support for serialization annotations in the default implementation.

As a consequence, some methods have been moved from Field to FieldDsl.

BsonPath

Experimental

Impacted modules: :bson

See: #2, #93, #146

Added the experimental BsonPath interface to represent JSONPath-like accessors to BSON documents.

BsonPath is a great alternative to deserialization when we are only interested in a few fields, as it avoids the need for creating complex DTOs, especially when they are deeply nested.

```kotlin val path = BsonPath.parse("$.users.1.name")

val name: String = myDocument at path ```

BSON

Removed @ExperimentalStdlibApi on the ObjectId constructor as it has been stabilized in the standard library (b9ccf073)
ObjectId.Serializer has been changed from a class to an object (88f6947e)
Timestamp.Serializer has been changed from a class to an object (88f6947e)

BSON (multiplatform)

Instances of .reader() are now reused. This will make access to fields faster (60397c9d)
Added Bson.eager() and BsonArray.eager() to eagerly initialize the readers, which makes them thread-safe. Improved the documentation on thread-safety (!167)
Improved the documentation of Bson and BsonArray (!167)

Dependencies

Kotlin 2.2.21

0.24.0 • Mokodee, unset shorthand and easier KMongo migration

Wed, 22 Oct 2025 00:00:00 +0000

0.24.0 • Mokodee, unset shorthand and easier KMongo migration

DSL

Added the unset shorthand for updates (1b49046f, !135)

Documentation

Added Mokodee, the KtMongo mascot! (c488893f, thanks to Lilywhiteout)
Added a set up guide to the KMongo migration guide (e663d70f)
Reorganized and updated the Multiplatform roadmap (67f6816d, 716ce781)
Formatting improvements in the aggregation page (20d455fa, 35c79cf4)

Dependencies

Prepared 2.1.1

0.23.0 • Multiplatform KotlinX.Serialization, Field.unsafe expansion, replace and KMongo utilities

Tue, 30 Sep 2025 00:00:00 +0000

0.23.0 • Multiplatform KotlinX.Serialization, Field.unsafe expansion, replace and KMongo utilities

BSON (Multiplatform)

Multiplatform KotlinX.Serialization support (#50, !117, thanks @UnknownJoe796)

DSL

Added Field.unsafe() overloads to allow more use-cases (!132)
$concat now allows nullability, and has been moved from ArithmeticValueOperators to StringValueOperators (!134)

Drivers

Added replaceOne() and repsertOne() (!133)
Added :driver-sync-kmongo and :driver-coroutines-kmongo with a utility function to convert KMongo objects to KtMongo objects (!132)

Documentation

Introduced the Kotlin Multiplatform roadmap (0861208a)
Added a feature page on aggregations (f4bec354)
Minor improvements on the home page

0.22.0 • WASI, averages and aggregation deserialization fixes

Thu, 18 Sep 2025 00:00:00 +0000

0.22.0 • WASI, averages and aggregation deserialization fixes

BSON

Added Wasm WASI support (!126)

DSL

Added the $avg accumulator (679ebb2c, !127)
Added the $avg aggregator (ebdc71de, !127)

Drivers

Fixed AggregationPipeline.reinterpret which attempted to deserialize the wrong type (#91, !129)

0.21.0 • $group and string aggregation operators

Sun, 24 Aug 2025 00:00:00 +0000

0.21.0 • $group and string aggregation operators

DSL

Projections are now represented with booleans instead of integers, for smaller request payloads (#81, !121)

Aggregation stages:

Added $group (!120)

Accumulation operators:

Added $sum (!120)

Aggregation operators:

Added $multiply, $divide and $subtract (!122)
Added $trim, $ltrim and $rtrim (!123)
Added $toLower and $toUpper (!123)
Added $substrCP, $substrBytes, $strLenCP and $strLenBytes (!123)
Added $split (!123)
Added $replaceOne and $replaceAll (!123)

Dependencies

KotlinX.Serialization 1.9.0
KotlinX.Coroutines 1.10.2
KotlinX.IO 0.8.0
MongoDB Java driver 5.5.1

0.20.0 • $addToSet, $currentDate and the new documentation website

Sat, 09 Aug 2025 00:00:00 +0000

0.20.0 • $addToSet, $currentDate and the new documentation website

BSON

Added support for reading and writing ObjectId (!110)

DSL

Added support for the update operator $addToSet (!107)
Added support for the update operator $currentDate (!108)

Documentation

Moved the website to https://ktmongo.opensavvy.dev (!112, !113)

0.20.1 • Fixed documentation website deployment

Sat, 09 Aug 2025 00:00:00 +0000

0.20.1 • Fixed documentation website deployment

0.19.0 • Pure Kotlin ObjectId and Timestamp, $switch, type aggregation operators, bitwise filter operators, writeConcern and readPreference

Tue, 29 Jul 2025 00:00:00 +0000

0.19.0 • Pure Kotlin ObjectId and Timestamp, $switch, type aggregation operators, bitwise filter operators, writeConcern and readPreference

BSON

Moved ObjectId to opensavvy.ktmongo.bson.types (6e455683, !80)
Added ObjectIdGenerator with multiple implementations (!80)
Added ObjectId.MIN and ObjectId.MAX (!80)
Added BsonContext.newId (!80)
Added BsonReader.readInstant and BsonWriter.writeInstant (244237ed, !88)
Added opensavvy.ktmongo.bson.types.Timestamp (!89)
Changed timestamp APIs from Long to the new Timestamp type (!89)

BSON (official)

Deleted the old expect class opensavvy.ktmongo.bson.official.types.ObjectId (!80)
Added a codec for the new ObjectId (!80)

BSON (multiplatform)

Decreased data copying when reading data (417128b5, !84)
Removed autoboxing in the implementation of the reader (17cab93a, !84)
Added no-copy piping of BSON from a reader to a writer (!86)
Added support for reading and writing BsonType.DateTime as kotlin.time.Instant (e15001f4, !88)
Added support for reading and writing BsonType.RegExp (2bb5e544, !88)
Added support for reading and writing BsonType.Timestamp (aa3c9a9e, !89)

Official driver

JvmMongoCollection.find now returns a JvmMongoIterable instead of a MongoIterable (!85)

DSL

Added the aggregation operator $switch (!90)
Added the aggregation operators $type, $isArray, $isNumber, $toBoolean, $toDate, $toDouble, $toInt, $toLong, $toObjectId, $toString and $toUUID (!91)
Added the filter operators $bitAllClear, $bitsAllSet, $bitsAnyClear and $bitsAnySet (!92)
Added the option writeConcern (!93)
Added the option readPreference (!94)
Created the Command interface and reorganized all commands to emit their BSON representation (!95)

Documentation

Added a section on aggregation support to the KMongo migration page (#87, !103)

Dependencies

Kotlin 2.2.0