Class AbstractQueryBuilder<T, S extends AbstractQueryBuilder<T,S>>

java.lang.Object
dev.hogwai.dynamodb.simplified.builder.base.AbstractQueryBuilder<T,S>
Type Parameters:
T - the item type
S - the concrete builder type (for fluent chaining)
Direct Known Subclasses:
AsyncQueryBuilder, QueryBuilder
public abstract class AbstractQueryBuilder<T, S extends AbstractQueryBuilder<T,S>> extends Object
Abstract base for sync and async query builders.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected static enum 
    AbstractQueryBuilder.KeyConditionOp
    Describes the type of sort key comparison for a key condition expression.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Boolean
    consistentRead
    Whether to use strongly consistent reads (false by default).
    protected Map<String, software.amazon.awssdk.services.dynamodb.model.AttributeValue>
    exclusiveStartKey
    Exclusive start key for paginated queries.
    protected FilterExpression
    filterExpression
    Optional filter expression applied after the query.
    protected software.amazon.awssdk.enhanced.dynamodb.model.QueryConditional
    keyCondition
    The key condition for the query.
    protected AbstractQueryBuilder.KeyConditionOp
    keyOp
    The key condition operator for low-level count operations.
    protected Integer
    limit
    Maximum number of items to evaluate per page.
    protected static final org.slf4j.Logger
    LOG
    Logger for this builder class.
    protected @Nullable Object
    pkValue
    The partition key value.
    protected ProjectionExpression
    projectionExpression
    Optional projection expression to restrict returned attributes.
    protected software.amazon.awssdk.services.dynamodb.model.ReturnConsumedCapacity
    returnConsumedCapacity
    Optional consumed capacity reporting level.
    protected Boolean
    scanIndexForward
    Whether to scan in forward (ascending) order (true by default).
    protected software.amazon.awssdk.services.dynamodb.model.Select
    select
    Optional select parameter controlling which attributes are returned.
    protected @Nullable Object
    skValue
    The sort key value (first bound for BETWEEN).
    protected @Nullable Object
    skValue2
    The second sort key bound (for BETWEEN only).

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    AbstractQueryBuilder()
    Constructs a new AbstractQueryBuilder.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected void
    applyFilterExpression(software.amazon.awssdk.services.dynamodb.model.QueryRequest.Builder requestBuilder, Map<String,String> keyNames, Map<String, software.amazon.awssdk.services.dynamodb.model.AttributeValue> keyValues)
    Applies the configured filter expression to a low-level QueryRequest.Builder.
    protected void
    applyQueryOptions(software.amazon.awssdk.services.dynamodb.model.QueryRequest.Builder requestBuilder)
    Applies the configured query options (limit, start key, consistent read, scan index forward, return consumed capacity) to a low-level QueryRequest.Builder.
    @NonNull S
    ascending()
    Sets the query to return results in ascending sort key order (the default).
    protected @NonNull software.amazon.awssdk.enhanced.dynamodb.model.QueryEnhancedRequest
    buildEnhancedRequest()
    Builds a high-level QueryEnhancedRequest from the configured parameters.
    protected @NonNull String
    buildKeyConditionExpression(Map<String,String> expressionNames, Map<String, software.amazon.awssdk.services.dynamodb.model.AttributeValue> expressionValues)
    Builds a DynamoDB key condition expression string for low-level count operations.
    @NonNull S
    consistentRead(boolean consistentRead)
    Enables or disables strongly consistent reads.
    @NonNull S
    descending()
    Sets the query to return results in descending sort key order.
    @NonNull S
    filter(@Nullable FilterExpression filter)
    Configures a post-query filter expression from a pre-built FilterExpression.
    @NonNull S
    filter(@NonNull Map<String,Object> conditions)
    Configures a query filter from a map of attribute-value pairs.
    @NonNull S
    filter(@NonNull Consumer<FilterExpression> filterBuilder)
    Configures a post-query filter expression using a FilterExpression consumer.
    protected abstract @Nullable String
    indexName()
    Returns the DynamoDB index name, or null if the query targets the base table.
    @NonNull S
    limit(int limit)
    Limits the number of items evaluated per page.
    protected static <K,V> Map<K,V>
    mergeMaps(Map<K,V> base, Map<K,V> override)
    Merges two maps, with the override map taking precedence.
    @NonNull S
    partitionKey(@NonNull Object pkValue)
    Sets the key condition to match all items with the given partition key value.
    @NonNull S
    partitionKeyAndSortKeyBeginsWith(@NonNull Object pkValue, @NonNull String skPrefix)
    Sets the key condition to match items whose sort key begins with the given prefix within the specified partition.
    @NonNull S
    partitionKeyAndSortKeyBetween(@NonNull Object pkValue, @NonNull Object skLow, @NonNull Object skHigh)
    Sets the key condition to match items whose sort key falls within the specified range (inclusive) within the given partition.
    @NonNull S
    partitionKeyAndSortKeyEquals(@NonNull Object pkValue, @NonNull Object skValue)
    Sets the key condition to match the item with the exact partition key and sort key values.
    @NonNull S
    partitionKeyAndSortKeyGreaterThan(@NonNull Object pkValue, @NonNull Object skValue)
    Sets the key condition to match items whose sort key is strictly greater than the given value within the specified partition.
    @NonNull S
    partitionKeyAndSortKeyGreaterThanOrEqual(@NonNull Object pkValue, @NonNull Object skValue)
    Sets the key condition to match items whose sort key is greater than or equal to the given value within the specified partition.
    @NonNull S
    partitionKeyAndSortKeyLessThan(@NonNull Object pkValue, @NonNull Object skValue)
    Sets the key condition to match items whose sort key is strictly less than the given value within the specified partition.
    @NonNull S
    partitionKeyAndSortKeyLessThanOrEqual(@NonNull Object pkValue, @NonNull Object skValue)
    Sets the key condition to match items whose sort key is less than or equal to the given value within the specified partition.
    protected abstract @NonNull String
    primaryPartitionKey()
    Returns the primary partition key attribute name for the targeted table or index.
    protected abstract @NonNull Optional<String>
    primarySortKey()
    Returns the primary sort key attribute name for the targeted table or index, or empty if the table/index has no sort key.
    @NonNull S
    project(@NonNull String... attributes)
    Restricts the returned attributes to the specified ones.
    @NonNull S
    project(@NonNull Consumer<ProjectionExpression> projectionBuilder)
    Restricts the returned attributes by configuring a ProjectionExpression via a consumer.
    protected void
    requirePartitionKey()
    Validates that the partition key has been set.
    @NonNull S
    returnConsumedCapacity(@NonNull software.amazon.awssdk.services.dynamodb.model.ReturnConsumedCapacity returnConsumedCapacity)
    Sets the return consumed capacity option for the query.
    @NonNull S
    select(@Nullable software.amazon.awssdk.services.dynamodb.model.Select select)
    Sets the select parameter for the query, controlling which attributes are returned.
    protected abstract S
    self()
    Returns this typed as S for fluent chaining.
    @NonNull S
    startFrom(@Nullable Map<String, software.amazon.awssdk.services.dynamodb.model.AttributeValue> lastEvaluatedKey)
    Sets the exclusive start key for paginated queries.
    protected abstract @NonNull String
    tableName()
    Returns the DynamoDB table name.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • LOG

      protected static final org.slf4j.Logger LOG
      Logger for this builder class.

    • keyCondition

      protected software.amazon.awssdk.enhanced.dynamodb.model.QueryConditional keyCondition
      The key condition for the query.

    • filterExpression

      protected FilterExpression filterExpression
      Optional filter expression applied after the query.

    • projectionExpression

      protected ProjectionExpression projectionExpression
      Optional projection expression to restrict returned attributes.

    • scanIndexForward

      protected Boolean scanIndexForward
      Whether to scan in forward (ascending) order (true by default).

    • limit

      protected Integer limit
      Maximum number of items to evaluate per page.

    • exclusiveStartKey

      protected Map<String, software.amazon.awssdk.services.dynamodb.model.AttributeValue> exclusiveStartKey
      Exclusive start key for paginated queries.

    • consistentRead

      protected Boolean consistentRead
      Whether to use strongly consistent reads (false by default).

    • returnConsumedCapacity

      protected software.amazon.awssdk.services.dynamodb.model.ReturnConsumedCapacity returnConsumedCapacity
      Optional consumed capacity reporting level.

    • select

      protected software.amazon.awssdk.services.dynamodb.model.Select select
      Optional select parameter controlling which attributes are returned.

    • keyOp

      protected AbstractQueryBuilder.KeyConditionOp keyOp
      The key condition operator for low-level count operations.

    • pkValue

      protected @Nullable Object pkValue
      The partition key value.

    • skValue

      protected @Nullable Object skValue
      The sort key value (first bound for BETWEEN).

    • skValue2

      protected @Nullable Object skValue2
      The second sort key bound (for BETWEEN only).

  • Constructor Details

    • AbstractQueryBuilder

      protected AbstractQueryBuilder()
      Constructs a new AbstractQueryBuilder.

  • Method Details

    • self

      protected abstract S self()
      Returns this typed as S for fluent chaining.
      Returns:
      this builder

    • tableName

      protected abstract @NonNull String tableName()
      Returns the DynamoDB table name.
      Returns:
      the DynamoDB table name

    • indexName

      protected abstract @Nullable String indexName()
      Returns the DynamoDB index name, or null if the query targets the base table.
      Returns:
      the index name, or null for the base table

    • primaryPartitionKey

      protected abstract @NonNull String primaryPartitionKey()
      Returns the primary partition key attribute name for the targeted table or index.
      Returns:
      the primary partition key attribute name

    • primarySortKey

      protected abstract @NonNull Optional<String> primarySortKey()
      Returns the primary sort key attribute name for the targeted table or index, or empty if the table/index has no sort key.
      Returns:
      the primary sort key attribute name, or empty if none

    • partitionKey

      public @NonNull S partitionKey(@NonNull Object pkValue)
      Sets the key condition to match all items with the given partition key value.
      Parameters:
      pkValue - the partition key value
      Returns:
      this builder for chaining

    • partitionKeyAndSortKeyEquals

      public @NonNull S partitionKeyAndSortKeyEquals(@NonNull Object pkValue, @NonNull Object skValue)
      Sets the key condition to match the item with the exact partition key and sort key values.
      Parameters:
      pkValue - the partition key value
      skValue - the sort key value
      Returns:
      this builder for chaining

    • partitionKeyAndSortKeyBeginsWith

      public @NonNull S partitionKeyAndSortKeyBeginsWith(@NonNull Object pkValue, @NonNull String skPrefix)
      Sets the key condition to match items whose sort key begins with the given prefix within the specified partition.
      Parameters:
      pkValue - the partition key value
      skPrefix - the sort key prefix string
      Returns:
      this builder for chaining

    • partitionKeyAndSortKeyBetween

      public @NonNull S partitionKeyAndSortKeyBetween(@NonNull Object pkValue, @NonNull Object skLow, @NonNull Object skHigh)
      Sets the key condition to match items whose sort key falls within the specified range (inclusive) within the given partition.
      Parameters:
      pkValue - the partition key value
      skLow - the lower bound of the sort key range (inclusive)
      skHigh - the upper bound of the sort key range (inclusive)
      Returns:
      this builder for chaining

    • partitionKeyAndSortKeyGreaterThan

      public @NonNull S partitionKeyAndSortKeyGreaterThan(@NonNull Object pkValue, @NonNull Object skValue)
      Sets the key condition to match items whose sort key is strictly greater than the given value within the specified partition.
      Parameters:
      pkValue - the partition key value
      skValue - the sort key threshold (exclusive)
      Returns:
      this builder for chaining

    • partitionKeyAndSortKeyGreaterThanOrEqual

      public @NonNull S partitionKeyAndSortKeyGreaterThanOrEqual(@NonNull Object pkValue, @NonNull Object skValue)
      Sets the key condition to match items whose sort key is greater than or equal to the given value within the specified partition.
      Parameters:
      pkValue - the partition key value
      skValue - the sort key threshold (inclusive)
      Returns:
      this builder for chaining

    • partitionKeyAndSortKeyLessThan

      public @NonNull S partitionKeyAndSortKeyLessThan(@NonNull Object pkValue, @NonNull Object skValue)
      Sets the key condition to match items whose sort key is strictly less than the given value within the specified partition.
      Parameters:
      pkValue - the partition key value
      skValue - the sort key threshold (exclusive)
      Returns:
      this builder for chaining

    • partitionKeyAndSortKeyLessThanOrEqual

      public @NonNull S partitionKeyAndSortKeyLessThanOrEqual(@NonNull Object pkValue, @NonNull Object skValue)
      Sets the key condition to match items whose sort key is less than or equal to the given value within the specified partition.
      Parameters:
      pkValue - the partition key value
      skValue - the sort key threshold (inclusive)
      Returns:
      this builder for chaining

    • filter

      public @NonNull S filter(@NonNull Consumer<FilterExpression> filterBuilder)
      Configures a post-query filter expression using a FilterExpression consumer.
      Parameters:
      filterBuilder - a consumer that configures the FilterExpression
      Returns:
      this builder for chaining

    • filter

      public @NonNull S filter(@Nullable FilterExpression filter)
      Configures a post-query filter expression from a pre-built FilterExpression.
      Parameters:
      filter - the filter expression
      Returns:
      this builder for chaining

    • filter

      public @NonNull S filter(@NonNull Map<String,Object> conditions)
      Configures a query filter from a map of attribute-value pairs.

      All conditions are combined with AND. Each entry is treated as an equality filter. For other condition types, use the consumer-based filter(Consumer) method.

      Parameters:
      conditions - a map of attribute names to their expected values
      Returns:
      this builder for chaining

    • project

      public @NonNull S 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

    • project

      public @NonNull S project(@NonNull Consumer<ProjectionExpression> projectionBuilder)
      Restricts the returned attributes by configuring a ProjectionExpression via a consumer.
      Parameters:
      projectionBuilder - a consumer that configures the ProjectionExpression
      Returns:
      this builder for chaining

    • descending

      public @NonNull S descending()
      Sets the query to return results in descending sort key order.
      Returns:
      this builder for chaining

    • ascending

      public @NonNull S ascending()
      Sets the query to return results in ascending sort key order (the default).
      Returns:
      this builder for chaining

    • limit

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

    • startFrom

      public @NonNull S startFrom(@Nullable Map<String, software.amazon.awssdk.services.dynamodb.model.AttributeValue> lastEvaluatedKey)
      Sets the exclusive start key for paginated queries. Typically obtained from the last evaluated key of a previous query.
      Parameters:
      lastEvaluatedKey - the key map from which to start the next page
      Returns:
      this builder for chaining

    • consistentRead

      public @NonNull S 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

    • returnConsumedCapacity

      public @NonNull S returnConsumedCapacity(@NonNull software.amazon.awssdk.services.dynamodb.model.ReturnConsumedCapacity returnConsumedCapacity)
      Sets the return consumed capacity option for the query.
      Parameters:
      returnConsumedCapacity - the return consumed capacity value
      Returns:
      this builder for chaining

    • select

      public @NonNull S select(@Nullable software.amazon.awssdk.services.dynamodb.model.Select select)
      Sets the select parameter for the query, controlling which attributes are returned. Use Select.COUNT to request only the item count from the server.
      Parameters:
      select - the select parameter (nullable)
      Returns:
      this builder for chaining

    • buildEnhancedRequest

      protected @NonNull software.amazon.awssdk.enhanced.dynamodb.model.QueryEnhancedRequest buildEnhancedRequest()
      Builds a high-level QueryEnhancedRequest from the configured parameters.
      Returns:
      the built enhanced request

    • requirePartitionKey

      protected void requirePartitionKey()
      Validates that the partition key has been set.
      Throws:
      IllegalStateException - if pkValue is null

    • buildKeyConditionExpression

      protected @NonNull String buildKeyConditionExpression(Map<String,String> expressionNames, Map<String, software.amazon.awssdk.services.dynamodb.model.AttributeValue> expressionValues)
      Builds a DynamoDB key condition expression string for low-level count operations.
      Parameters:
      expressionNames - the map to populate with expression attribute names
      expressionValues - the map to populate with expression attribute values
      Returns:
      the key condition expression string

    • applyFilterExpression

      protected void applyFilterExpression(software.amazon.awssdk.services.dynamodb.model.QueryRequest.Builder requestBuilder, Map<String,String> keyNames, Map<String, software.amazon.awssdk.services.dynamodb.model.AttributeValue> keyValues)
      Applies the configured filter expression to a low-level QueryRequest.Builder.
      Parameters:
      requestBuilder - the query request builder to configure
      keyNames - the expression attribute names from the key condition
      keyValues - the expression attribute values from the key condition

    • applyQueryOptions

      protected void applyQueryOptions(software.amazon.awssdk.services.dynamodb.model.QueryRequest.Builder requestBuilder)
      Applies the configured query options (limit, start key, consistent read, scan index forward, return consumed capacity) to a low-level QueryRequest.Builder.
      Parameters:
      requestBuilder - the query request builder to configure

    • mergeMaps

      protected static <K,V> Map<K,V> mergeMaps(Map<K,V> base, Map<K,V> override)
      Merges two maps, with the override map taking precedence.
      Type Parameters:
      K - the map key type
      V - the map value type
      Parameters:
      base - the base map
      override - the override map (entries take precedence over base)
      Returns:
      a new map containing all entries from both maps