From 624fb8c4a1acba4ea4c82d4df50d96798c95e0f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Thu, 30 Apr 2026 00:21:29 +0200 Subject: [PATCH 1/7] docs(website): Link to the reference in feature pages --- docs/website/docs/features/aggregations.md | 2 +- docs/website/docs/features/bulk-writes.md | 10 ++++-- docs/website/docs/features/crud.md | 35 ++++++++++++------- .../docs/features/filtered-collections.md | 6 ++-- .../website/docs/features/optional-filters.md | 4 +++ 5 files changed, 38 insertions(+), 19 deletions(-) diff --git a/docs/website/docs/features/aggregations.md b/docs/website/docs/features/aggregations.md index ff19589f..fe09e7ef 100644 --- a/docs/website/docs/features/aggregations.md +++ b/docs/website/docs/features/aggregations.md @@ -17,7 +17,7 @@ users.aggregate() Within each stage, you may combine values together. !!! note "" - Unlike other stages, `match` uses regular find syntax and not aggregation operators. Use the [`expr` operator](../api/dsl/opensavvy.ktmongo.dsl.query/-filter-query/index.md#expr) within `match` to access aggregation operators. + Unlike other stages, [`match`](../api/dsl/opensavvy.ktmongo.dsl.aggregation.stages/-has-match/index.md#match) uses regular find syntax and not aggregation operators. Use the [`expr` operator](../api/dsl/opensavvy.ktmongo.dsl.query/-filter-query/index.md#expr) within `match` to access aggregation operators. ## Aggregation operators diff --git a/docs/website/docs/features/bulk-writes.md b/docs/website/docs/features/bulk-writes.md index b5ad5e75..46d559d5 100644 --- a/docs/website/docs/features/bulk-writes.md +++ b/docs/website/docs/features/bulk-writes.md @@ -18,7 +18,7 @@ for (user in usersToCreate) { This code is bad because each insert will send data to the database and wait for its response. Between each insert, it waits for the previous one to finish and for an entire network roundtrip. -Instead, we can insert all users at once with `insertMany`: +Instead, we can insert all users at once with [`insertMany`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-insert-operations/index.md#insertmany): ```kotlin val usersToCreate = listOf( @@ -32,9 +32,9 @@ users.insertMany(usersToCreate) Here, a single request is sent to the database, which can perform all inserts much quicker. -Similarly, other write operations have a variant that allows performing the same write on multiple documents: `updateMany` and `deleteMany`. +Similarly, other write operations have a variant that allows performing the same write on multiple documents: [`updateMany`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-update-operations/index.md#updatemany) and [`deleteMany`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-delete-operations/index.md#deletemany). -Sometimes, however, we want to perform very different writes, but we could still benefit from sending them all in a single request. In those situations, we can use `bulkWrite`: +Sometimes, however, we want to perform very different writes, but we could still benefit from sending them all in a single request. In those situations, we can use [`bulkWrite`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-update-operations/index.md#bulkwrite): ```kotlin users.bulkWrite { @@ -57,3 +57,7 @@ users.bulkWrite { ``` Note that this _isn't_ a transaction. The operations are performed in the same way they would be if calling their respective methods, the only difference is they are all sent together to the database in a single request to decrease network traffic and latency. + +Learn more: + +- [Bulk write commands](../api/dsl/opensavvy.ktmongo.dsl.command/-bulk-write/index.md) diff --git a/docs/website/docs/features/crud.md b/docs/website/docs/features/crud.md index a1789fd8..1449cabb 100644 --- a/docs/website/docs/features/crud.md +++ b/docs/website/docs/features/crud.md @@ -43,7 +43,7 @@ In the rest of this article, we assume you have [obtained a collection](../tutor ## Create -Creating a new document is done directly with an instance of the class and the method `insertOne`: +Creating a new document is done directly with an instance of the class and the method [`insertOne`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-insert-operations/index.md#insertone): ```kotlin users.insertOne(User(ObjectId(), "Bob")) @@ -51,7 +51,7 @@ users.insertOne(User(ObjectId(), "Bob")) If the collection didn't yet exist, any write operation creates it. -If we want to insert multiple documents at the same time, we can use `insertMany`: +If we want to insert multiple documents at the same time, we can use [`insertMany`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-insert-operations/index.md#insertmany): ```kotlin users.insertMany( @@ -64,19 +64,19 @@ users.insertMany( ## Read Read operations retrieve documents from a collection. -For example, we can `count` how many documents exist in a collection: +For example, we can [`count`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-count-operations/index.md#count) how many documents exist in a collection: ```kotlin users.count() ``` -Or, we can get all the documents using the `find` method: +Or, we can get all the documents using the [`find`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-find-operations/index.md#find) method: ```kotlin users.find().toList() ``` -However, lists are in-memory data structures, and it may not be appropriate to query an entire collection into memory. Instead, we can stream the results using `forEach`: +However, lists are in-memory data structures, and it may not be appropriate to query an entire collection into memory. Instead, we can stream the results using [`forEach`](../api/driver-coroutines/opensavvy.ktmongo.coroutines/-mongo-iterable/index.md#foreach): ```kotlin users.find().forEach { println("Found a document: $it") } @@ -110,7 +110,7 @@ This syntax is typesafe: invalid requests (for example comparing against another [//]: # (TODO: add a link to the 'collation' option, whenever it is implemented) -If you are only interested in a single document, use `findOne`, which returns a nullable value instead of a list: +If you are only interested in a single document, use [`findOne`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-find-operations/index.md#findone), which returns a nullable value instead of a list: ```kotlin users.findOne { @@ -121,12 +121,13 @@ users.findOne { Learn more: - [Referring to fields](fields.md) +- [Filter operators](../api/dsl/opensavvy.ktmongo.dsl.query/-filter-query/index.md) ## Update Update operations modify existing documents in a collection. -Similarly to search criteria, we can use infix operators to update some fields. To update all documents, use `updateMany`: +Similarly to search criteria, we can use infix operators to update some fields. To update all documents, use [`updateMany`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-update-operations/index.md#updatemany): ```kotlin users.updateMany { @@ -146,15 +147,21 @@ users.updateMany( } ``` -If you only want to update a single document, use `updateOne` instead, which has the same syntax. +If you only want to update a single document, use [`updateOne`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-update-operations/index.md#updateone) instead, which has the same syntax. -Finally, if you want to ensure that a specific document exists, and want to create it if it doesn't, use `upsertOne`. +Finally, if you want to ensure that a specific document exists, and want to create it if it doesn't, use [`upsertOne`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-update-operations/index.md#upsertone). + +Learn more: + +- [Filter operators](../api/dsl/opensavvy.ktmongo.dsl.query/-filter-query/index.md) +- [Update operators](../api/dsl/opensavvy.ktmongo.dsl.query/-update-query/index.md) +- [Upsert operators](../api/dsl/opensavvy.ktmongo.dsl.query/-upsert-query/index.md) ## Delete Delete operations remove documents from a collection. Delete operations accept a filter, just like `findOne` and `findMany`. -To delete one document, use `deleteOne`: +To delete one document, use [`deleteOne`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-delete-operations/index.md#deleteone): ```kotlin users.deleteOne { @@ -162,7 +169,7 @@ users.deleteOne { } ``` -To delete multiple documents, use `deleteMany`: +To delete multiple documents, use [`deleteMany`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-delete-operations/index.md#deletemany): ```kotlin users.deleteMany { @@ -170,8 +177,12 @@ users.deleteMany { } ``` -Additionally, to delete the entire collection, use `drop`: +Additionally, to delete the entire collection, use [`drop`](../api/driver-coroutines/opensavvy.ktmongo.coroutines.operations/-collection-operations/index.md#drop): ```kotlin users.drop() ``` + +Learn more: + +- [Filter operators](../api/dsl/opensavvy.ktmongo.dsl.query/-filter-query/index.md) diff --git a/docs/website/docs/features/filtered-collections.md b/docs/website/docs/features/filtered-collections.md index 38da965b..037fd4dd 100644 --- a/docs/website/docs/features/filtered-collections.md +++ b/docs/website/docs/features/filtered-collections.md @@ -17,7 +17,7 @@ We can use [delete operations](crud.md#delete) to remove documents from a collec In all these situations, we want to hide documents and ensure no requests can impact them. The traditional approach is to have a shared BSON filter and remember to apply it to all operations. Using this approach, it is very easy to forget one request, creating hard to trace bugs. To alleviate this, KtMongo introduces filtered collections. As an example, let's imagine a list of invoices. Users can trash invoices, but we cannot actually delete them because they may need to be inspected later. -We use the `filter` method to create a filtered collection containing only "live" invoices: +We use the [`filter`](../api/driver-coroutines/opensavvy.ktmongo.coroutines/-mongo-collection/index.md#filter) method to create a filtered collection containing only "live" invoices: ```kotlin val allInvoices = database.getCollection("invoices").asKtMongo() val liveInvoices = allInvoices.filter { Invoice::isLive ne false } @@ -38,11 +38,11 @@ trashedInvoices.deleteMany { ``` !!! note "Implementation" - `.filter {}` is implemented by combining the filter criteria with the command's own criteria using an `$and` operator. + [`.filter {}`](../api/driver-coroutines/opensavvy.ktmongo.coroutines/-mongo-collection/index.md#filter) is implemented by combining the filter criteria with the command's own criteria using an [`$and`](../api/dsl/opensavvy.ktmongo.dsl.query/-filter-query/index.md#and) operator. ## Bulk writes -When writing a complex [bulk write](bulk-writes.md), we can use the `filtered` method to apply a filter to some operations in the bulk write but not others: +When writing a complex [bulk write](bulk-writes.md), we can use the [`filtered`](../api/dsl/opensavvy.ktmongo.dsl.command/-bulk-write/index.md#filtered) method to apply a filter to some operations in the bulk write but not others: ```kotlin liveInvoices.bulkWrite { insertOne(Invoice(/* … */)) diff --git a/docs/website/docs/features/optional-filters.md b/docs/website/docs/features/optional-filters.md index 6806734d..fc3f6ea0 100644 --- a/docs/website/docs/features/optional-filters.md +++ b/docs/website/docs/features/optional-filters.md @@ -66,3 +66,7 @@ songs.find { Song::releaseDate ltNotNull criteria.releasedBefore } ``` + +Learn more: + +- [Filter operators](../api/dsl/opensavvy.ktmongo.dsl.query/-filter-query/index.md) (optional filter operators are suffixed with `NotNull`) -- 2.51.2 From abfb3301d487c7744cdc4159205e82741b251f54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Sat, 2 May 2026 14:51:07 +0200 Subject: [PATCH 2/7] docs(driver-sync-java): Fix the module-level page not appearing --- driver-sync-java/README.md | 2 +- driver-sync-java/build.gradle.kts | 6 ++++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/driver-sync-java/README.md b/driver-sync-java/README.md index b847e484..321f6cd6 100644 --- a/driver-sync-java/README.md +++ b/driver-sync-java/README.md @@ -1,4 +1,4 @@ -# Module MongoDB driver for Kotlin (synchronous, with Java helpers) +# Module KtMongo: MongoDB driver for Kotlin & Java • Synchronous Blocking/synchronous driver for MongoDB Java users. diff --git a/driver-sync-java/build.gradle.kts b/driver-sync-java/build.gradle.kts index df62e139..b235a5a8 100644 --- a/driver-sync-java/build.gradle.kts +++ b/driver-sync-java/build.gradle.kts @@ -62,3 +62,9 @@ publishing { } } } + +dokka { + dokkaSourceSets.configureEach { + includes.from("README.md") + } +} -- 2.51.2 From 6317e9ef3404ac25f062b021fc97aedf072053fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Sat, 2 May 2026 14:51:36 +0200 Subject: [PATCH 3/7] docs(driver-sync-java): Fix code example --- driver-sync-java/README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/driver-sync-java/README.md b/driver-sync-java/README.md index 321f6cd6..a018c5d3 100644 --- a/driver-sync-java/README.md +++ b/driver-sync-java/README.md @@ -47,11 +47,9 @@ Use the method [`KtMongo.from`][opensavvy.ktmongo.sync.KtMongo.from] to convert Because Java doesn't provide optional parameters, and because Java and Kotlin lambdas are slightly different, we offer convenience methods. ```java -collection.find(options(),filter(filter ->{ - filter. - -eq(JavaField.of(Profile::name), "Fred"); - })); +collection.find(options(), filter(filter -> { + filter.eq(JavaField.of(Profile::name), "Fred"); +})); ``` You can find more complex examples in the [test directory](https://gitlab.com/opensavvy/ktmongo/-/tree/main/driver-sync-java/src/test/java/opensavvy/ktmongo/sync?ref_type=heads). -- 2.51.2 From 32cc567b2fc248310b073923e4584f22f79e8cff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Sat, 2 May 2026 14:57:21 +0200 Subject: [PATCH 4/7] docs(bson-tests): Removed the :bson-tests module from the KtMongo website The documentation will still be available on javadocs.io. We remove it because it pollutes search results in the website. --- docs/website/build.gradle.kts | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/website/build.gradle.kts b/docs/website/build.gradle.kts index 0f9623d0..6cfab438 100644 --- a/docs/website/build.gradle.kts +++ b/docs/website/build.gradle.kts @@ -25,7 +25,6 @@ dependencies { dokka(projects.bson) dokka(projects.bsonOfficial) dokka(projects.bsonMultiplatform) - dokka(projects.bsonTests) dokka(projects.dsl) dokka(projects.driverSharedOfficial) dokka(projects.driverSharedKmongo) -- 2.51.2 From 39a3822598b53fc2d3a36a3e34ed0ece19d055e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Sat, 2 May 2026 15:07:22 +0200 Subject: [PATCH 5/7] docs(bson-official): Added package-level pages --- bson-official/README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/bson-official/README.md b/bson-official/README.md index 1b23ce68..202b65ad 100644 --- a/bson-official/README.md +++ b/bson-official/README.md @@ -8,4 +8,12 @@ Kotlin-first BSON library, based on the official MongoDB implementations. BSON API for Kotlin, implemented on top of the [official `org.mongodb:bson` library](https://javadoc.io/doc/org.mongodb/bson/latest/index.html). -The method [`JvmBsonFactory`][opensavvy.ktmongo.bson.official.JvmBsonFactory] is the entry point to all types in the module. It allows creating a new BSON factory using the same configuration as the official library (via the `CodecRegistry`). +The class [`BsonFactory`][opensavvy.ktmongo.bson.official.BsonFactory] is the entry point to all types in the module. It allows creating a new BSON factory using the same configuration as the official library (via the `CodecRegistry`). + +# Package opensavvy.ktmongo.bson.official + +The BSON factory, documents and arrays. + +# Package opensavvy.ktmongo.bson.official.types + +Utilities for working with KtMongo's BSON types and utilities to convert them to the official implementations. -- 2.51.2 From ba65a8285958c8019eca20793c509323519d7f3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Sat, 2 May 2026 15:15:49 +0200 Subject: [PATCH 6/7] docs(bson-official): Link to the interface --- bson-official/src/commonMain/kotlin/Bson.kt | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/bson-official/src/commonMain/kotlin/Bson.kt b/bson-official/src/commonMain/kotlin/Bson.kt index 7674a8fe..87b841aa 100644 --- a/bson-official/src/commonMain/kotlin/Bson.kt +++ b/bson-official/src/commonMain/kotlin/Bson.kt @@ -28,6 +28,9 @@ import kotlin.reflect.typeOf * * To create instances of this class, see [BsonFactory]. * + * > This page describes the BSON implementation based on the official MongoDB drivers. + * > To learn more about the general BSON operations, see [opensavvy.ktmongo.bson.BsonDocument]. + * * ### Navigating BSON types * * This interface is part of the BSON trinity: @@ -76,6 +79,9 @@ expect class BsonDocument : BsonDocument { * * To create instances of this class, see [BsonFactory]. * + * > This page describes the BSON implementation based on the official MongoDB drivers. + * > To learn more about the general BSON operations, see [opensavvy.ktmongo.bson.BsonArray]. + * * ### Navigating BSON types * * This interface is part of the BSON trinity: @@ -120,6 +126,9 @@ expect class BsonArray : BsonArray { * * To instantiate a [BsonDocument] or [BsonArray], see [BsonFactory]. * + * > This page describes the BSON implementation based on the official MongoDB drivers. + * > To learn more about the general BSON operations, see [opensavvy.ktmongo.bson.BsonArray]. + * * ### Navigating BSON types * * This interface is part of the BSON trinity: -- 2.51.2 From ff410f2fa86071ded0727c65a3b73b61a0a7f0f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Sat, 2 May 2026 15:15:57 +0200 Subject: [PATCH 7/7] docs(bson-multiplatform): Link to the interface --- bson-multiplatform/src/commonMain/kotlin/BsonArray.kt | 3 +++ bson-multiplatform/src/commonMain/kotlin/BsonDocument.kt | 3 +++ bson-multiplatform/src/commonMain/kotlin/BsonValue.kt | 3 +++ 3 files changed, 9 insertions(+) diff --git a/bson-multiplatform/src/commonMain/kotlin/BsonArray.kt b/bson-multiplatform/src/commonMain/kotlin/BsonArray.kt index 791d1b1e..0abd5b80 100644 --- a/bson-multiplatform/src/commonMain/kotlin/BsonArray.kt +++ b/bson-multiplatform/src/commonMain/kotlin/BsonArray.kt @@ -33,6 +33,9 @@ import kotlin.reflect.KType * * To create instances of this class, see [BsonFactory]. * + * > This page describes the BSON multiplatform implementation. + * > To learn more about the general BSON operations, see [opensavvy.ktmongo.bson.BsonArray]. + * * ### Navigating BSON types * * This class is part of the BSON trinity: diff --git a/bson-multiplatform/src/commonMain/kotlin/BsonDocument.kt b/bson-multiplatform/src/commonMain/kotlin/BsonDocument.kt index e69e481c..b6b87545 100644 --- a/bson-multiplatform/src/commonMain/kotlin/BsonDocument.kt +++ b/bson-multiplatform/src/commonMain/kotlin/BsonDocument.kt @@ -31,6 +31,9 @@ import kotlin.reflect.KType * * To create instances of this class, see [BsonFactory]. * + * > This page describes the BSON multiplatform implementation. + * > To learn more about the general BSON operations, see [opensavvy.ktmongo.bson.BsonDocument]. + * * ### Navigating BSON types * * This class is part of the BSON trinity: diff --git a/bson-multiplatform/src/commonMain/kotlin/BsonValue.kt b/bson-multiplatform/src/commonMain/kotlin/BsonValue.kt index 102b787d..ac370737 100644 --- a/bson-multiplatform/src/commonMain/kotlin/BsonValue.kt +++ b/bson-multiplatform/src/commonMain/kotlin/BsonValue.kt @@ -46,6 +46,9 @@ import kotlin.time.Instant * * To instantiate a [BsonDocument] or [BsonArray], see [BsonFactory]. * + * > This page describes the BSON multiplatform implementation. + * > To learn more about the general BSON operations, see [opensavvy.ktmongo.bson.BsonValue]. + * * ### Navigating BSON types * * This class is part of the BSON trinity: -- 2.51.2