DynamoDBMapper and Java Enhanced Client Cheat Sheet

DynamoDBMapper maps Java objects to DynamoDB items in AWS SDK for Java 1.x, which reached end of support on December 31, 2025. For current applications, use the AWS SDK for Java 2.x DynamoDB Enhanced Client: annotate a bean, create a TableSchema, and call methods on a DynamoDbTable. The examples below cover the same CRUD, query, scan and batch operations, followed by transactions, optimistic locking and a legacy Mapper reference.

DynamoDBMapper to Enhanced Client mapping

The Enhanced Client is AWS's successor to DynamoDBMapper. Migration changes imports, annotations, request builders and some persistence behavior; replacing the dependency alone is insufficient.

Keep existing attribute names and key types during migration. Table names move out of bean annotations and into client configuration. Review the AWS mapping API comparison before translating custom converters or save behaviors.

Cheat-sheet contents

• Setup
• Create a model class
• Connection
• Create a table
• Put an item
• Get an item
• Update an item
• Batch put items
• Batch put and delete
• Batch get items
• Scan with a filter
• Parallel scan
• Query
• Delete an item
• Batch delete items
• Transactions
• Optimistic locking
• Delete a table
• DynamoDB Local
• Legacy DynamoDBMapper

Setup

These examples use Java 17 or later and AWS SDK for Java 2.x. Java 17 is the example baseline, not the minimum for every SDK 2.x release. Use the SDK BOM to align module versions. For a Gradle project, the dependency block is:

dependencies {
    implementation platform('software.amazon.awssdk:bom:2.57.3')
    implementation 'software.amazon.awssdk:dynamodb'
    implementation 'software.amazon.awssdk:dynamodb-enhanced'
    implementation 'software.amazon.awssdk:sso'
    implementation 'software.amazon.awssdk:ssooidc'
}
dependencies {
    implementation platform('software.amazon.awssdk:bom:2.57.3')
    implementation 'software.amazon.awssdk:dynamodb'
    implementation 'software.amazon.awssdk:dynamodb-enhanced'
    implementation 'software.amazon.awssdk:sso'
    implementation 'software.amazon.awssdk:ssooidc'
}

The SSO modules support IAM Identity Center profiles during local development. Configure a Region and credentials through an AWS profile or runtime IAM role. Grant the table operations your application needs; static access keys and an administrator policy are not prerequisites. Spring Boot is optional: the SDK works in an ordinary Java application.

Save the bean below as Product.java. The operation snippets are method-body excerpts: use the imports and ProductExamples scaffold in the connection section, and run each example separately against a disposable table. They are not an ordered script, because the deletion examples remove data used elsewhere.

Create a model class and table schema

The Product table has Number partition key ProductId and String sort key ProductName. Every item lookup needs both. Price and weight use BigDecimal; names in annotations preserve the stored attribute names independently of Java property casing.

import java.math.BigDecimal;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.*;

@DynamoDbBean
public class Product {
    private Integer productId;
    private String productName;
    private BigDecimal price;
    private BigDecimal weight;
    private Long version;

    public Product() {}

    @DynamoDbPartitionKey
    @DynamoDbAttribute("ProductId")
    public Integer getProductId() { return productId; }
    public void setProductId(Integer value) { productId = value; }

    @DynamoDbSortKey
    @DynamoDbAttribute("ProductName")
    public String getProductName() { return productName; }
    public void setProductName(String value) { productName = value; }

    @DynamoDbAttribute("Price")
    public BigDecimal getPrice() { return price; }
    public void setPrice(BigDecimal value) { price = value; }

    @DynamoDbAttribute("Weight")
    public BigDecimal getWeight() { return weight; }
    public void setWeight(BigDecimal value) { weight = value; }

    public Long getVersion() { return version; }
    public void setVersion(Long value) { version = value; }
}
import java.math.BigDecimal;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.*;

@DynamoDbBean
public class Product {
    private Integer productId;
    private String productName;
    private BigDecimal price;
    private BigDecimal weight;
    private Long version;

    public Product() {}

    @DynamoDbPartitionKey
    @DynamoDbAttribute("ProductId")
    public Integer getProductId() { return productId; }
    public void setProductId(Integer value) { productId = value; }

    @DynamoDbSortKey
    @DynamoDbAttribute("ProductName")
    public String getProductName() { return productName; }
    public void setProductName(String value) { productName = value; }

    @DynamoDbAttribute("Price")
    public BigDecimal getPrice() { return price; }
    public void setPrice(BigDecimal value) { price = value; }

