Class AsyncQueryBuilder<T>

java.lang.Object
dev.hogwai.dynamodb.simplified.builder.base.AbstractQueryBuilder<T, AsyncQueryBuilder<T>>
dev.hogwai.dynamodb.simplified.async.AsyncQueryBuilder<T>
Type Parameters:
T - the type of the item
public class AsyncQueryBuilder<T> extends AbstractQueryBuilder<T, AsyncQueryBuilder<T>>
A fluent async builder for querying items in a DynamoDB table.

Mirrors the sync QueryBuilder but returns CompletableFuture from all execution methods and uses the AWS SDK's async PagePublisher under the hood.

Key conditions, filters, projections, sort order, pagination, and consistent read settings are all supported. For index-specific queries, use AsyncIndex instead.

  • Constructor Details

    • AsyncQueryBuilder

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

    • AsyncQueryBuilder

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

    • AsyncQueryBuilder

      public AsyncQueryBuilder(@NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable<T> table, @Nullable software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient dynamoDbAsyncClient)
      Constructs a new AsyncQueryBuilder for the given async table with a low-level client.
      Parameters:
      table - the async DynamoDB table
      dynamoDbAsyncClient - the low-level async DynamoDB client (nullable)

    • AsyncQueryBuilder

      public AsyncQueryBuilder(@NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncIndex<T> index, @Nullable software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient dynamoDbAsyncClient)
      Constructs a new AsyncQueryBuilder for querying the given async secondary index with a low-level client.
      Parameters:
      index - the async DynamoDB secondary index
      dynamoDbAsyncClient - the low-level async DynamoDB client (nullable)

  • Method Details

    • self

      protected @NonNull AsyncQueryBuilder<T> self()
      Description copied from class: AbstractQueryBuilder
      Returns this typed as S for fluent chaining.
      Specified by:
      self in class AbstractQueryBuilder<T, AsyncQueryBuilder<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, AsyncQueryBuilder<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, AsyncQueryBuilder<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, AsyncQueryBuilder<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, AsyncQueryBuilder<T>>
      Returns:
      the primary sort key attribute name, or empty if none

    • executeAll

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

      Memory warning: This method eagerly loads all matching items into memory. If the result set may be large, consider using paginated methods such as executeWithPagination() to process items incrementally.

      Returns:
      a CompletableFuture containing a list of matching items

    • executeWithPagination

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

    • executeAndGetFirst

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

    • streamResults

      public @NonNull software.amazon.awssdk.core.async.SdkPublisher<T> streamResults()
      Returns a reactive publisher that streams query results lazily.
      Returns:
      an SdkPublisher that emits query items
      Throws:
      IllegalStateException - if called with Select.COUNT

    • count

      public @NonNull CompletableFuture<Long> count()
      Returns the total number of matching items asynchronously by iterating all query result pages.

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

      Returns:
      a CompletableFuture containing the total count of matching items