Class UpdateExpression

java.lang.Object
dev.hogwai.dynamodb.simplified.expression.UpdateExpression
public class UpdateExpression extends Object
Fluent builder for constructing DynamoDB update expressions as part of the DynamoDB Simplified library.

Supports all four update expression clauses, SET, REMOVE, ADD, and DELETE, with a chainable API. The builder automatically manages expression attribute name placeholders (#u0, #u1, ...) and expression attribute value placeholders (:u0, :u1, ...) to avoid reserved word conflicts. Common update patterns such as incrementing/decrementing numbers, appending/prepending to lists, and adding/removing set elements are provided as dedicated methods.

  • Method Details

    • builder

      public static @NonNull UpdateExpression builder()
      Creates a new UpdateExpression builder.
      Returns:
      a new empty UpdateExpression

    • set

      public @NonNull UpdateExpression set(@NonNull String attribute, @Nullable Object value)
      Adds a SET action that assigns the given value to the specified attribute, overwriting any existing value.
      Parameters:
      attribute - the attribute name (must not be null)
      value - the value to set (must not be null: use remove(String...) instead)
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if value is null

    • setIfNotExists

      public @NonNull UpdateExpression setIfNotExists(@NonNull String attribute, @NonNull Object value)
      Adds a SET action that assigns the given value to the specified attribute only if the attribute does not already exist, using the if_not_exists function.
      Parameters:
      attribute - the attribute name
      value - the value to set if the attribute does not exist
      Returns:
      this builder for chaining

    • increment

      public @NonNull UpdateExpression increment(@NonNull String attribute, @NonNull Number delta)
      Adds a SET action that increments a number attribute by the given delta using an in-place arithmetic expression (attr = attr + delta).
      Parameters:
      attribute - the attribute name
      delta - the amount to increment by
      Returns:
      this builder for chaining

    • decrement

      public @NonNull UpdateExpression decrement(@NonNull String attribute, @NonNull Number delta)
      Adds a SET action that decrements a number attribute by the given delta using an in-place arithmetic expression (attr = attr - delta).
      Parameters:
      attribute - the attribute name
      delta - the amount to decrement by
      Returns:
      this builder for chaining

    • appendToList

      public @NonNull UpdateExpression appendToList(@NonNull String attribute, @NonNull List<?> values)
      Adds a SET action that appends a list of values to an existing list attribute using list_append. If the attribute does not exist, it is initialized to an empty list before appending.
      Parameters:
      attribute - the list attribute name
      values - the values to append
      Returns:
      this builder for chaining

    • prependToList

      public @NonNull UpdateExpression prependToList(@NonNull String attribute, @NonNull List<?> values)
      Adds a SET action that prepends a list of values to an existing list attribute using list_append. If the attribute does not exist, it is initialized to an empty list before prepending.
      Parameters:
      attribute - the list attribute name
      values - the values to prepend
      Returns:
      this builder for chaining

    • setListElement

      public @NonNull UpdateExpression setListElement(@NonNull String attribute, int index, @NonNull Object value)
      Adds a SET action that assigns a value to a specific element in a list attribute by index (e.g., myList[2] = value).
      Parameters:
      attribute - the list attribute name
      index - the zero-based index of the element to set
      value - the value to assign
      Returns:
      this builder for chaining

    • setNested

      public @NonNull UpdateExpression setNested(@NonNull String path, @NonNull Object value)
      Adds a SET action that assigns a value to a nested attribute path (dot-separated), such as address.city. Each path segment is individually mapped to an expression attribute name placeholder.
      Parameters:
      path - the nested attribute path (e.g., "address.city")
      value - the value to set
      Returns:
      this builder for chaining

    • ttl

      public @NonNull UpdateExpression ttl(@NonNull String attribute, @NonNull Duration duration)
      Sets the TTL attribute to the given duration from now.

      Convenience method that computes the epoch timestamp and delegates to set(String, Object).

      Parameters:
      attribute - the TTL attribute name
      duration - the duration from now when the item should expire
      Returns:
      this builder for chaining

    • remove

      public @NonNull UpdateExpression remove(@NonNull String... attributes)
      Adds one or more attributes to the REMOVE clause, deleting them from the item.
      Parameters:
      attributes - one or more attribute names to remove
      Returns:
      this builder for chaining

    • removeListElement

      public @NonNull UpdateExpression removeListElement(@NonNull String attribute, int index)
      Adds a specific list element to the REMOVE clause, removing it by index (e.g., myList[2]).
      Parameters:
      attribute - the list attribute name
      index - the zero-based index of the element to remove
      Returns:
      this builder for chaining

    • addToSet

      public @NonNull UpdateExpression addToSet(@NonNull String attribute, @NonNull Set<?> values)
      Adds an ADD action that inserts the given values into a set attribute. If the attribute does not exist, DynamoDB creates it with the provided values.
      Parameters:
      attribute - the set attribute name
      values - the values to add to the set
      Returns:
      this builder for chaining

    • addNumber

      public @NonNull UpdateExpression addNumber(@NonNull String attribute, @NonNull Number value)
      Adds an ADD action that increments a number attribute by the given value. This uses the ADD clause rather than SET, which is useful for atomic counters in scenarios where you want to ensure the increment is applied regardless of concurrent modifications (DynamoDB ADD is idempotent for sets but not for numbers).
      Parameters:
      attribute - the number attribute name
      value - the amount to add
      Returns:
      this builder for chaining

    • deleteFromSet

      public @NonNull UpdateExpression deleteFromSet(@NonNull String attribute, @NonNull Set<?> values)
      Adds a DELETE action that removes the given values from a set attribute.
      Parameters:
      attribute - the set attribute name
      values - the values to remove from the set
      Returns:
      this builder for chaining

    • getExpression

      public @NonNull String getExpression()
      Returns the built update expression string with SET, REMOVE, ADD, and/or DELETE clauses, formatted as required by the DynamoDB API (e.g., "SET #u0 = :u0, #u1 = :u1 REMOVE #u2"). Only non-empty clauses are included.
      Returns:
      the update expression string

    • getExpressionNames

      public @NonNull Map<String,String> getExpressionNames()
      Returns the map of expression attribute names used in this expression. Keys are the generated placeholders (e.g., #u0) and values are the original attribute names.
      Returns:
      the expression attribute names map

    • getExpressionValues

      public @NonNull Map<String, software.amazon.awssdk.services.dynamodb.model.AttributeValue> getExpressionValues()
      Returns the map of expression attribute values used in this expression. Keys are the generated placeholders (e.g., :u0) and values are the corresponding AttributeValue instances.
      Returns:
      the expression attribute values map

    • isEmpty

      public boolean isEmpty()
      Returns whether no update actions have been added to this expression yet.
      Returns:
      true if no actions have been added, false otherwise