Class QueryBuilder<T>

java.lang.Object
dev.hogwai.dynamodb.simplified.builder.base.AbstractQueryBuilder<T, QueryBuilder<T>>
dev.hogwai.dynamodb.simplified.builder.QueryBuilder<T>
Type Parameters:
T - the type of the item
public class QueryBuilder<T> extends AbstractQueryBuilder<T, QueryBuilder<T>>
A fluent builder for querying items in a DynamoDB table or index. Supports key conditions, filters, projections, sorting, pagination, and global secondary index usage. Part of the DynamoDB Simplified library.

  • Constructor Details

    • QueryBuilder

      public QueryBuilder(@NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable<T> table)
      Constructs a new QueryBuilder for the given table.
      Parameters:
      table - the DynamoDB table

    • QueryBuilder

      public QueryBuilder(@NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbIndex<T> index)
      Constructs a new QueryBuilder for querying the given secondary index.
      Parameters:
      index - the DynamoDB secondary index

    • QueryBuilder

      public QueryBuilder(@NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable<T> table, @Nullable software.amazon.awssdk.services.dynamodb.DynamoDbClient dynamoDbClient)
      Constructs a new QueryBuilder for the given table with a low-level client.
      Parameters:
      table - the DynamoDB table
      dynamoDbClient - the low-level DynamoDB client (nullable)

    • QueryBuilder

      public QueryBuilder(@NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbIndex<T> index, @Nullable software.amazon.awssdk.services.dynamodb.DynamoDbClient dynamoDbClient)
      Constructs a new QueryBuilder for querying the given secondary index with a low-level client.
      Parameters:
      index - the DynamoDB secondary index
      dynamoDbClient - the low-level DynamoDB client (nullable)

  • Method Details

    • self

      protected @NonNull QueryBuilder<T> self()
      Description copied from class: AbstractQueryBuilder
      Returns this typed as S for fluent chaining.
      Specified by:
      self in class AbstractQueryBuilder<T, QueryBuilder<T>>
      Returns:
      this builder

    • tableName

      protected @NonNull String tableName()
      Description copied from class: AbstractQueryBuilder
      Returns the DynamoDB table name.
      Specified by:
      tableName in class AbstractQueryBuilder<T, QueryBuilder<T>>
      Returns:
      the DynamoDB table name

    • indexName

      protected @Nullable String indexName()
      Description copied from class: AbstractQueryBuilder
      Returns the DynamoDB index name, or null if the query targets the base table.
      Specified by:
      indexName in class AbstractQueryBuilder<T, QueryBuilder<T>>
      Returns:
      the index name, or null for the base table

    • primaryPartitionKey

      protected @NonNull String primaryPartitionKey()
      Description copied from class: AbstractQueryBuilder
      Returns the primary partition key attribute name for the targeted table or index.
      Specified by:
      primaryPartitionKey in class AbstractQueryBuilder<T, QueryBuilder<T>>
      Returns:
      the primary partition key attribute name

    • primarySortKey

      protected @NonNull Optional<String> primarySortKey()
      Description copied from class: AbstractQueryBuilder
      Returns the primary sort key attribute name for the targeted table or index, or empty if the table/index has no sort key.
      Specified by:
      primarySortKey in class AbstractQueryBuilder<T, QueryBuilder<T>>
      Returns:
      the primary sort key attribute name, or empty if none

    • executeAll

      public @NonNull List<T> executeAll()
      Executes the query and returns all matching items aggregated from all pages.

      Memory warning: all results are loaded into memory. For large result sets, consider using executeStream() for lazy iteration or executeWithPagination() for page-by-page processing.

      Returns:
      a list of matching items

    • executeStream

      public @NonNull Stream<T> executeStream()
      Executes the query and returns a lazy stream of all matching items.

      The stream lazily fetches pages as needed, making it suitable for large result sets.

      Returns:
      a stream of matching items

    • executeWithPagination

      public @NonNull PagedResult<T> executeWithPagination()
      Executes the query and returns only the first page of results along with the last evaluated key for pagination.
      Returns:
      a PagedResult containing the first page of items and the last evaluated key (may be null if no more pages)

    • executeAndGetFirst

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

    • count

      public long count()
      Returns the total number of matching items by iterating all query result pages.

      When a low-level DynamoDbClient is available, uses Select.COUNT server-side to avoid transferring item data. Falls back to the enhanced client page iteration otherwise.

      Returns:
      the total count of matching items