Class ScanBuilder<T>

java.lang.Object
dev.hogwai.dynamodb.simplified.builder.base.AbstractScanBuilder<T, ScanBuilder<T>>
dev.hogwai.dynamodb.simplified.builder.ScanBuilder<T>
Type Parameters:
T - the type of the item
public class ScanBuilder<T> extends AbstractScanBuilder<T, ScanBuilder<T>>
A fluent builder for scanning a DynamoDB table with optional filter, projection, parallel scan segments, and pagination. Part of the DynamoDB Simplified library.

  • Constructor Details

    • ScanBuilder

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

    • ScanBuilder

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

    • ScanBuilder

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

    • ScanBuilder

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

  • Method Details

    • self

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

    • tableName

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

    • indexName

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

    • executeAll

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

      Warning: This method loads all results into memory. For large result sets, consider using executeStream() for lazy streaming or paginate manually with executeWithPagination().

      Returns:
      a list of matching items

    • executeAndGetFirst

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

    • executeStream

      public @NonNull Stream<T> executeStream()
      Executes the scan and returns a lazy Stream of all matching items. The stream is backed by the paginated scan results, so items are fetched on demand as the stream is consumed.
      Returns:
      a stream of matching items

    • executeWithPagination

      public @NonNull PagedResult<T> executeWithPagination()
      Executes the scan 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)

    • count

      public long count()
      Returns the total number of items by iterating all scan 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 scanned items matching the filter