    @DynamoDbAttribute("Weight")
    public BigDecimal getWeight() { return weight; }
    public void setWeight(BigDecimal value) { weight = value; }

    public Long getVersion() { return version; }
    public void setVersion(Long value) { version = value; }
}

The bean needs a public no-argument constructor and getters/setters. TableSchema.fromBean(Product.class) inspects its annotations. Reuse the schema instead of rebuilding it per request. The version property is initially ordinary data; the locking section shows the annotation that changes its behavior.

Do not use a String UUID generator on an Integer key. If an existing table has String ProductId values, change the Java property and the example key values to String rather than changing the existing table's schema.

Connect and map the table

Use these imports for the operation snippets. Add an operation inside main; add the batch helper shown later as another static method in this class.

import java.math.BigDecimal;
import java.util.*;
import java.util.concurrent.*;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.*;
import software.amazon.awssdk.enhanced.dynamodb.*;
import software.amazon.awssdk.enhanced.dynamodb.model.*;

public class ProductExamples {
    public static Product product(int id, String name, String price) {
        Product item = new Product();
        item.setProductId(id);
        item.setProductName(name);
        item.setPrice(new BigDecimal(price));
        return item;
    }

    public static void main(String[] args) throws Exception {
        try (DynamoDbClient client = DynamoDbClient.builder()
                .region(Region.US_EAST_1).build()) {
            DynamoDbEnhancedClient enhanced = DynamoDbEnhancedClient.builder()
                    .dynamoDbClient(client).build();
            TableSchema<Product> schema = TableSchema.fromBean(Product.class);
            DynamoDbTable<Product> table = enhanced.table("Product", schema);
            // Insert one operation snippet here.
        }
    }
}
import java.math.BigDecimal;
import java.util.*;
import java.util.concurrent.*;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.*;
import software.amazon.awssdk.enhanced.dynamodb.*;
import software.amazon.awssdk.enhanced.dynamodb.model.*;

public class ProductExamples {
    public static Product product(int id, String name, String price) {
        Product item = new Product();
        item.setProductId(id);
        item.setProductName(name);
        item.setPrice(new BigDecimal(price));
        return item;
    }

    public static void main(String[] args) throws Exception {
        try (DynamoDbClient client = DynamoDbClient.builder()
                .region(Region.US_EAST_1).build()) {
            DynamoDbEnhancedClient enhanced = DynamoDbEnhancedClient.builder()
                    .dynamoDbClient(client).build();
            TableSchema<Product> schema = TableSchema.fromBean(Product.class);
            DynamoDbTable<Product> table = enhanced.table("Product", schema);
            // Insert one operation snippet here.
        }
    }
}

Creating the mapped table handle does not create a remote table. Keep the low-level client open while iterating results because lazy pagination makes additional requests. In a server application, reuse clients and close them at application shutdown.

Create a table

The low-level client makes the exact key types and on-demand billing explicit. Attribute definitions contain only keys, not Price, Weight or version.

client.createTable(CreateTableRequest.builder()
        .tableName("Product")
        .billingMode(BillingMode.PAY_PER_REQUEST)
        .attributeDefinitions(
                AttributeDefinition.builder().attributeName("ProductId")
                        .attributeType(ScalarAttributeType.N).build(),
                AttributeDefinition.builder().attributeName("ProductName")
                        .attributeType(ScalarAttributeType.S).build())
        .keySchema(
                KeySchemaElement.builder().attributeName("ProductId")
                        .keyType(KeyType.HASH).build(),
                KeySchemaElement.builder().attributeName("ProductName")
                        .keyType(KeyType.RANGE).build())
        .build());
try (var waiter = client.waiter()) {
    waiter.waitUntilTableExists(r -> r.tableName("Product"))
            .matched().response().orElseThrow();
}
client.createTable(CreateTableRequest.builder()
        .tableName("Product")
        .billingMode(BillingMode.PAY_PER_REQUEST)
        .attributeDefinitions(
                AttributeDefinition.builder().attributeName("ProductId")
                        .attributeType(ScalarAttributeType.N).build(),
                AttributeDefinition.builder().attributeName("ProductName")
                        .attributeType(ScalarAttributeType.S).build())
        .keySchema(
                KeySchemaElement.builder().attributeName("ProductId")
                        .keyType(KeyType.HASH).build(),
                KeySchemaElement.builder().attributeName("ProductName")
                        .keyType(KeyType.RANGE).build())
        .build());
try (var waiter = client.waiter()) {
    waiter.waitUntilTableExists(r -> r.tableName("Product"))
            .matched().response().orElseThrow();
}

