From 7f561eaa23a4fb456d2311033ca271eb7a68f6c9 Mon Sep 17 00:00:00 2001 From: Paula Date: Thu, 4 Jan 2024 12:44:41 +1100 Subject: [PATCH 1/3] added readOwnWrites option for UPSERT --- .../3.12/aql/high-level-operations/upsert.md | 14 ++++++++++++++ .../version-3.12/whats-new-in-3-12.md | 14 ++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/site/content/3.12/aql/high-level-operations/upsert.md b/site/content/3.12/aql/high-level-operations/upsert.md index 29bfa9e3b8..683ef096a8 100644 --- a/site/content/3.12/aql/high-level-operations/upsert.md +++ b/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 `UPSERT` operations 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. A batch has normally 1000 inputs, so it can lead to a faster execution. +However, when using batches, the `UPSERT` operation cannot observe its own writes. +The `readOwnWrites` option should be set to `false` only if it can +be guaranteed 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 diff --git a/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md b/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md index 7bd2e11843..d992bd7052 100644 --- a/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md +++ b/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md @@ -174,6 +174,20 @@ 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 + +The `readOwnWrites` option has been added for `UPSERT` operations. The default +value is `true`. When set to `true`, 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. A batch has normally 1000 inputs, so it can lead to a faster execution. +However, when using batches, the `UPSERT` operation cannot observe its own writes. +Therefore, the `readOwnWrites` option should be set to `false` only if it can +be guaranteed 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 From c1e689b5f2878c0e3931bf6b74a48535cf152453 Mon Sep 17 00:00:00 2001 From: Paula Mihu <97217318+nerpaula@users.noreply.github.com> Date: Thu, 4 Jan 2024 21:09:07 +1100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Simran --- site/content/3.12/aql/high-level-operations/upsert.md | 8 ++++---- .../release-notes/version-3.12/whats-new-in-3-12.md | 11 ++++++----- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/site/content/3.12/aql/high-level-operations/upsert.md b/site/content/3.12/aql/high-level-operations/upsert.md index 683ef096a8..b9e0254ebd 100644 --- a/site/content/3.12/aql/high-level-operations/upsert.md +++ b/site/content/3.12/aql/high-level-operations/upsert.md @@ -245,16 +245,16 @@ UPSERT { a: 1234 } ### `readOwnWrites` -The `readOwnWrites` option allows `UPSERT` operations to process its inputs one +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. A batch has normally 1000 inputs, so it can lead to a faster execution. +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. -The `readOwnWrites` option should be set to `false` only if it can -be guaranteed that the input of the `UPSERT` leads to disjoint documents being +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 diff --git a/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md b/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md index d992bd7052..43d6db5e44 100644 --- a/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md +++ b/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md @@ -176,16 +176,17 @@ Read more about [`UPSERT` operations](../../aql/high-level-operations/upsert.md) ### `readOwnWrites` option for `UPSERT` operations -The `readOwnWrites` option has been added for `UPSERT` operations. The default -value is `true`. When set to `true`, an `UPSERT` operation processes its +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. A batch has normally 1000 inputs, so it can lead to a faster execution. +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, the `readOwnWrites` option should be set to `false` only if it can -be guaranteed that the input of the `UPSERT` leads to disjoint documents being +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 From 400056242b2d1c66c2975b7fb22268175aacd98b Mon Sep 17 00:00:00 2001 From: Paula Mihu <97217318+nerpaula@users.noreply.github.com> Date: Sat, 6 Jan 2024 17:59:40 +1100 Subject: [PATCH 3/3] rephrase Co-authored-by: Simran --- site/content/3.12/aql/high-level-operations/upsert.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/content/3.12/aql/high-level-operations/upsert.md b/site/content/3.12/aql/high-level-operations/upsert.md index b9e0254ebd..f5b94cb14e 100644 --- a/site/content/3.12/aql/high-level-operations/upsert.md +++ b/site/content/3.12/aql/high-level-operations/upsert.md @@ -252,7 +252,7 @@ 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. +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.