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로 해석됩니다(예약어 안전).
  • ConditionalCheckFailedExceptionDynamoDbException을 확장함 — (위의 안쪽 try에서) 먼저 잡아 실패한 조건을 다른 서비스 오류와 분리해 처리하세요.
  • 덮어쓴 항목을 되돌려 받으려면 .returnValues(ReturnValue.ALL_OLD)를 추가하세요.
  • 평범한 Java 객체를 선호하시나요? DynamoDB Enhanced Client(software.amazon.awssdk.enhanced.dynamodb)는 AttributeValue 맵 대신 어노테이션이 붙은 빈 클래스를 씁니다.

Do it visually

조건부 put을 손으로 작성하고 계신가요? DynamoDB Expression BuilderConditionExpression을 조립하고 코드를 복사해 줍니다.

GUI에서 항목을 추가하고 편집하려면 — 속성별 폼, 타입 선택기, 코드로 복사 — DynoTable을 다운로드하세요.

References

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

Console 없이 DynamoDB 작업하기

DynoTable은 DynamoDB를 위한 빠른 데스크톱 클라이언트입니다 — 테이블을 탐색하고, SQL 스타일 쿼리를 실행하고, 항목을 로컬에서 편집하세요.