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()`](/features/debugging.html) (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
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
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](https://ktmongo.opensavvy.dev/features) 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
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](https://ktmongo.opensavvy.dev/tutorials/from-kmongo/setup.html) - Rewrote the [KMongo operator migration guide](https://ktmongo.opensavvy.dev/tutorials/from-kmongo/migrate.html) - Fixed incorrect example of the `sort` option (8cbe186a) ### Dependencies - Kotlin 2.4.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](https://ktmongo.opensavvy.dev/api/dsl/opensavvy.ktmongo.dsl.aggregation.operators/-conditional-value-operators/index.html#switch) has changed: the value is now defined with `then` instead of `to` - The `addToSet` overload that accepts a list has been renamed to [`addEachToSet`](https://ktmongo.opensavvy.dev/api/dsl/opensavvy.ktmongo.dsl.query/-update-query/index.html#addeachtoset) - Added `Field.unsafeCast<T>()` (7a5170bd) - Added the [`$push` update operator](https://ktmongo.opensavvy.dev/api/dsl/opensavvy.ktmongo.dsl.query/-update-query/index.html#push) 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](https://ktmongo.opensavvy.dev/api/bson/opensavvy.ktmongo.bson.types/-geo/index.html) (#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](https://ktmongo.opensavvy.dev/tutorials/index.html) page to mention the different KtMongo flavors (806fc7ed) - Added detailed pages on [KotlinX.Serialization](https://ktmongo.opensavvy.dev/tutorials/official/serialization-kotlinx.html), [Reflection](https://ktmongo.opensavvy.dev/tutorials/official/serialization-reflection.html) and [custom](https://ktmongo.opensavvy.dev/tutorials/official/serialization-custom.html) serialization strategies. - Java driver: fixed missing pages and incorrect examples (abfb3301, 6317e9ef)
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)
### MongoDB support
Due to a [tcmalloc bug](https://github.com/google/tcmalloc/issues/292), 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](https://gitlab.com/opensavvy/ktmongo/-/work_items/116) 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.
Improved documentation
### DSL - Added the `FieldDsl` constructor (d0472ba2, !214) ### Documentation - Renamed the documentation page titles (!206) - Renamed the module titles (!209)
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)
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
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
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.
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)
Technical fixes
Fixed a technical issue in the documentation website.
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
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](https://bsky.app/profile/lilywhiteout.bsky.social)) - 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
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](https://ktmongo.opensavvy.dev/tutorials/multiplatform/index.html) (0861208a) - Added a [feature page on aggregations](https://ktmongo.opensavvy.dev/features/aggregations.html) (f4bec354) - Minor improvements on the home page
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)
$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
$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)
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
ObjectId, range operators, $min and $max, read concern and Java usage
### BSON - Pure Kotlin ObjectId implementation (!72) - Added utilities for comparing ObjectId and Instant (!72) ### DSL - Added the `isIn` operator to query on ranges (!75) - Added the `$size` filter operator (659dae51, !82) - Added the `$nor` filter operator (20378994, !82) - Added the `$min` and `$max` update operators (b298039f, !82) - Added the `readConcern` option (0b9520aa, !83) ### Synchronous driver - Added a new experimental module, `:driver-sync-java`, with utilities for using KtMongo from Java (!69) - Java: Added `JavaField.of(Customer::name)` syntax (!69) - Java: Added `KtMongo.from()` helper (!69) - Java: Added `options(s -> s.)` syntax (!69) ### Dependencies - Kotlin 2.1.21 (06afc477) - MongoDB Java driver 5.5.0 (07106e25) - KotlinX.Serialization 1.8.1 (399750c2)
$mul and Field.unsafe
### DSL - Marked `Field`'s `Root` type parameter as contravariant (2424b984) - Added `Field.unsafe` to access field names using a stringly API (508d0ca9, !71) - Added the `$mul` update operator (!74)
skip, maxTimeMS, MinKey, MaxKey
### DSL - Added the `skip` option (!65) - Added the `maxTimeMS` option (!65) ### BSON - Read and write the MinKey and MaxKey special values (#64, !67)
`$regex` flexibility, simpler options, `Reader.toBson`
### DSL - Allow using `$regex` on a nullable `String` field (!59) - Rewrote the representation of options to make them simpler to evolve in the future (!61) ### BSON - Added `BsonDocumentReader.toBson` and `BsonArrayReader.toBson` (9148b99c, !61) - Added `BsonDocumentReader.asValue` and `BsonArrayReader.asValue` (19348ff2, !63) - Added `BsonValueWriter.pipe` (#41, 48267c74, !63) - Renamed `Bson.read` to `Bson.reader` (f503f49e, !61) ### BSON (Multiplatform) - Read binary data (876b6fee, !58) - Read JavaScript (21b5e928, !58) - Read `undefined` (c233d391, !62) - Implemented `BsonContext.buildArray` (#48, 37f0b868, !63) - Implemented `BsonFieldWriter.write` (627ec56e, !63) ### Documentation - Added a mention to `$in` and `$nin` in `FilterQuery` (a1e04fe8, !57) - Fixed a broken sentence in `BsonDocumentReader` (34ca574d, !57) - Added the Multiplatform BSON implementation to the API references (888b31ce, !57)
Start of the Multiplatform driver, the great rename, $nin and $regex
### Breaking changes This version contains a major rename that affects almost everything in the DSL module. To learn more about the reasons we did it, see #35 and !54. Although future versions may still have breakages, this was the last planned major change. - Renamed package `models` to `command` - Renamed package `expr` to `query` - Moved contents of package `expr.common` to `tree` - Moved contents of package `options` to `command` - Moved contents of package `options.common` to `command` - Renamed `FilterOperators` to `FilterQuery`, removed `FilterExpression` - Renamed `PredicateOperators` to `FilterQueryPredicate`, removed `PredicateExpression` - Renamed `UpdateOperators` to `UpdateQuery`, removed `UpdateExpression` - Renamed `UpsertOperators` to `UpsertQuery` - Renamed `Expression` (and its hierarchy) to `BsonNode` - Renamed `ValueDsl` to `AggregationOperators` ### BSON - Added `Bson.toByteArray()` and `BsonArray.toByteArray()` to access the raw binary BSON representation (!49) - `writeBinaryData`'s subtype parameter was changed from `Byte` to `UByte` to better mirror the BSON spec (!49) - Added `BsonType.fromCode()` to more easily access a BSON type from its binary representation (!50) - Added `Bson.read()` and `BsonArray.read()` to access contents of BSON objects (!50) - Added `BsonContext.readDocument()` and `BsonContext.readArray()` to convert from the binary BSON representation to driver objects (!50) - Documented that BSON-writeable objects much implement `toString` with a JSON representation (!54) ### BSON (Official) - Removed the dependency on NPM `bson` since it is currently unused (!49) ### BSON (Multiplatform) This new module is a pure Kotlin implementation of the BSON spec (#48, #49). - Write booleans (!49) and read them (!50) - Write int32 and int64 (!49) and read them (!50) - Write strings (!49) and read them (!50) - Write documents (!49) and read them (!50) - Write doubles (!49) and read them (!50) - Write arrays (!49) and read them (!50) - Write binary data (!49) - Write JS (!49) - Write datetime (49) - Write null (!49) and read them (!50) ### DSL - Added the filter operator `$nin` (!52) - Added the filter operator `$regex` (!56) - Added the convenience function `BsonNode.toBson()` (!54) ### Synchronous driver - Moved `UpdatePipelineOperators` into the correct package (!54) ### Deployment - The project is now tested with MongoDB versions 6.0.21, 7.0.18 and 8.0.6 (!53)
Arbitrary BSON writers and parsers
### BSON The `:bson` module's documentation on the Kotlin MongoDB driver has been removed. There are multiple breaking changes related to this refactor. For example, `buildBsonDocument` and `buildBsonArray` are now members of `BsonContext` instead of being top-level functions. - Everything but the interface definitions for arbitrary BSON writers and parsers has been removed from the `:bson` module - The BSON parser and writer based on the Kotlin MongoDB driver has been moved to the new module `:bson-official` (67567b42) - BSON tests for parsers and writers have been moved to the new module `:bson-tests` (5bef8c13) - Support most Kotlin platforms (9af59a3b) ### Annotations - Support most Kotlin platforms (9af59a3b) ### DSL - Utilities related to the official MongoDB driver have been moved to the `:driver-shared-official` internal module (404cbb38) ### Documentation - Changed the Maven metadata from linking to the repository to linking to the documentation website (8ca2a2df)
Documentation improvements
### Documentation Updated Dokka for MkDocs to version 0.5.0, bringing many improvements to the embedded API reference in the website.
Array handling aggregation operators and more
```kotlin users.aggregate() .project { include(User::name) User::bestPassingGrades set User::grades .filter { it gt of(50) } .map { it / Grade::value } .sortedDescending() .take(3) } ``` ### DSL - Added the `$filter` aggregation operator (59740316, !46) - Added the `$map` aggregation operator (5c903096, !46) - Added the `$firstN` and `$lastN` aggregation operators (721b1b07, 721b1b07, !46) - Added the `$sortArray` aggregation operator (f736c402, a607fcce, !46) - Added the `$getField` aggregation operator (28946504, !46) - Added the `$ceil` aggregation operator (7481c6ab, !42) - Added the `$floor` aggregation operator (d04f4b7f, !42) - Added the `$count` aggregation stage (f14132bd, !45) - Fixed incorrect type parameters for `$degreesToRadians` and `$radiansToDegrees` (fb01397c, !43) ### Documentation - Renamed the DSL module from 'Query DSL' to 'Request DSL' (859f3737, !42) - Added an example to `SortOptionDsl` (91c044ac, !43) ### Dependencies - KotlinX.Coroutines 1.10.1 - KotlinX.Serialization 1.8.0 - MongoDB Kotlin driver 5.3.1 - BSON JS 6.10.3
Aggregation stages $unset, $project, $sort and $unionWith, sorting in find(), $concat aggregation operator
### DSL - Add the $unset aggregation stage (4be311d4, !38) - Add the $project aggregation stage (e27a6869, !38) - Add the $sort aggregation stage (8040445f, !39) - Add the $unionWith aggregation stage (d3773e41, !39) - Add the $concat aggregation operator (892491e8, !37) - Add sorting in find()'s options (c6b2acd8, !39) - Allow using the '/' notation on nullable fields (d08211e1, !39) - Improve toString of Mongo iterables (e8372cd1, !39) - Fix documentation error in the $add aggregation operator (b6db3ff2, !37) - Fix outdated Pipeline documentation (40c30ce3, !39) - Documentation improvements around aggregation pipelines (bd23fefa, !41) - Forbid nullable documents in models, as MongoDB doesn't allow them (5efad8f1, !39) ### Kotlin BSON - Various documentation improvements and clarifications (e17b899e, !41)
$add, $abs and trigonometry operators
### DSL - Add the `$add` aggregation operator (#7, 4c8eedbe, !33) - Add the `$abs` aggregation operator (#7, 056da623, !35) - Add trigonometry aggregation operators `$cos`, `$cosh`, `$acos`, `$acosh`, `$sin`, `$sinh`, `$asin`, `$asinh`, `$tan`, `$tanh`, `$atan`, `$atanh` (#7, !35) - Move the aggregation conversion functions (`of()`) higher in the `ValueDsl` hierarchy (224c601a, !33) - Rename `ConditionalOperators` to `ConditionalValueOperators` (edf69970, !33) - Rename `SetOperators` to `SetStageOperators` (bc343596, !33) ### Documentation - Add a 'news' section to the website with changelogs (!34) - Add the BSON module in the API reference (!36)
$cond and +=
### DSL - Add the aggregation operator $cond (!32) - The update operator $inc can now be written += (!32) - Add the update operators setIf & setUnless (!32) - Add the aggregation operators setIf & setUnless (!32)
Aggregation and update pipelines
### DSL - Rewrite the Pipeline hierarchy (!31) ### Drivers - Add MongoCollection.aggregate (#38, !31) - Add MongoCollection.updateWithPipeline variants (#37, !31) ### Documentation - Split the article on field access into multiple pages (62571947, !30) - Add a documentation page on optional filters (0c6ca41a, !30) - Add a documentation page on filtered collections (bce1d0df, !30)
$expr and the first aggregation stages
### Kotlin BSON - Fixed bug where arrays were generated incorrectly (9d0cbea3, !20) ### MongoDB DSL - Create the aggregation Value (bec086c1) - Create the $expr filter operator (22b9d97e) - Add the $match aggregation stage (44ea7bf3) - Add the $sample aggregation stage (fc34f2b5) - Add the $skip aggregation stage (3239a479) - Add the $limit aggregation stage (4cc84722) - Add the $set aggregation stage (81b7f8b4) - Implement the $literal aggregation operator (49e1d564) - Implement the $eq, $ne, $gt, $lt, $gte, $lte aggregation operators (22b9d97e)
Map of strings and documentation improvements
### DSL - Add isMapEmpty & isMapNotEmpty (#33, 75c62ebb, !28) - Add the get() operator for Map<String, V> (#33, 70473b4d, !28) ### Documentation - Add link to the documentation website in the main README (!27) - Shorten the main README (!27)
Embedded documentation
### Documentation - The reference is now embedded directly into the documentation website (experimental, 8d613304, !25) ### Dependencies - Kotlin 2.1.0
Collection.isEmpty, .$., .$[]., improved documentation website
### DSL - Added the filter operator Collection.isEmpty (#21, !21) - Added the filter operator Collection.isNotEmpty (#21, !21) - Added the positional operator: .$. (!22) - Added the all positional operator: .$[]. (!22) ### Website - Added a documentation page for CRUD operations (!22) - Added a documentation page for bulkWrite (!22) - Added a documentation page for nested fields access, including arrays (!22)
Insert, delete, drop, and a configuration tutorial
### Drivers - Add insertOne, insertMany (!16) - Add deleteOne, deleteMany (!14) - Add drop (!14) ### Query DSL - Add InsertOneOptions, DeleteOneOptions (!16) - Add DeleteOptions (!14) - Add DropOptions (!14) - Rename any to anyValue, and anyObject to any (#11, !16) - Add a documentation header for AbstractCompoundExpression (#12, !16) - Add a link to tracking issues in operators' documentation (#13, !16) ### Documentation - Initialize the website (!15) - Add a tutorial for setting up everything (!15) - Add a contribution guide for integration tests (!16) - Add pages introducing how to find and update data (!18) - Add an explanation of the benefits of KtMongo over KMongo (!18) - Add a comparison between KtMongo and KMongo (!18) - Simplify the design of the home page (!17)
count(), update(), bulkWrite(), abstract tree management and options
### Drivers - Added count() - Added countEstimated() - Added updateOne(), updateMany(), upsertOne() - Added findOneAndUpdate() - Added filtered collections - Added an 'options' lambda to all operations - Added CountOptions.limit() - Improved MongoCollection.toString() - Added bulkWrite() ### DSL - The BsonContext is now available in all expressions - Abstract over tree management with the new '.tree' package - Reorganize all operations from XXXExpressions to XXXOperators interfaces (to allow delegation) - Add Expression.toBsonDocument ### BSON - Added buildBsonArray ### Deployment - Added an integration test to ensure the driver is compatible with 3 stable MongoDB versions
find(), basic filter and update operators
### Drivers - Create MongoCollection and MongoIterable (!8) - Implement find, findOne (!8) ### DSL - Create Expression (!2) - Create Path and Field to refer to MongoDB fields using Kotlin variables (!3) - Implement basic filter operators (!3) - $and, $or, $not - $eq, $ne, $in - $exists, $type - $gt, $gte, $lt, $lte - $elemMatch, $all - *notNull variants - Implement basic update operators (!7) - $set, $setOnInsert, $unset - $inc - $rename ### BSON - Mark all functions as @LowLevelApi (!2) ### Dependencies - Kotlin 2.0.20 (!5)