Wait for the table to become active before writing. A table with only a partition key can also be queried, but this example intentionally has a sort key so multiple items can share a ProductId.

Put an item

Put replaces an entire existing item. Use a condition for a create-only write so an accidental duplicate cannot erase attributes omitted from your bean.

Product item = product(1, "Product 01", "50.50");
item.setWeight(new BigDecimal("80.0"));
Expression absent = Expression.builder()
        .expression("attribute_not_exists(#id)")
        .putExpressionName("#id", "ProductId").build();
table.putItem(PutItemEnhancedRequest.builder(Product.class)
        .item(item).conditionExpression(absent).build());
Product item = product(1, "Product 01", "50.50");
item.setWeight(new BigDecimal("80.0"));
Expression absent = Expression.builder()
        .expression("attribute_not_exists(#id)")
        .putExpressionName("#id", "ProductId").build();
table.putItem(PutItemEnhancedRequest.builder(Product.class)
        .item(item).conditionExpression(absent).build());

This condition applies to the full key, including ProductName. It does not require the entire partition to be empty. Catch ConditionalCheckFailedException if the same key already exists.

Get an item

A Get requires both key attributes. It returns null when the item does not exist. A strongly consistent base-table read observes completed writes in that Region.

Key key = Key.builder().partitionValue(1).sortValue("Product 01").build();
Product item = table.getItem(GetItemEnhancedRequest.builder()
        .key(key).consistentRead(true).build());
if (item != null) {
    System.out.println(item.getPrice());
}
Key key = Key.builder().partitionValue(1).sortValue("Product 01").build();
Product item = table.getItem(GetItemEnhancedRequest.builder()
        .key(key).consistentRead(true).build());
if (item != null) {
    System.out.println(item.getPrice());
}

Get does not search by price or fetch every item sharing the partition key. Use Query for the latter and design a secondary index for other access patterns.

Update an item and handle nulls

Enhanced Client updateItem removes mapped attributes whose bean properties are null by default. For a patch to scalar fields, use IgnoreNullsMode.SCALAR_ONLY and an existence condition. This preserves the stored weight when the patch does not set it.

Product patch = product(1, "Product 01", "85.00");
Expression exists = Expression.builder()
        .expression("attribute_exists(#id)")
        .putExpressionName("#id", "ProductId").build();
Product updated = table.updateItem(UpdateItemEnhancedRequest.builder(Product.class)
        .item(patch)
        .ignoreNullsMode(IgnoreNullsMode.SCALAR_ONLY)
        .conditionExpression(exists)
        .build());
System.out.println(updated.getPrice());
Product patch = product(1, "Product 01", "85.00");
Expression exists = Expression.builder()
        .expression("attribute_exists(#id)")
        .putExpressionName("#id", "ProductId").build();
Product updated = table.updateItem(UpdateItemEnhancedRequest.builder(Product.class)
        .item(patch)
        .ignoreNullsMode(IgnoreNullsMode.SCALAR_ONLY)
        .conditionExpression(exists)
        .build());
System.out.println(updated.getPrice());

Alternatively, get the item first, check for null, change its price and weight, then call updateItem. That read-modify-write sequence needs optimistic locking to detect concurrent changes. Do not assume a type-safe bean makes concurrent writes safe. For raw update expressions, see the SDK 2.x update example.

Batch put items with bounded retries

A batch writes at most 25 puts/deletes and a 16 MB request. It does not update selected attributes, support conditions or execute atomically. Use this helper for the unversioned Product bean above; retry only unfinished operations and retain them if retries run out.

Add this exception type and method to ProductExamples, outside main. The exception exposes pending work so the caller can save it for a later retry:

public static class BatchIncompleteException extends RuntimeException {
    public final List<Product> pendingPuts;
    public final List<Key> pendingDeletes;

    public BatchIncompleteException(List<Product> puts, List<Key> deletes) {
        super("Batch write remains incomplete");
        pendingPuts = List.copyOf(puts);
        pendingDeletes = List.copyOf(deletes);
    }
}

