DynamoDb enhanced client: support UpdateExpressions in single-request update

Author: anasatirbasa

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/operations/UpdateItemOperation.java

@@ -131,7 +131,7 @@ public UpdateItemRequest generateRequest(TableSchema<T> tableSchema,
         Map<String, AttributeValue> keyAttributes = filterMap(itemMap, entry -> primaryKeys.contains(entry.getKey()));
         Map<String, AttributeValue> nonKeyAttributes = filterMap(itemMap, entry -> !primaryKeys.contains(entry.getKey()));
 
-        Expression updateExpression = generateUpdateExpressionIfExist(tableMetadata, transformation, request, nonKeyAttributes);
+        Expression updateExpression = generateUpdateExpressionIfExist(tableMetadata, transformation, nonKeyAttributes, request);
         Expression conditionExpression = generateConditionExpressionIfExist(transformation, request);
 
         Map<String, String> expressionNames = coalesceExpressionNames(updateExpression, conditionExpression);
@@ -270,26 +270,46 @@ public TransactWriteItem generateTransactWriteItem(TableSchema<T> tableSchema, O
     }
 
     /**
-     * Retrieves the UpdateExpression from extensions if existing, and then creates an UpdateExpression for the request POJO
-     * if there are attributes to be updated (most likely). If both exist, they are merged and the code generates a final
-     * Expression that represent the result.
+     * Generates the final UpdateExpression by merging expressions from multiple sources:
+     * <ol>
+     *   <li><b>POJO attributes</b>: Creates SET/REMOVE actions for non-key attributes from the item POJO</li>
+     *   <li><b>Extension expressions</b>: Includes UpdateExpression from extensions (if any)</li>
+     *   <li><b>Request expressions</b>: Includes explicit UpdateExpression from the request (if any)</li>
+     * </ol>
+     * 
+     * <p><b>Conflict Detection:</b>
+     * <ul>
+     *   <li>POJO vs Request conflicts are detected client-side and throw {@code IllegalArgumentException}</li>
+     *   <li>Extension vs Request conflicts are detected server-side by DynamoDB and throw {@code DynamoDbException}</li>
+     * </ul>
+     * 
+     * <p><b>Attribute Filtering:</b>
+     * Attributes referenced in extension expressions are automatically excluded from REMOVE actions
+     * to prevent conflicts, even when {@code ignoreNulls} is false.
+     * 
+     * @param tableMetadata metadata about the table structure
+     * @param transformation write modification from extensions containing UpdateExpression
+     * @param attributes non-key attributes from the POJO item
+     * @param request the update request containing optional explicit UpdateExpression
+     * @return merged Expression containing the final update expression, or null if no updates needed
      */
     private Expression generateUpdateExpressionIfExist(
         TableMetadata tableMetadata,
         WriteModification transformation,
-        Either<UpdateItemEnhancedRequest<T>, TransactUpdateItemEnhancedRequest<T>> request,
-        Map<String, AttributeValue> nonKeyAttributes) {
+        Map<String, AttributeValue> attributes,
+        Either<UpdateItemEnhancedRequest<T>, TransactUpdateItemEnhancedRequest<T>> request) {
 
-        UpdateExpression requestUpdateExpression = request.map(r -> Optional.ofNullable(r.updateExpression()),
-                                                               r -> Optional.ofNullable(r.updateExpression()))
-                                                          .orElse(null);
+        UpdateExpression requestUpdateExpression =
+            request.map(r -> Optional.ofNullable(r.updateExpression()),
+                        r -> Optional.ofNullable(r.updateExpression()))
+                   .orElse(null);
 
         UpdateExpressionResolver updateExpressionResolver =
             UpdateExpressionResolver.builder()
                                     .tableMetadata(tableMetadata)
-                                    .itemNonKeyAttributes(nonKeyAttributes)
+                                    .itemNonKeyAttributes(attributes)
                                     .requestExpression(requestUpdateExpression)
-                                    .transformationExpression(transformation != null ? transformation.updateExpression() : null)
+                                    .extensionExpression(transformation != null ? transformation.updateExpression() : null)
                                     .build();
 
         UpdateExpression mergedUpdateExpression = updateExpressionResolver.resolve();

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/update/UpdateExpressionConverter.java

@@ -76,7 +76,7 @@ private UpdateExpressionConverter() {
      * @param expression the UpdateExpression to convert
      *
      * @return an Expression representing the concatenation of all actions in this UpdateExpression, or null if the expression
-     * is null or empty
+     * is null or empty (contains no actions) to avoid generating invalid empty expressions that would be rejected by DynamoDB.
      */
     public static Expression toExpression(UpdateExpression expression) {
         if (expression == null || expression.isEmpty()) {

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/update/UpdateExpressionResolver.java

@@ -30,7 +30,8 @@
 import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
 
 /**
- *
+ * Resolves and merges UpdateExpressions from multiple sources (item attributes, extensions, requests)
+ * with priority-based conflict resolution and smart filtering to prevent attribute conflicts.
  */
 @SdkInternalApi
 public final class UpdateExpressionResolver {
@@ -41,7 +42,7 @@ public final class UpdateExpressionResolver {
     private final TableMetadata tableMetadata;
 
     private UpdateExpressionResolver(Builder builder) {
-        this.extensionExpression = builder.transformationExpression;
+        this.extensionExpression = builder.extensionExpression;
         this.requestExpression = builder.requestExpression;
         this.itemNonKeyAttributes = builder.nonKeyAttributes;
         this.tableMetadata = builder.tableMetadata;
@@ -52,31 +53,40 @@ public static Builder builder() {
     }
 
     /**
-     * Resolves all available and potential update expressions by priority and returns a merged update expression. It may return
-     * null, if the item attribute map is empty / does not contain non-null attributes and no other update expressions are
-     * present.
-     * <p>
-     * Conditions that will result in error:
-     * <ul>
-     *     <li>Two expressions contain actions referencing the same attribute</li>
-     * </ul>
-     * <p>
-     * <b>Note: </b> The presence of attributes in update expressions submitted through the request or generated from extensions
-     * take precedence over removing attributes based on item configuration.
-     * For example, when IGNORE_NULLS is set to true (default), the client generates REMOVE actions for all
-     * attributes in the schema that are not explicitly set in the request item submitted to the operation. If such
-     * attributes are referenced in update expressions on the request or from extensions, the remove actions are filtered
-     * out.
+     * Merges UpdateExpressions from three sources in priority order:
+     * <ol>
+     *   <li><b>Item attributes</b>: SET/REMOVE actions from item POJO (lowest priority)</li>
+     *   <li><b>Extension expressions</b>: Override conflicting item actions (medium priority)</li>
+     *   <li><b>Request expressions</b>: Override all other sources (highest priority)</li>
+     * </ol>
+     *
+     * <p><b>Implementation steps:</b>
+     * <ol>
+     *   <li>Find attributes referenced in extension and request expressions to exclude them from removal</li>
+     *   <li>Generate SET actions for all non-null item attributes</li>
+     *   <li>Generate REMOVE actions for null item attributes, excluding those referenced in expressions</li>
+     *   <li>Combine item SET and REMOVE expressions into a single item expression</li>
+     *   <li>Merge extension expressions with item expression (extension overrides conflicting item actions)</li>
+     *   <li>Merge request expressions with combined result (request overrides all conflicting actions)</li>
+     * </ol>
+     *
+     * <p>Higher priority expressions win conflicts. REMOVE actions are filtered to prevent conflicts,
+     * even when {@code ignoreNulls} is false.
+     *
+     * <p><b>Backward compatibility:</b> This enhancement is not a breaking change. Without request
+     * expressions, behavior is identical to previous versions.
+     *
+     * @return merged UpdateExpression, or empty if no updates needed
      */
     public UpdateExpression resolve() {
-        UpdateExpression itemSetExpression = generateItemSetExpression(itemNonKeyAttributes, tableMetadata);
+        List<String> excludedFromRemoval = attributesPresentInExpressions(Arrays.asList(extensionExpression, requestExpression));
 
-        List<String> nonRemoveAttributes = attributesPresentInExpressions(Arrays.asList(extensionExpression, requestExpression));
-        UpdateExpression itemRemoveExpression = generateItemRemoveExpression(itemNonKeyAttributes, nonRemoveAttributes);
+        UpdateExpression itemSetExpression = generateItemSetExpression(itemNonKeyAttributes, tableMetadata);
+        UpdateExpression itemRemoveExpression = generateItemRemoveExpression(itemNonKeyAttributes, excludedFromRemoval);
+        UpdateExpression itemFinalExpression = UpdateExpression.mergeExpressions(itemSetExpression, itemRemoveExpression);
 
-        UpdateExpression itemExpression = UpdateExpression.mergeExpressions(itemSetExpression, itemRemoveExpression);
-        UpdateExpression extensionItemExpression = UpdateExpression.mergeExpressions(extensionExpression, itemExpression);
-        return UpdateExpression.mergeExpressions(requestExpression, extensionItemExpression);
+        UpdateExpression itemAndExtensionExpression = UpdateExpression.mergeExpressions(extensionExpression, itemFinalExpression);
+        return UpdateExpression.mergeExpressions(requestExpression, itemAndExtensionExpression);
     }
 
     private static List<String> attributesPresentInExpressions(List<UpdateExpression> updateExpressions) {
@@ -108,7 +118,7 @@ public static UpdateExpression generateItemRemoveExpression(Map<String, Attribut
     public static final class Builder {
 
         private TableMetadata tableMetadata;
-        private UpdateExpression transformationExpression;
+        private UpdateExpression extensionExpression;
         private UpdateExpression requestExpression;
         private Map<String, AttributeValue> nonKeyAttributes;
 
@@ -117,8 +127,8 @@ public Builder tableMetadata(TableMetadata tableMetadata) {
             return this;
         }
 
-        public Builder transformationExpression(UpdateExpression transformationExpression) {
-            this.transformationExpression = transformationExpression;
+        public Builder extensionExpression(UpdateExpression extensionExpression) {
+            this.extensionExpression = extensionExpression;
             return this;
         }
 

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/model/TransactUpdateItemEnhancedRequest.java

@@ -247,27 +247,21 @@ public Builder<T> item(T item) {
         }
 
         /**
-         * Define an {@link UpdateExpression} to control updating specific parts of the item in DynamoDb. The update expression
-         * corresponds to the DynamoDb update expression format. It can be used to set, modify and delete attributes for use cases
-         * that simply supplying the item does not cover; in particular, manipulating composed attributes such as sets or lists:
-         * <ul>
-         * <li>Add/remove elements to/from list attributes</li>
-         * <li>Add/remove elements to/from set attributes</li>
-         * <li>Unset or nullify attributes without modifying the whole attribute</li>
-         * </ul>
+         * Specifies custom update operations using DynamoDB's native update expression syntax. Enables advanced modifications
+         * like incrementing counters or modifying lists/sets.
          * <p>
-         * This method will throw an exception if the expression references an attribute that is already present on the
-         * item, or is modified through an extension.
+         * <b>Precedence:</b> Request expressions (highest) > Extension expressions > Item attributes (lowest).
+         * This method overrides any conflicting operations from item attributes or extensions.
          * <p>
-         * <b>Note: </b>This is a powerful mechanism that bypasses many of the abstractions and
-         * safety checks in the enhanced client, and should be used with caution. Only use it when submitting only
-         * a configured item bean/object is insufficient.
-         * <p>
-         * See {@link UpdateExpression}, {@link AddAction}, {@link DeleteAction}, {@link SetAction} and
-         * {@link RemoveAction} for syntax and examples.
+         * <b>Backward compatible:</b> New feature that doesn't affect existing behavior when not used.
          *
-         * @param updateExpression a composed expression of type {@link UpdateExpression}
+         * @param updateExpression the update operations to perform
          * @return a builder of this type
+         * @see UpdateExpression
+         * @see SetAction
+         * @see AddAction
+         * @see RemoveAction
+         * @see DeleteAction
          */
         public Builder<T> updateExpression(UpdateExpression updateExpression) {
             this.updateExpression = updateExpression;

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/model/UpdateItemEnhancedRequest.java

@@ -332,27 +332,21 @@ public Builder<T> item(T item) {
         }
 
         /**
-         * Define an {@link UpdateExpression} to control updating specific parts of the item in DynamoDb. The update expression
-         * corresponds to the DynamoDb update expression format. It can be used to set, modify and delete attributes for use cases
-         * that simply supplying the item does not cover; in particular, manipulating composed attributes such as sets or lists:
-         * <ul>
-         * <li>Add/remove elements to/from list attributes</li>
-         * <li>Add/remove elements to/from set attributes</li>
-         * <li>Unset or nullify attributes without modifying the whole attribute</li>
-         * </ul>
+         * Specifies custom update operations using DynamoDB's native update expression syntax. Enables advanced modifications
+         * like incrementing counters or modifying lists/sets.
          * <p>
-         * This method will throw an exception if the expression references an attribute that is already present on the
-         * item, or is modified through an extension.
+         * <b>Precedence:</b> Request expressions (highest) > Extension expressions > Item attributes (lowest).
+         * This method overrides any conflicting operations from item attributes or extensions.
          * <p>
-         * <b>Note: </b>This is a powerful mechanism that bypasses many of the abstractions and
-         * safety checks in the enhanced client, and should be used with caution. Only use it when submitting only
-         * a configured item bean/object is insufficient.
-         * <p>
-         * See {@link UpdateExpression}, {@link AddAction}, {@link DeleteAction}, {@link SetAction} and
-         * {@link RemoveAction} for syntax and examples.
+         * <b>Backward compatible:</b> New feature that doesn't affect existing behavior when not used.
          *
-         * @param updateExpression a composed expression of type {@link UpdateExpression}
+         * @param updateExpression the update operations to perform
          * @return a builder of this type
+         * @see UpdateExpression
+         * @see SetAction
+         * @see AddAction
+         * @see RemoveAction
+         * @see DeleteAction
          */
         public Builder<T> updateExpression(UpdateExpression updateExpression) {
             this.updateExpression = updateExpression;