Java（AWS SDK v2）中的 DynamoDB PutItem

PutItem 写入一个完整项目，创建它，或替换任何具有相同主键的现有项目。在 AWS SDK for Java 2.x 中，你构建一个 PutItemRequest，其 item 映射把每个属性都存为带类型的 AttributeValue（字符串用 .s(...)，数字用 .n(...)）。

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

说明

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）会写入带注解的 bean 类而非 AttributeValue 映射。

可视化操作

手工写一次条件 put？DynamoDB Expression Builder 会组装 ConditionExpression 并复制代码。

想在 GUI 中添加和编辑项目——每个属性一个表单、类型选择器、复制为代码——请下载 DynoTable。

References

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

Java（AWS SDK v2）中的 DynamoDB PutItem

Code

说明

可视化操作

相关示例

References