public static void writeBatchWithRetry(
        DynamoDbEnhancedClient enhanced, DynamoDbTable<Product> table,
        List<Product> puts, List<Key> deletes) throws InterruptedException {
    List<Product> pendingPuts = new ArrayList<>(puts);
    List<Key> pendingDeletes = new ArrayList<>(deletes);
    if (pendingPuts.size() + pendingDeletes.size() > 25) {
        throw new IllegalArgumentException("Split input into batches of at most 25");
    }
    for (int attempt = 0; !pendingPuts.isEmpty() || !pendingDeletes.isEmpty(); attempt++) {
        if (attempt == 8) {
            throw new BatchIncompleteException(pendingPuts, pendingDeletes);
        }
        if (attempt > 0) {
            Thread.sleep(ThreadLocalRandom.current()
                    .nextLong(Math.min(5000L, 100L << attempt)));
        }
        WriteBatch.Builder<Product> batch = WriteBatch.builder(Product.class)
                .mappedTableResource(table);
        pendingPuts.forEach(batch::addPutItem);
        pendingDeletes.forEach(batch::addDeleteItem);
        BatchWriteResult result = enhanced.batchWriteItem(
                BatchWriteItemEnhancedRequest.builder().writeBatches(batch.build()).build());
        pendingPuts = result.unprocessedPutItemsForTable(table);
        pendingDeletes = result.unprocessedDeleteItemsForTable(table);
    }
}
public static class BatchIncompleteException extends RuntimeException {
    public final List<Product> pendingPuts;
    public final List<Key> pendingDeletes;

    public BatchIncompleteException(List<Product> puts, List<Key> deletes) {
        super("Batch write remains incomplete");
        pendingPuts = List.copyOf(puts);
        pendingDeletes = List.copyOf(deletes);
    }
}

public static void writeBatchWithRetry(
        DynamoDbEnhancedClient enhanced, DynamoDbTable<Product> table,
        List<Product> puts, List<Key> deletes) throws InterruptedException {
    List<Product> pendingPuts = new ArrayList<>(puts);
    List<Key> pendingDeletes = new ArrayList<>(deletes);
    if (pendingPuts.size() + pendingDeletes.size() > 25) {
        throw new IllegalArgumentException("Split input into batches of at most 25");
    }
    for (int attempt = 0; !pendingPuts.isEmpty() || !pendingDeletes.isEmpty(); attempt++) {
        if (attempt == 8) {
            throw new BatchIncompleteException(pendingPuts, pendingDeletes);
        }
        if (attempt > 0) {
            Thread.sleep(ThreadLocalRandom.current()
                    .nextLong(Math.min(5000L, 100L << attempt)));
        }
        WriteBatch.Builder<Product> batch = WriteBatch.builder(Product.class)
                .mappedTableResource(table);
        pendingPuts.forEach(batch::addPutItem);
        pendingDeletes.forEach(batch::addDeleteItem);
        BatchWriteResult result = enhanced.batchWriteItem(
                BatchWriteItemEnhancedRequest.builder().writeBatches(batch.build()).build());
        pendingPuts = result.unprocessedPutItemsForTable(table);
        pendingDeletes = result.unprocessedDeleteItemsForTable(table);
    }
}

Call it with distinct complete keys. Each put replaces any existing item at its key:

writeBatchWithRetry(enhanced, table, List.of(
        product(2, "Product 02", "50.00"),
        product(3, "Product 03", "60.00")
), List.of());
writeBatchWithRetry(enhanced, table, List.of(
        product(2, "Product 02", "50.00"),
        product(3, "Product 03", "60.00")
), List.of());

Check item and wire sizes when constructing real batches; the operation count alone does not guarantee they fit. Batches are unsuitable for writes that require version or state conditions. See the Enhanced Client batch API.

Batch put and delete

Puts and deletes can share one batch, provided they target different items. This keeps the same schema and retry helper rather than introducing undefined purchase or category models.

writeBatchWithRetry(enhanced, table,
        List.of(product(4, "Product 04", "67.00")),
        List.of(Key.builder().partitionValue(2).sortValue("Product 02").build()));
writeBatchWithRetry(enhanced, table,
        List.of(product(4, "Product 04", "67.00")),
        List.of(Key.builder().partitionValue(2).sortValue("Product 02").build()));

To target multiple tables, add a WriteBatch for each mapped table to the same request and retain each table's unprocessed results. The 25-operation limit applies across the entire request, not separately to each table.

Batch get items

BatchGet reads known keys, up to 100 items and 16 MB per service response. Iterate the Enhanced Client's result iterable: it requests further pages and retries unprocessed keys. Results can be unordered, and nonexistent items are omitted.

ReadBatch<Product> batch = ReadBatch.builder(Product.class)
        .mappedTableResource(table)
        .addGetItem(Key.builder().partitionValue(2).sortValue("Product 02").build())
        .addGetItem(Key.builder().partitionValue(3).sortValue("Product 03").build())
        .build();
enhanced.batchGetItem(BatchGetItemEnhancedRequest.builder()
        .readBatches(batch).build())
        .resultsForTable(table)
        .forEach(item -> System.out.println(item.getProductName()));
