DOC-614 | Added readOwnWrites option for UPSERT operations (#409)

* added readOwnWrites option for UPSERT

* Apply suggestions from code review

Co-authored-by: Simran <[email protected]>

* rephrase

Co-authored-by: Simran <[email protected]>

---------

Co-authored-by: Simran <[email protected]>

Author: nerpaula

site/content/3.12/aql/high-level-operations/upsert.md

@@ -243,6 +243,20 @@ UPSERT { a: 1234 }
   OPTIONS { indexHint: … , forceIndexHint: true }
 ```
 
+### `readOwnWrites`
+
+The `readOwnWrites` option allows an `UPSERT` operation to process its inputs one
+by one. The default value is `true`. When enabled, the `UPSERT` operation can
+observe its own writes and can handle modifying the same target document multiple
+times in the same query.
+
+When the option is set to `false`, an `UPSERT` operation processes its inputs
+in batches. Normally, a batch has 1000 inputs, which can lead to a faster execution.
+However, when using batches, the `UPSERT` operation can essentially not observe its own writes.
+You should only set the `readOwnWrites` option to `false` if you can
+guarantee that the input of the `UPSERT` leads to disjoint documents being
+inserted, updated, or replaced.
+
 ## Returning documents
 
 `UPSERT` statements can optionally return data. To do so, they need to be followed

site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md

@@ -175,6 +175,21 @@ UPDATE { logins: OLD.logins + 1 } IN users
 
 Read more about [`UPSERT` operations](../../aql/high-level-operations/upsert.md) in AQL.
 
+### `readOwnWrites` option for `UPSERT` operations
+
+A `readOwnWrites` option has been added for `UPSERT` operations. The default
+value is `true` and the behavior is identical to previous versions of ArangoDB that
+do not have this option. When enabled, an `UPSERT` operation processes its
+inputs one by one. This way, the operation can observe its own writes and can
+handle modifying the same target document multiple times in the same query.
+
+When the option is set to `false`, an `UPSERT` operation processes its inputs
+in batches. Normally, a batch has 1000 inputs, which can lead to a faster execution.
+However, when using batches, the `UPSERT` operation cannot observe its own writes.
+Therefore, you should only set the `readOwnWrites` option to `false` if you can
+guarantee that the input of the `UPSERT` leads to disjoint documents being
+inserted, updated, or replaced.
+
 ### Added AQL functions
 
 The new `PARSE_COLLECTION()` and `PARSE_KEY()` let you more extract the