docs: DynamoDB Recommendation of offset batches (#1263)

akka · Nov 22, 2024 · d3ad158 · d3ad158
1 parent c422baa
commit d3ad158
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 3 deletions.
diff --git a/...tion-dynamodb-integration/src/test/java/projection/docs/javadsl/ProjectionDocExample.java b/...tion-dynamodb-integration/src/test/java/projection/docs/javadsl/ProjectionDocExample.java
@@ -382,7 +382,7 @@ public void atLeastOnceExample(
 
     Optional<DynamoDBProjectionSettings> settings = Optional.empty();
 
-    int saveOffsetAfterEnvelopes = 100;
+    int saveOffsetAfterEnvelopes = 25;
     Duration saveOffsetAfterDuration = Duration.ofMillis(500);
 
     Projection<EventEnvelope<ShoppingCart.Event>> projection =
@@ -407,7 +407,7 @@ public void exactlyOnceGroupedWithinExample(
 
     Optional<DynamoDBProjectionSettings> settings = Optional.empty();
 
-    int groupAfterEnvelopes = 20;
+    int groupAfterEnvelopes = 25;
     Duration groupAfterDuration = Duration.ofMillis(500);
 
     Projection<EventEnvelope<ShoppingCart.Event>> projection =
@@ -433,7 +433,7 @@ public void atLeastOnceGroupedWithinExample(
 
     Optional<DynamoDBProjectionSettings> settings = Optional.empty();
 
-    int groupAfterEnvelopes = 20;
+    int groupAfterEnvelopes = 25;
     Duration groupAfterDuration = Duration.ofMillis(500);
 
     Projection<EventEnvelope<ShoppingCart.Event>> projection =

diff --git a/docs/src/main/paradox/dynamodb.md b/docs/src/main/paradox/dynamodb.md
@@ -81,6 +81,16 @@ Scala
 
 By default, Akka Projection DynamoDB shares the @extref:[DynamoDB client configuration](akka-persistence-dynamodb:config.html#dynamodb-client-configuration) with Akka Persistence DynamoDB.
 
+### Batch writes
+
+Offsets are written in batches for @ref:[at-least-once](#at-least-once) and @ref:[at-least-once (grouped)](#at-least-once-grouped-).
+To reduce the risk of write throttling it is recommended to save at most 25 offsets at a time. This is configured by:  
+
+```hcon
+akka.projection.at-least-once.save-offset-after-envelopes = 25
+akka.projection.grouped.group-after-envelopes = 25
+```
+
 ### Reference configuration
 
 The following can be overridden in your `application.conf` for projection specific settings:
@@ -164,6 +174,8 @@ defined in the configuration section `akka.projection.at-least-once`. There is a
 offset too often, but the drawback is that there can be more duplicates that will be processed again when the
 projection is restarted.
 
+Offsets are written in batches. To reduce the risk of write throttling it is recommended to save at most 25 offsets at a time.
+
 The @ref:[`ShoppingCartHandler` is shown below](#generic-handler).
 
 ## exactly-once (grouped)
@@ -204,6 +216,9 @@ Java
 Scala
 :  @@snip [at least once grouped within](/akka-projection-dynamodb-integration/src/test/scala/projection/docs/scaladsl/ProjectionDocExample.scala) { #at-least-once-grouped-within }
 
+Offsets are written immediately after the group of envelopes has been processed. To reduce the risk of write throttling
+it is recommended to save at most 25 offsets at a time, and therefore not exceed this for the group size.
+
 The @ref:[`GroupedShoppingCartHandler` is shown below](#grouped-handler).
 
 ## Handler