ReadBatch<Product> batch = ReadBatch.builder(Product.class)
        .mappedTableResource(table)
        .addGetItem(Key.builder().partitionValue(2).sortValue("Product 02").build())
        .addGetItem(Key.builder().partitionValue(3).sortValue("Product 03").build())
        .build();
enhanced.batchGetItem(BatchGetItemEnhancedRequest.builder()
        .readBatches(batch).build())
        .resultsForTable(table)
        .forEach(item -> System.out.println(item.getProductName()));

Keep keys unique and split inputs above the request limit. If you need strongly consistent reads, set consistentRead(true) on every GetItemEnhancedRequest for that table. BatchGet is not an atomic read transaction.

Scan with a filter

The items() iterable walks all pages without collecting the table into memory. A filter is applied after DynamoDB reads each page, so it does not lower read capacity. Unlike a Query filter, a Scan filter may refer to key attributes.

Expression filter = Expression.builder()
        .expression("begins_with(#name, :prefix)")
        .putExpressionName("#name", "ProductName")
        .putExpressionValue(":prefix", AttributeValue.builder().s("Product").build())
        .build();
table.scan(ScanEnhancedRequest.builder().filterExpression(filter).build())
        .items().forEach(item -> System.out.println(item.getProductName()));
Expression filter = Expression.builder()
        .expression("begins_with(#name, :prefix)")
        .putExpressionName("#name", "ProductName")
        .putExpressionValue(":prefix", AttributeValue.builder().s("Product").build())
        .build();
table.scan(ScanEnhancedRequest.builder().filterExpression(filter).build())
        .items().forEach(item -> System.out.println(item.getProductName()));

Each service response evaluates up to 1 MB before filtering. An empty page can still have a continuation key. Lazy iteration handles that, but scans are not snapshots and can see concurrent changes.

Parallel scan

Use a separate worker for each segment. Every worker must keep its segment number and total segment count while reading all pages. Parallelism can shorten elapsed time while consuming capacity faster; it does not make a full scan cheaper.

int segments = 3;
ExecutorService workers = Executors.newFixedThreadPool(segments);
List<Future<?>> jobs = new ArrayList<>();
try {
    for (int segment = 0; segment < segments; segment++) {
        final int currentSegment = segment;
        jobs.add(workers.submit(() -> {
            ScanEnhancedRequest request = ScanEnhancedRequest.builder()
                    .segment(currentSegment).totalSegments(segments).build();
            table.scan(request).items().forEach(item ->
                    System.out.println(item.getProductName()));
        }));
    }
    for (Future<?> job : jobs) {
        job.get();
    }
} finally {
    workers.shutdownNow();
    if (!workers.awaitTermination(1, TimeUnit.MINUTES)) {
        throw new IllegalStateException("Scan workers have not stopped");
    }
}
int segments = 3;
ExecutorService workers = Executors.newFixedThreadPool(segments);
List<Future<?>> jobs = new ArrayList<>();
try {
    for (int segment = 0; segment < segments; segment++) {
        final int currentSegment = segment;
        jobs.add(workers.submit(() -> {
            ScanEnhancedRequest request = ScanEnhancedRequest.builder()
                    .segment(currentSegment).totalSegments(segments).build();
            table.scan(request).items().forEach(item ->
                    System.out.println(item.getProductName()));
        }));
    }
    for (Future<?> job : jobs) {
        job.get();
    }
} finally {
    workers.shutdownNow();
    if (!workers.awaitTermination(1, TimeUnit.MINUTES)) {
        throw new IllegalStateException("Scan workers have not stopped");
    }
}

The example waits for worker results so exceptions are not silently lost. Production jobs should checkpoint each segment separately and set request timeouts. DynamoDB Local does not reproduce parallel scan segmentation, so test that behavior against AWS.

Query a partition and paginate results

Query requires partition-key equality. A sort key is optional in DynamoDB generally; when present, it supports additional predicates and orders the results. Here, query every item whose ProductId is 1, in descending ProductName order.

QueryConditional condition = QueryConditional.keyEqualTo(
        Key.builder().partitionValue(1).build());
QueryEnhancedRequest request = QueryEnhancedRequest.builder()
        .queryConditional(condition)
        .scanIndexForward(false)
        .limit(100)
        .build();
for (Page<Product> page : table.query(request)) {
    for (Product item : page.items()) {
        System.out.println(item.getProductName());
    }
}
QueryConditional condition = QueryConditional.keyEqualTo(
        Key.builder().partitionValue(1).build());
