Class EntityQueryBuilder

java.lang.Object
dev.hogwai.dynamodb.simplified.entity.EntityQueryBuilder
public final class EntityQueryBuilder extends Object
Builds and executes cross-entity queries across multiple entity types sharing a single DynamoDB table (single-table design).

Supports partition key filtering, sort key conditions, discriminator-based entity filtering, pagination, and projection.

See Also:

  • Constructor Details

    • EntityQueryBuilder

      public EntityQueryBuilder(@NonNull software.amazon.awssdk.services.dynamodb.DynamoDbClient dynamoDbClient, @NonNull String tableName, @NonNull String discriminatorAttribute)
      Creates a cross-entity query builder for a table and discriminator attribute.
      Parameters:
      dynamoDbClient - the low-level DynamoDB client used to execute queries
      tableName - the DynamoDB table shared by the entity types
      discriminatorAttribute - the attribute containing each entity's discriminator

  • Method Details

    • partitionKey

      public @NonNull EntityQueryBuilder partitionKey(@NonNull Object partitionKey)
      Sets the partition key value for the query. Resets any previously configured sort key condition.
      Parameters:
      partitionKey - the partition key value
      Returns:
      this builder for chaining

    • limit

      public @NonNull EntityQueryBuilder limit(int limit)
      Limits the number of items returned per page.
      Parameters:
      limit - the maximum number of items per page
      Returns:
      this builder for chaining

    • includeEntity

      public @NonNull EntityQueryBuilder includeEntity(@NonNull Class<?> entityClass)
      Includes an entity type in the cross-entity query results. Items matching the entity's discriminator value will be deserialized into the given entity class.
      Parameters:
      entityClass - the entity class to include
      Returns:
      this builder for chaining

    • includeEntity

      public @NonNull EntityQueryBuilder includeEntity(@NonNull EntitySchema<?> schema)
      Includes an entity type using a pre-built EntitySchema.
      Parameters:
      schema - the entity schema to include
      Returns:
      this builder for chaining

    • sortKeyBeginsWith

      public @NonNull EntityQueryBuilder sortKeyBeginsWith(@NonNull Object value)
      Adds a sort key condition: sort key begins with the given prefix.
      Parameters:
      value - the prefix value
      Returns:
      this builder for chaining

    • sortKeyEquals

      public @NonNull EntityQueryBuilder sortKeyEquals(@NonNull Object value)
      Adds a sort key condition: sort key equals the given value.
      Parameters:
      value - the value to match
      Returns:
      this builder for chaining

    • sortKeyBetween

      public @NonNull EntityQueryBuilder sortKeyBetween(@NonNull Object from, @NonNull Object to)
      Adds a sort key condition: sort key is between the given values (inclusive).
      Parameters:
      from - the lower bound (inclusive)
      to - the upper bound (inclusive)
      Returns:
      this builder for chaining

    • sortKeyGreaterThan

      public @NonNull EntityQueryBuilder sortKeyGreaterThan(@NonNull Object value)
      Adds a sort key condition: sort key is strictly greater than the given value.
      Parameters:
      value - the threshold value
      Returns:
      this builder for chaining

    • sortKeyGreaterThanOrEqual

      public @NonNull EntityQueryBuilder sortKeyGreaterThanOrEqual(@NonNull Object value)
      Adds a sort key condition: sort key is greater than or equal to the given value.
      Parameters:
      value - the threshold value
      Returns:
      this builder for chaining

    • sortKeyLessThan

      public @NonNull EntityQueryBuilder sortKeyLessThan(@NonNull Object value)
      Adds a sort key condition: sort key is strictly less than the given value.
      Parameters:
      value - the threshold value
      Returns:
      this builder for chaining

    • sortKeyLessThanOrEqual

      public @NonNull EntityQueryBuilder sortKeyLessThanOrEqual(@NonNull Object value)
      Adds a sort key condition: sort key is less than or equal to the given value.
      Parameters:
      value - the threshold value
      Returns:
      this builder for chaining

    • project

      public @NonNull EntityQueryBuilder project(@NonNull String... attributes)
      Restricts the returned attributes to the specified ones.
      Parameters:
      attributes - the attribute names to include in the result
      Returns:
      this builder for chaining

    • consistentRead

      public @NonNull EntityQueryBuilder consistentRead(boolean consistentRead)
      Enables or disables strongly consistent reads.
      Parameters:
      consistentRead - true for a strongly consistent read, false (the default) for an eventually consistent read
      Returns:
      this builder for chaining

    • scanIndexForward

      public @NonNull EntityQueryBuilder scanIndexForward(boolean forward)
      Sets the sort order for the query results.
      Parameters:
      forward - true for ascending order (the default), false for descending order
      Returns:
      this builder for chaining

    • startFrom

      public @NonNull EntityQueryBuilder startFrom(@Nullable Map<String, software.amazon.awssdk.services.dynamodb.model.AttributeValue> lastEvaluatedKey)
      Sets the exclusive start key for the next paginated query. The key is typically obtained from CrossEntityResultWithPagination.getLastEvaluatedKey().
      Parameters:
      lastEvaluatedKey - the key returned by a previous page, or null to start from the beginning
      Returns:
      this builder for chaining

    • execute

      public @NonNull CrossEntityResult execute()
      Executes the query and returns all matching items grouped by entity type.
      Returns:
      a CrossEntityResult containing items mapped by entity class
      Throws:
      IllegalStateException - if the partition key has not been set

    • executeWithPagination

      public @NonNull CrossEntityResultWithPagination executeWithPagination()
      Executes the query and returns the first page of results along with pagination metadata.
      Returns:
      a CrossEntityResultWithPagination containing the first page

    • executeAll

      public @NonNull List<CrossEntityResult> executeAll()
      Executes the query and returns all results from all pages.
      Returns:
      a list of CrossEntityResult, one per page

    • executeAndGetFirst

      public @NonNull Optional<CrossEntityResult> executeAndGetFirst()
      Executes the query and returns the first matching item for each entity type, if any.
      Returns:
      an Optional containing the first page, or empty if no items match

    • count

      public long count()
      Returns the total number of matching items by iterating all query result pages using Select.COUNT server-side to avoid transferring item data.
      Returns:
      the total count of matching items