merge: Add upgrade operations to the website

docs/website/docs/guides/search.md

@@ -1,7 +1,7 @@
 # Find data
 
 !!! note ""
-Before retrieving data, you must [connect to the database and obtain a collection](setup.md).
+    Before retrieving data, you must [connect to the database and obtain a collection](setup.md).
 
 Let's assume we have the following class:
 

docs/website/docs/guides/update.md

@@ -0,0 +1,76 @@
+# Update data
+
+!!! note ""
+    Before retrieving data, you must [connect to the database and obtain a collection](setup.md).
+
+Let's assume we have the following class:
+
+```kotlin
+class User(
+	val name: String,
+	val age: Int,
+)
+```
+
+## Updating multiple documents
+
+To update all elements in a collection, use `updateMany`:
+
+```kotlin
+collection.updateMany {
+	User::age set 18
+}
+```
+
+To update only specific documents, add a filter:
+
+```kotlin
+collection.updateMany(
+	filter = {
+		User::name eq "Bob"
+	},
+	update = {
+		User::age set 18
+	}
+)
+```
+
+Alternatively, create a filtered collection to avoid the two-lambda syntax:
+
+```kotlin
+collection
+	.filter { User::name eq "Bob" }
+	.updateMany { User::age set 18 }
+```
+
+## Updating a single document
+
+To update a single document, use `updateOne` instead. The syntax is identical.
+
+If you'd like to atomically update and retrieve a document, use `findOneByUpdate`. See its option to decide between retrieving the document before or after the update.
+
+## Inserting a document if it doesn't exist
+
+When using `updateOne` with a filter, the operation does nothing if the filter doesn't exist. If, instead, you want to create the document if it doesn't exist, use `upsertOne`:
+```kotlin
+collection.upsertOne(
+	filter = {
+		User::name eq "Bob"
+	},
+	update = {
+		User::age set 18
+	}
+)
+```
+
+If there exists a document with a `name` of "Bob", it is updated. If none exist, the following document is created:
+```json
+{
+    "name": "Bob",
+    "age": 18
+}
+```
+
+Not all filter expressions are added to the created object. To learn more, visit `upsertOne`'s documentation.
+
+`upsertOne` is also compatible with filtered collections.

docs/website/docs/migrate-from-kmongo/update.md

@@ -0,0 +1,91 @@
+# Update data
+
+Much like [find variants](search.md), update operations use a DSL instead of passing raw BSON values.
+
+## Updating multiple documents
+
+Like with KMongo, the function to update multiple documents is `updateMany`.
+
+```kotlin title="With KMongo"
+collection.updateMany(
+	filter = and(
+		User::name.exists(),
+		User::age gt 18
+	),
+	set(
+		User::isLegal setTo true
+	)
+)
+```
+
+```kotlin title="With KtMongo"
+collection.updateMany(
+	filter = {
+		User::name.exists()
+		User::age gt 18
+	},
+	update = {
+		User::isLegal set true
+	}
+)
+```
+
+To learn more about filtering, visit [the find documentation](search.md).
+
+Unlike in KMongo, there is no need to combine multiple operators yourself, the library will do it for you. The order of operators is not relevant.
+
+```kotlin title="With KMongo"
+collection.updateMany(
+	filter = …,
+	set(
+		User::name setTo "foo",
+		User::isLegal setTo true,
+	),
+	inc(
+		User::age setTo 1
+	)
+)
+```
+
+```kotlin title="With KtMongo"
+collection.updateMany(
+	filter = { … },
+	update = {
+		User::name set "foo"
+		User::isLegal set true
+		User::age inc 1
+	}
+)
+```
+
+## Updating a single document
+
+Like in KMongo, KtMongo provides a dedicated function to edit a single element, `updateOne`. 
+
+## Inserting a document if it doesn't exist
+
+KtMongo provides an overload to perform upserts:
+
+```kotlin title="With KMongo"
+collection.updateOne(
+	filter = …,
+	setOnInsert(
+		User::creationDate setTo Instant.now(),
+	),
+	UpdateOptions().upsert(true)
+)
+```
+
+```kotlin title="With KtMongo"
+collection.upsertOne(
+	filter = { … },
+	update = {
+		User::creationDate setOnInsert Instant.now()
+	}
+)
+```
+
+!!! tip
+    It is also possible to perform an upsert by setting `UpdateOptions().upsert(true)`, as well as setting any other update options, with `updateOne` and `updateMany`, just like in KMongo. `upsertOne` is just syntactic sugar, since we find that we use it very often.
+
+    Note that options are often the first parameter instead of the last (because the last is the lambda block). Other than that, they behave identically.

docs/website/mkdocs.yml

@@ -87,6 +87,7 @@ nav:
       - guides/overview.md
       - guides/setup.md
       - guides/search.md
+      - guides/update.md
 
   - Migrating from KMongo:
       - migrate-from-kmongo/why.md