QueryEnhancedRequest request = QueryEnhancedRequest.builder()
        .queryConditional(condition)
        .scanIndexForward(false)
        .limit(100)
        .build();
for (Page<Product> page : table.query(request)) {
    for (Product item : page.items()) {
        System.out.println(item.getProductName());
    }
}

limit(100) limits evaluated items per request, not the total number of results from the iterable. To narrow the sort key, use a condition such as QueryConditional.sortBeginsWith(Key.builder().partitionValue(1).sortValue("Product").build()). Non-key filters run after the key condition and do not reduce the data read.

For an index query, map its key properties with @DynamoDbSecondaryPartitionKey and @DynamoDbSecondarySortKey, obtain table.index("IndexName"), and query using its keys. GSIs provide eventually consistent reads only. The Java index example shows the equivalent low-level SDK 2.x request.

Delete one item

Delete takes the full key and returns the previous item, or null if none existed. A plain key-based deletion does not need a preliminary read.

Product removed = table.deleteItem(
        Key.builder().partitionValue(1).sortValue("Product 01").build());
if (removed != null) {
    System.out.println(removed.getProductName());
}
Product removed = table.deleteItem(
        Key.builder().partitionValue(1).sortValue("Product 01").build());
if (removed != null) {
    System.out.println(removed.getProductName());
}

If deletion depends on an expected version or state, use DeleteItemEnhancedRequest with an explicit condition. Merely passing a bean with a version property does not add that condition automatically.

Batch delete items

Reuse the bounded batch helper with no puts. There is no need to load complete records when the full keys are already known.

writeBatchWithRetry(enhanced, table, List.of(), List.of(
        Key.builder().partitionValue(2).sortValue("Product 02").build(),
        Key.builder().partitionValue(3).sortValue("Product 03").build()
));
writeBatchWithRetry(enhanced, table, List.of(), List.of(
        Key.builder().partitionValue(2).sortValue("Product 02").build(),
        Key.builder().partitionValue(3).sortValue("Product 03").build()
));

Use individual conditional deletes or a transaction if a version must still match. For table-wide cleanup, delete all items with Java scans keys and handles pagination and batch retries.

Write and read transactions

Transactions coordinate changes atomically across up to 100 distinct items and 4 MB in one account and Region. They cannot target the same item twice or operate on MRSC global tables. This writes two new products with create-only conditions.

Expression absent = Expression.builder()
        .expression("attribute_not_exists(#id)")
        .putExpressionName("#id", "ProductId").build();
TransactWriteItemsEnhancedRequest request = TransactWriteItemsEnhancedRequest.builder()
        .clientRequestToken("product-pair-10-11-v1")
        .addPutItem(table, TransactPutItemEnhancedRequest.builder(Product.class)
                .item(product(10, "Product 10", "10.00"))
                .conditionExpression(absent).build())
        .addPutItem(table, TransactPutItemEnhancedRequest.builder(Product.class)
                .item(product(11, "Product 11", "11.00"))
                .conditionExpression(absent).build())
        .build();
enhanced.transactWriteItems(request);
Expression absent = Expression.builder()
        .expression("attribute_not_exists(#id)")
        .putExpressionName("#id", "ProductId").build();
TransactWriteItemsEnhancedRequest request = TransactWriteItemsEnhancedRequest.builder()
        .clientRequestToken("product-pair-10-11-v1")
        .addPutItem(table, TransactPutItemEnhancedRequest.builder(Product.class)
                .item(product(10, "Product 10", "10.00"))
                .conditionExpression(absent).build())
        .addPutItem(table, TransactPutItemEnhancedRequest.builder(Product.class)
                .item(product(11, "Product 11", "11.00"))
                .conditionExpression(absent).build())
        .build();
enhanced.transactWriteItems(request);

Use one unique token per logical transaction and reuse the identical payload and token for retries within the 10-minute idempotency window. Catch TransactionCanceledException and inspect cancellationReasons(); a failed condition is not fixed by blindly retrying.

Read both items atomically with transactGetItems. Result documents preserve request order, and getItem(table) returns null for a missing item:

List<Document> results = enhanced.transactGetItems(
        TransactGetItemsEnhancedRequest.builder()
                .addGetItem(table, Key.builder().partitionValue(10).sortValue("Product 10").build())
                .addGetItem(table, Key.builder().partitionValue(11).sortValue("Product 11").build())
                .build());
