Class FilterExpression

java.lang.Object
dev.hogwai.dynamodb.simplified.expression.FilterExpression
Direct Known Subclasses:
ConditionExpression, ConditionExpression.Builder
public class FilterExpression extends Object
Fluent builder for constructing DynamoDB filter and condition expressions.

Used as a filter expression (post-read filtering) in Scan and Query operations, and as a condition expression (pre-write gating) in PutItem, UpdateItem, and DeleteItem operations. DynamoDB distinguishes these two semantics, see the DynamoDB Developer Guide for details on the difference.

Provides a chainable API for building complex filter conditions including comparisons (=, <>, <, <=, >, >=), string functions (begins_with, contains), server-side size() comparisons, attribute existence checks, attribute type checks, BETWEEN, IN, and logical combinators (AND, OR, NOT). All attribute names and values are automatically mapped to expression attribute names (#n0, #n1, ...) and expression attribute values (:v0, :v1, ...) to avoid reserved word conflicts and simplify value handling.

  • Constructor Details

    • FilterExpression

      protected FilterExpression()
      Creates an empty filter expression.

    • FilterExpression

      protected FilterExpression(FilterExpression other)
      Creates a copy of the given filter expression. Subclasses can use this to create instances backed by an existing FilterExpression.
      Parameters:
      other - the filter expression to copy

  • Method Details

    • builder

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

    • toSdkExpression

      public @NonNull software.amazon.awssdk.enhanced.dynamodb.Expression toSdkExpression()
      Converts this filter expression into an AWS SDK Expression for use with enhanced client request builders.
      Returns:
      the SDK expression

    • eq

      public @NonNull FilterExpression eq(@NonNull String attribute, @NonNull Object value)
      Adds an equality condition: attribute = value.
      Parameters:
      attribute - the attribute name
      value - the value to compare against
      Returns:
      this builder for chaining

    • ne

      public @NonNull FilterExpression ne(@NonNull String attribute, @NonNull Object value)
      Adds a not-equal condition: attribute <> value.
      Parameters:
      attribute - the attribute name
      value - the value to compare against
      Returns:
      this builder for chaining

    • lt

      public @NonNull FilterExpression lt(@NonNull String attribute, @NonNull Object value)
      Adds a less-than condition: attribute < value.
      Parameters:
      attribute - the attribute name
      value - the value to compare against
      Returns:
      this builder for chaining

    • le

      public @NonNull FilterExpression le(@NonNull String attribute, @NonNull Object value)
      Adds a less-than-or-equal condition: attribute <= value.
      Parameters:
      attribute - the attribute name
      value - the value to compare against
      Returns:
      this builder for chaining

    • gt

      public @NonNull FilterExpression gt(@NonNull String attribute, @NonNull Object value)
      Adds a greater-than condition: attribute > value.
      Parameters:
      attribute - the attribute name
      value - the value to compare against
      Returns:
      this builder for chaining

    • ge

      public @NonNull FilterExpression ge(@NonNull String attribute, @NonNull Object value)
      Adds a greater-than-or-equal condition: attribute >= value.
      Parameters:
      attribute - the attribute name
      value - the value to compare against
      Returns:
      this builder for chaining

    • beginsWith

      public @NonNull FilterExpression beginsWith(@NonNull String attribute, @NonNull String prefix)
      Adds a begins_with function condition checking whether the attribute value starts with the given prefix.
      Parameters:
      attribute - the attribute name
      prefix - the string prefix to test
      Returns:
      this builder for chaining

    • contains

      public @NonNull FilterExpression contains(@NonNull String attribute, @NonNull Object value)
      Adds a contains function condition checking whether the attribute value contains the given substring (for strings) or element (for sets).
      Parameters:
      attribute - the attribute name
      value - the value to search for within the attribute
      Returns:
      this builder for chaining

    • sizeEq

      public @NonNull FilterExpression sizeEq(String attribute, int size)
      Adds a condition that the server-side size() of the attribute equals the given value.
      Parameters:
      attribute - the attribute name
      size - the expected size
      Returns:
      this builder for chaining

    • sizeLt

      public @NonNull FilterExpression sizeLt(String attribute, int size)
      Adds a condition that the server-side size() of the attribute is less than the given value.
      Parameters:
      attribute - the attribute name
      size - the size to compare against
      Returns:
      this builder for chaining

    • sizeLe

      public @NonNull FilterExpression sizeLe(String attribute, int size)
      Adds a condition that the server-side size() of the attribute is less than or equal to the given value.
      Parameters:
      attribute - the attribute name
      size - the size to compare against
      Returns:
      this builder for chaining

    • sizeGt

      public @NonNull FilterExpression sizeGt(String attribute, int size)
      Adds a condition that the server-side size() of the attribute is greater than the given value.
      Parameters:
      attribute - the attribute name
      size - the size to compare against
      Returns:
      this builder for chaining

    • sizeGe

      public @NonNull FilterExpression sizeGe(String attribute, int size)
      Adds a condition that the server-side size() of the attribute is greater than or equal to the given value.
      Parameters:
      attribute - the attribute name
      size - the size to compare against
      Returns:
      this builder for chaining

    • sizeBetween

      public @NonNull FilterExpression sizeBetween(String attribute, int minSize, int maxSize)
      Adds a condition that the server-side size() of the attribute is between the given minimum and maximum values (inclusive).
      Parameters:
      attribute - the attribute name
      minSize - the minimum size
      maxSize - the maximum size
      Returns:
      this builder for chaining

    • exists

      public @NonNull FilterExpression exists(@NonNull String attribute)
      Adds an attribute_exists condition that checks whether the specified attribute is present on the item.
      Parameters:
      attribute - the attribute name
      Returns:
      this builder for chaining

    • notExists

      public @NonNull FilterExpression notExists(@NonNull String attribute)
      Adds an attribute_not_exists condition that checks whether the specified attribute is not present on the item.
      Parameters:
      attribute - the attribute name
      Returns:
      this builder for chaining

    • attributeType

      public @NonNull FilterExpression attributeType(@NonNull String attribute, @NonNull FilterExpression.AttributeType type)
      Adds an attribute_type condition that checks whether the specified attribute is of the given DynamoDB type.
      Parameters:
      attribute - the attribute name
      type - the expected FilterExpression.AttributeType
      Returns:
      this builder for chaining

    • between

      public @NonNull FilterExpression between(@NonNull String attribute, @NonNull Object low, @NonNull Object high)
      Adds a BETWEEN condition: attribute BETWEEN low AND high (inclusive). Supports strings, numbers, and binaries.
      Parameters:
      attribute - the attribute name
      low - the lower bound
      high - the upper bound
      Returns:
      this builder for chaining

    • in

      public @NonNull FilterExpression in(@NonNull String attribute, @NonNull Object... values)
      Adds an IN condition: attribute IN (val1, val2, ...). The attribute must match at least one of the provided values.
      Parameters:
      attribute - the attribute name
      values - one or more values to test against
      Returns:
      this builder for chaining

    • and

      public @NonNull FilterExpression and()
      Appends an AND logical operator to combine two filter conditions.
      Returns:
      this builder for chaining

    • or

      public @NonNull FilterExpression or()
      Appends an OR logical operator to combine two filter conditions.
      Returns:
      this builder for chaining

    • not

      public @NonNull FilterExpression not()
      Appends a NOT logical operator to negate the following condition.
      Returns:
      this builder for chaining

    • group

      public @NonNull FilterExpression group(@NonNull FilterExpression nested)
      Wraps the given nested FilterExpression in parentheses and merges its expression attribute names and values into this builder. Useful for creating grouped or nested conditions with proper precedence.
      Parameters:
      nested - the filter expression to wrap in parentheses
      Returns:
      this builder for chaining

    • nestedEq

      public @NonNull FilterExpression nestedEq(@NonNull String path, @NonNull Object value)
      Adds an equality condition on a nested attribute path (e.g., address.city). Dot-separated path segments are resolved to individual expression attribute names, and list indices (e.g., items[0]) are supported.
      Parameters:
      path - the nested attribute path (e.g., "address.city")
      value - the value to compare against
      Returns:
      this builder for chaining

    • getExpression

      public @NonNull String getExpression()
      Returns the built filter expression string (e.g., "#n0 = :v0 AND begins_with(#n1, :v1)").
      Returns:
      the filter 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., #n0) 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., :v0) and values are the corresponding AttributeValue instances.
      Returns:
      the expression attribute values map

    • isEmpty

      public boolean isEmpty()
      Returns whether no conditions have been added to this expression yet.
      Returns:
      true if the expression is empty, false otherwise