Java (AWS SDK v2) での DynamoDB PutItem

PutItem はアイテム全体を書き込み、新規作成するか、同じプライマリキーを持つ既存アイテムを置き換えます。AWS SDK for Java 2.x では、item マップに型付き AttributeValue（文字列には .s(...)、数値には .n(...)）としてすべての属性を持つ PutItemRequest を構築します。

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 — テーブルの完全なプライマリキーと、その他の任意の属性を含める必要があります。数値は N 型の下では文字列です（AttributeValue.builder().n("1994")）。
Put は置き換える — 条件がなければ、PutItem は同じキーを持つ既存アイテムを黙って上書きします。残りを壊さずに一部の属性だけ変更するには UpdateItem を使いましょう。
conditionExpression — キー属性に対する attribute_not_exists(...) により、書き込みは作成のみの挿入になります。アイテムが既に存在する場合、書き込みは ConditionalCheckFailedException で失敗します。これは DynamoDB の楽観的ロックのプリミティブです。#cond0/#cond1 エイリアスは expressionAttributeNames を介して Artist/SongTitle に解決されます（予約語に安全）。
ConditionalCheckFailedException は DynamoDbException を継承します — 上記の内側の try で最初にキャッチし、失敗した条件を他のサービスエラーとは別に処理します。
上書きされたアイテムを取得するには、.returnValues(ReturnValue.ALL_OLD) を追加します。
素の Java オブジェクトがほしいですか？DynamoDB Enhanced Client（software.amazon.awssdk.enhanced.dynamodb）は、AttributeValue のマップの代わりにアノテーション付き Bean クラスを書き込みます。

Do it visually

条件付きの put を手作業で書いていますか？DynamoDB Expression Builder が ConditionExpression を組み立て、コードをコピーします。

GUI でアイテムを追加・編集するには（属性ごとのフォーム、型ピッカー、コードとしてコピー）、DynoTable をダウンロードしてください。

DynamoDB PutItem in Go — AWS SDK for Go v2 による同じ条件付き書き込み。
DynamoDB UpdateItem in Java — アイテムを置き換える代わりに特定の属性を変更する。
DynamoDB condition expressions — attribute_not_exists、楽観的ロックなど。
DynamoDB ConditionalCheckFailedException — アイテムが既に存在するときに作成のみ条件が投げるもの。
DynamoDB ValidationException — 不正なアイテムや式に対する包括的なエラー。

References

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。

Java (AWS SDK v2) での DynamoDB PutItem

Code

Explanation

Do it visually

Related examples

References