for (Document document : results) {
    Product item = document.getItem(table);
    System.out.println(item == null ? "Missing" : item.getProductName());
}
List<Document> results = enhanced.transactGetItems(
        TransactGetItemsEnhancedRequest.builder()
                .addGetItem(table, Key.builder().partitionValue(10).sortValue("Product 10").build())
                .addGetItem(table, Key.builder().partitionValue(11).sortValue("Product 11").build())
                .build());
for (Document document : results) {
    Product item = document.getItem(table);
    System.out.println(item == null ? "Missing" : item.getProductName());
}

The Enhanced Client transaction guide covers combining puts, updates, deletes and condition checks.

Optimistic locking with DynamoDbVersionAttribute

For records updated concurrently, replace the existing getVersion() method in Product with this annotated version. Add the import at the top of Product.java; keep the existing field and setter. This is a model change, so recreate the schema/client after recompiling.

import software.amazon.awssdk.enhanced.dynamodb.extensions.annotations.DynamoDbVersionAttribute;

@DynamoDbVersionAttribute
public Long getVersion() { return version; }
import software.amazon.awssdk.enhanced.dynamodb.extensions.annotations.DynamoDbVersionAttribute;

@DynamoDbVersionAttribute
public Long getVersion() { return version; }

VersionedRecordExtension is loaded by default. It initializes a new version at 0 and increments it on successful writes, adding a version condition. Explicitly configuring your own extension list replaces the defaults, so include VersionedRecordExtension there when needed.

Read the item, modify it and keep the returned updated object for subsequent writes:

Key key = Key.builder().partitionValue(1).sortValue("Product 01").build();
Product current = table.getItem(r -> r.key(key).consistentRead(true));
if (current == null) {
    throw new IllegalStateException("Product not found");
}
current.setPrice(new BigDecimal("85.00"));
try {
    Product saved = table.updateItem(current);
    System.out.println(saved.getVersion());
} catch (ConditionalCheckFailedException conflict) {
    // Reload and decide whether the user's change can be reapplied.
    throw conflict;
}
Key key = Key.builder().partitionValue(1).sortValue("Product 01").build();
Product current = table.getItem(r -> r.key(key).consistentRead(true));
if (current == null) {
    throw new IllegalStateException("Product not found");
}
current.setPrice(new BigDecimal("85.00"));
try {
    Product saved = table.updateItem(current);
    System.out.println(saved.getVersion());
} catch (ConditionalCheckFailedException conflict) {
    // Reload and decide whether the user's change can be reapplied.
    throw conflict;
}

The earlier scalar patch example must now carry the version read from the item. A null version means a new, unversioned item to the extension, not permission to overwrite an existing version. Avoid batch writes for version-controlled records because BatchWriteItem cannot enforce per-item conditions.

Version annotations do not protect deletes. Read the version and add the condition yourself:

Key key = Key.builder().partitionValue(1).sortValue("Product 01").build();
Product current = table.getItem(r -> r.key(key).consistentRead(true));
if (current == null || current.getVersion() == null) {
    throw new IllegalStateException("Versioned product not found");
}
Expression versionMatches = Expression.builder()
        .expression("#version = :expected")
        .putExpressionName("#version", "version")
        .putExpressionValue(":expected", AttributeValue.builder()
                .n(current.getVersion().toString()).build())
        .build();
table.deleteItem(DeleteItemEnhancedRequest.builder()
        .key(key).conditionExpression(versionMatches).build());
Key key = Key.builder().partitionValue(1).sortValue("Product 01").build();
Product current = table.getItem(r -> r.key(key).consistentRead(true));
if (current == null || current.getVersion() == null) {
    throw new IllegalStateException("Versioned product not found");
}
Expression versionMatches = Expression.builder()
        .expression("#version = :expected")
        .putExpressionName("#version", "version")
        .putExpressionValue(":expected", AttributeValue.builder()
                .n(current.getVersion().toString()).build())
        .build();
table.deleteItem(DeleteItemEnhancedRequest.builder()
        .key(key).conditionExpression(versionMatches).build());

Multi-Region eventual consistency global tables use last-writer-wins reconciliation, so a local version condition is not a cross-Region lock. The extension reference describes which operations apply version checks.

Delete a table

This deletes the table and all its data. Run it only after the disposable examples are finished. Deletion protection must be disabled.

A successful not-exists waiter is matched by a ResourceNotFoundException, not a DescribeTable response. Check the matched exception when confirming deletion:

