DynamoDB PutItem in Java (AWS SDK v2)

PutItem schreibt ein ganzes Item und erstellt es oder ersetzt jedes bestehende Item mit demselben Primärschlüssel. Im AWS SDK for Java 2.x baust du einen PutItemRequest, dessen item-Map jedes Attribut als typisierten AttributeValue hält (.s(...) für Strings, .n(...) für Zahlen).

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());
        }
    }
}

Erklärung

• item — muss den vollständigen Primärschlüssel der Tabelle enthalten, plus alle weiteren Attribute. Zahlen sind Strings unter dem N-Typ (AttributeValue.builder().n("1994")).
• Put ersetzt — ohne Bedingung überschreibt PutItem stillschweigend ein bestehendes Item mit demselben Schlüssel. Nutze UpdateItem, um einige Attribute zu ändern, ohne den Rest zu überschreiben.
• conditionExpression — attribute_not_exists(...) auf den Schlüsselattributen macht den Write zu einem nur-erstellenden Insert; der Write schlägt mit ConditionalCheckFailedException fehl, wenn das Item bereits existiert. Das ist DynamoDBs Primitiv für optimistisches Locking. Die Aliase #cond0/#cond1 lösen per expressionAttributeNames zu Artist/SongTitle auf (reservierte-Wort-sicher).
• ConditionalCheckFailedException erweitert DynamoDbException — fange sie zuerst (der innere try oben), sodass die fehlgeschlagene Bedingung getrennt von anderen Service-Fehlern behandelt wird.
• Um das überschriebene Item zurückzubekommen, füge .returnValues(ReturnValue.ALL_OLD) hinzu.
• Lieber schlichte Java-Objekte? Der DynamoDB Enhanced Client (software.amazon.awssdk.enhanced.dynamodb) schreibt annotierte Bean-Klassen statt AttributeValue-Maps.

Visuell erledigen

Einen bedingten Put von Hand schreiben? Der DynamoDB Expression Builder stellt die ConditionExpression zusammen und kopiert den Code.

Um Items in einer GUI hinzuzufügen und zu bearbeiten — ein Formular pro Attribut, Typ-Auswahl und Copy-as-Code — lade DynoTable herunter.

Verwandte Beispiele

• DynamoDB PutItem in Go — derselbe bedingte Write mit AWS SDK for Go v2.
• DynamoDB UpdateItem in Java — bestimmte Attribute ändern, statt das Item zu ersetzen.
• DynamoDB-Bedingungsausdrücke — attribute_not_exists, optimistisches Locking und mehr.
• DynamoDB ConditionalCheckFailedException — was die nur-erstellende Bedingung wirft, wenn das Item bereits existiert.
• DynamoDB ValidationException — der Sammelfehler für ein fehlerhaftes Item oder eine fehlerhafte Expression.

References

• PutItem — Amazon DynamoDB API Reference
• Use PutItem with an AWS SDK or CLI — Amazon DynamoDB Developer Guide
• DynamoDbClient — AWS SDK for Java 2.x API Reference
• PutItemRequest — AWS SDK for Java 2.x API Reference
• Condition expressions — Amazon DynamoDB Developer Guide

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.