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맵 대신 어노테이션이 붙은 빈 클래스를 씁니다.
Do it visually
조건부 put을 손으로 작성하고 계신가요? DynamoDB Expression Builder는 ConditionExpression을 조립하고 코드를 복사해 줍니다.
GUI에서 항목을 추가하고 편집하려면 — 속성별 폼, 타입 선택기, 코드로 복사 — DynoTable을 다운로드하세요.
Related examples
- DynamoDB PutItem in Go — AWS SDK for Go v2를 사용한 동일한 조건부 쓰기.
- DynamoDB UpdateItem in Java — 항목을 교체하는 대신 특정 속성을 변경하기.
- DynamoDB condition expressions —
attribute_not_exists, 낙관적 잠금 등. - DynamoDB ConditionalCheckFailedException — 항목이 이미 존재할 때 생성 전용 조건이 발생시키는 것.
- DynamoDB ValidationException — 잘못된 형식의 항목이나 표현식을 위한 포괄 오류.
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
Last verified 2026-07-13 against the official AWS documentation linked above.