DynamoDB PutItem in Java (AWS SDK v2)

PutItem writes a whole item, creating it or replacing any existing item with the same primary key. In AWS SDK for Java 2.x you build a PutItemRequest whose item map holds every attribute as a typed AttributeValue (.s(...) for strings, .n(...) for numbers).

Code

import java.util.HashMap;
import java.util.Map;

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.ConditionalCheckFailedException;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.PutItemRequest;

public class PutItemExample {
    public static void main(String[] args) {
        try (DynamoDbClient ddb = DynamoDbClient.builder()
                .region(Region.US_EAST_1)
                .build()) {

            Map<String, AttributeValue> item = new HashMap<>();
            item.put("Artist", AttributeValue.builder().s("Arturo Sandoval").build());
            item.put("SongTitle", AttributeValue.builder().s("Cubano Chant").build());
            item.put("AlbumTitle", AttributeValue.builder().s("Danzon").build());
            item.put("Year", AttributeValue.builder().n("1994").build());
            item.put("Awards", AttributeValue.builder().n("0").build());

            Map<String, String> names = new HashMap<>();
            names.put("#cond0", "Artist");
            names.put("#cond1", "SongTitle");

            PutItemRequest request = PutItemRequest.builder()
                    .tableName("Music")
                    .item(item)
                    .conditionExpression("attribute_not_exists(#cond0) AND attribute_not_exists(#cond1)")
                    .expressionAttributeNames(names)
                    .build();

            try {
                ddb.putItem(request);
                System.out.println("Song written");
            } catch (ConditionalCheckFailedException e) {
                System.out.println("A song with that key already exists — not overwritten");
            }
        } catch (DynamoDbException e) {
            System.err.println(e.getMessage());
        }
    }
}

Explanation

item — must contain the table's full primary key, plus any other attributes. Numbers are strings under the N type (AttributeValue.builder().n("1994")).
Put replaces — without a condition, PutItem silently overwrites an existing item with the same key. Use UpdateItem to change a few attributes without clobbering the rest.
conditionExpression — attribute_not_exists(...) on the key attributes makes the write a create-only insert; the write fails with ConditionalCheckFailedException if the item already exists. This is DynamoDB's optimistic-locking primitive. The #cond0/#cond1 aliases resolve to Artist/SongTitle via expressionAttributeNames (reserved-word-safe).
ConditionalCheckFailedException extends DynamoDbException — catch it first (the inner try above) so the failed condition is handled separately from other service errors.
To get the overwritten item back, add .returnValues(ReturnValue.ALL_OLD).
Prefer plain Java objects? The DynamoDB Enhanced Client (software.amazon.awssdk.enhanced.dynamodb) writes annotated bean classes instead of AttributeValue maps.

Do it visually

Writing a conditional put by hand? The DynamoDB Expression Builder assembles the ConditionExpression and copies the code.

To add and edit items in a GUI — a form per attribute, type pickers, and copy-as-code — download DynoTable.

DynamoDB PutItem in Go — the same conditional write with AWS SDK for Go v2.
DynamoDB UpdateItem in Java — change specific attributes instead of replacing the item.
DynamoDB condition expressions — attribute_not_exists, optimistic locking, and more.
DynamoDB ConditionalCheckFailedException — what the create-only condition throws when the item already exists.
DynamoDB ValidationException — the catch-all for a malformed item or expression.

References

Last verified 2026-07-13 against the official AWS documentation linked above.

DynamoDB PutItem in Java (AWS SDK v2)

Code

Explanation

Do it visually

Related examples

References