table.deleteTable();
try (var waiter = client.waiter()) {
    var result = waiter.waitUntilTableNotExists(r -> r.tableName("Product"));
    if (!(result.matched().exception().orElse(null) instanceof ResourceNotFoundException)) {
        throw new IllegalStateException("Table deletion was not confirmed");
    }
}
table.deleteTable();
try (var waiter = client.waiter()) {
    var result = waiter.waitUntilTableNotExists(r -> r.tableName("Product"));
    if (!(result.matched().exception().orElse(null) instanceof ResourceNotFoundException)) {
        throw new IllegalStateException("Table deletion was not confirmed");
    }
}

Run DynamoDB Local

Use the current DynamoDB Local 3.x image. Running the downloaded JAR directly requires JRE 17 or later; the Docker image supplies its runtime. This disposable example stores data only in memory.

docker run --rm -p 127.0.0.1:8000:8000 amazon/dynamodb-local:3.3.2 \
  -jar DynamoDBLocal.jar -inMemory -sharedDb
docker run --rm -p 127.0.0.1:8000:8000 amazon/dynamodb-local:3.3.2 \
  -jar DynamoDBLocal.jar -inMemory -sharedDb

In the connection scaffold, replace the client construction with this local configuration. Keep the rest of the Enhanced Client setup the same, and create the table at this endpoint first.

DynamoDbClient client = DynamoDbClient.builder()
        .region(Region.US_EAST_1)
        .endpointOverride(java.net.URI.create("http://localhost:8000"))
        .credentialsProvider(software.amazon.awssdk.auth.credentials.StaticCredentialsProvider.create(
                software.amazon.awssdk.auth.credentials.AwsBasicCredentials.create("local", "local")))
        .build();
DynamoDbClient client = DynamoDbClient.builder()
        .region(Region.US_EAST_1)
        .endpointOverride(java.net.URI.create("http://localhost:8000"))
        .credentialsProvider(software.amazon.awssdk.auth.credentials.StaticCredentialsProvider.create(
                software.amazon.awssdk.auth.credentials.AwsBasicCredentials.create("local", "local")))
        .build();

Dummy credentials are for Local only. Local does not model real throughput throttling or every cloud feature. The local development guide covers persistent storage and other clients.

DynamoDBMapper for existing SDK 1.x code

Keep this section only as a migration reference. The legacy package is com.amazonaws:aws-java-sdk-dynamodb; it is not part of SDK 2.x. A correctly mapped composite-key bean uses @DynamoDBHashKey and @DynamoDBRangeKey, and load needs both values.

import com.amazonaws.services.dynamodbv2.datamodeling.*;

@DynamoDBTable(tableName = "Product")
public class LegacyProduct {
    private Integer productId;
    private String productName;

    public LegacyProduct() {}

    @DynamoDBHashKey(attributeName = "ProductId")
    public Integer getProductId() { return productId; }
    public void setProductId(Integer value) { productId = value; }

    @DynamoDBRangeKey(attributeName = "ProductName")
    public String getProductName() { return productName; }
    public void setProductName(String value) { productName = value; }
}
import com.amazonaws.services.dynamodbv2.datamodeling.*;

@DynamoDBTable(tableName = "Product")
public class LegacyProduct {
    private Integer productId;
    private String productName;

    public LegacyProduct() {}

    @DynamoDBHashKey(attributeName = "ProductId")
    public Integer getProductId() { return productId; }
    public void setProductId(Integer value) { productId = value; }

    @DynamoDBRangeKey(attributeName = "ProductName")
    public String getProductName() { return productName; }
    public void setProductName(String value) { productName = value; }
}

In an existing 1.x project, read it using the default credentials chain:

import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBMapper;

public class LegacyRead {
    public static void main(String[] args) {
        AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard()
                .withRegion("us-east-1").build();
        try {
            DynamoDBMapper mapper = new DynamoDBMapper(client);
            LegacyProduct item = mapper.load(LegacyProduct.class, 1, "Product 01");
            System.out.println(item == null ? "Missing" : item.getProductName());
        } finally {
            client.shutdown();
        }
    }
}
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBMapper;

public class LegacyRead {
    public static void main(String[] args) {
        AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard()
                .withRegion("us-east-1").build();
        try {
            DynamoDBMapper mapper = new DynamoDBMapper(client);
            LegacyProduct item = mapper.load(LegacyProduct.class, 1, "Product 01");
            System.out.println(item == null ? "Missing" : item.getProductName());
        } finally {
            client.shutdown();
        }
    }
}

Legacy save behavior depends on DynamoDBMapperConfig.SaveBehavior, so translate the intended overwrite, patch and null-handling behavior explicitly. Map all attributes needed by your application before writing; the small legacy bean here is read-only. Existing batch methods also require checking their returned failures. The Mapper method reference remains useful while migrating.

Frequently asked questions