Skip to content

News

  • 2 min read

0.33.0 • Multiplatform is Experimental, $unwind, exclusions in $set and $project, capped collections and aggregation debug mode

BSON (Official)

  • Display the BSON document being decoded when no Codec is found (01955256)

Drivers

  • Added missing aggregation specializations (!292)
  • Added MongoAggregationPipeline.debug() (2efea338, 67d552a9)
  • insert now supports the options maxTime (Multiplatform-only), ordered, bypassDocumentValidation and comment (!295)
  • insert now throws rich exceptions (!301, !304)
  • Added support for creating capped collections (!297)
  • Added support for document validation (!298)
  • Simplified untyped access through BsonDocument (!303)

Driver (Multiplatform)

  • Improved the shutdown sequence (!280)
  • Improved connection failures (857f4d62)
  • Implemented Unified API (!299, !300)

DSL

Aggregations: - Added $unwind (2d61c846) - Added $arrayElemAt (18a1c37d) - Field accesses now generate $getField and $arrayElemAt automatically (b98244cf) - Removed the fake array in the string representation of Value (47114cbb) - Added Value.unsafeCast() (cfca285d)     - Added Value.unsafeNonNull() (517f2ce7) - Renamed Pipeline.reinterpret to Pipeline.unsafeCast (102d3e65) - The $set stage now has an overload to set array elements (ea46d924) - The $set and $group stages are now stricter about type safety (1013f81a, 7944e685) - The $set and $project stages now support field exclusion via $$REMOVE (9661baec) - Projections ($project and $set) automatically cast the pipeline if the type changes (19e9fb64) - Created trigonometry & string operator overloads for non-nullable values (4df776a7, 70ad9074) - Removed some ambiguous / overloads (02fca9c3) - The $divide operator now requires explicit div spelling instead of just / (223ad3c8)

Options: - Specify the behavior of $maxTimeMS with submillisecond timeouts (e9fd9402) - The option holder classes have been renamed from WithOption to HasOption (db8f2589) - Added a convenience overload for writeConcern (b93c2766)

Documentation

  • Documented missing aggregation stages (51bed497)
  • Decreased the visibility of the 'news' section in the site search
  • Various corrections (2a89f430)
  • Documented how to create a custom option (78073d1d)

Dependencies

  • MongoDB Java driver 5.10.0
  • 1 min read

0.32.1 • Improved documentation, group by

BSON

  • Added BsonFieldWriter.write(String, BsonValueWriteable) (f7e6b07a)

DSL

  • Added $group's _id parameter (38bac2f8)
  • Path is now Comparable (3ecec1e3)
  • Added missing Node supertype of CompoundNode (5c9bb1f7)
  • Cleaned up the @DslMarker annotation (!282)
  • Fixed possible thread unsafety in Node.freeze() (#101, ca4f0011)

Multiplatform

  • Improved testing of the wire protocol (!279)

Documentation

  • Fixed broken links (!278)
  • Improved documentation of the dsl.tree package (!285)
  • Clarified the difference between isIn and isOneOf (#131, !283)

Deployment

  • This version has been tested against MongoDB 7.0.40
  • 2 min read

0.32.0 • The Unified API, $lookup and date-time aggregation operators

The Unified API

Since the start of the project, KtMongo only contained collection types (MongoCollection) and no database or client types. With this version, we're introducing MongoClient and MongoDatabase.

Along with this change, the two KtMongo drivers are tested under the same integration test suite, both with KotlinX.Serialization and with reflection. This will ensure we can catch differences earlier.

Breaking changes: with the occasion of the Unified API, some types have been renamed:

  • opensavvy.ktmongo.coroutines.JvmMongoCollection → opensavvy.ktmongo.coroutines.CoroutineMongoCollection
  • opensavvy.ktmongo.sync.JvmMongoCollection → opensavvy.ktmongo.sync.SyncMongoCollection
  • Similar renaming for JvmMongoIterable

Soon, the Multiplatform driver will join both official drivers to follow the same API.

  • Created the new :driver-api module with common documentation (#129, !259, !260, !262, !263, !276)
  • :driver-coroutines now follows the Unified API (!259, !260, !263)
  • :driver-sync now follows the Unified API (!277)

Drivers

  • Fixed MongoCollection.asOfficial() which returned a collection not aware of Kotlin types (4a75b28c)
  • Fixed deleteMany which only deleted one document (07d82316)

DSL

  • Improved compilation errors when the types are incorrect for update operations (!269, with help from the Kotlin team!)
  • Added the matchExpr aggregation stage as syntax sugar for $match { $expr: { … } } (3a704e4c)
  • Added direct array item access in projections (c29fc188)
  • Added the $lookup aggregation stage with all its options (!271)
  • Added the datetime aggregation operators: $year, $week, $second, $month, $minute, $millisecond, $isoWeek, $isoWeekYear, $isoDayOfWeek, $hour, $dayOfMonth, $dayOfWeek and $dayOfYear (!274)

Multiplatform

  • Improvements to the closing of the client (!261, !272)
  • Precise timing logs (5fa463d0)

Documentation

  • Added the Quick navigation page which makes it easier to find specific operators (!275)
  • The modules :driver-multiplatform and :driver-multiplatform-wire are now included in the Reference (!258)

Dependencies

  • Kotlin 2.4.10
  • KotlinX.Coroutines 1.11.0
  • KotlinX.Serialization 1.11.0
  • KotlinX.IO 0.9.1
  • Ktor 3.5.1
  • Slf4j 2.0.18
  • MongoDB JVM Driver 5.9.1
  • KMongo 5.6.0
  • 1 min read

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:

Filter operators:

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

Dependencies

  • Kotlin 2.4.0
  • 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