DynamoDB PutItem di Java (AWS SDK v2)

PutItem menulis seluruh item, membuatnya atau menggantikan item apa pun yang sudah ada dengan primary key yang sama. Di AWS SDK for Java 2.x Anda membangun PutItemRequest yang map item-nya menyimpan setiap atribut sebagai typed AttributeValue (.s(...) untuk string, .n(...) untuk angka).

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

Penjelasan

item — harus berisi primary key lengkap tabel, ditambah atribut lain apa pun. Angka berupa string di bawah tipe N (AttributeValue.builder().n("1994")).
Put menggantikan — tanpa kondisi, PutItem menimpa secara diam-diam item yang sudah ada dengan key yang sama. Gunakan UpdateItem untuk mengubah beberapa atribut tanpa menghancurkan sisanya.
conditionExpression — attribute_not_exists(...) pada atribut key membuat penulisan menjadi insert create-only; penulisan gagal dengan ConditionalCheckFailedException jika item sudah ada. Ini adalah primitif optimistic-locking DynamoDB. Alias #cond0/#cond1 di-resolve ke Artist/SongTitle via expressionAttributeNames (aman terhadap reserved word).
ConditionalCheckFailedException extends DynamoDbException — tangkap ia lebih dulu (blok try bagian dalam di atas) sehingga kondisi yang gagal ditangani terpisah dari error service lain.
Untuk mendapatkan kembali item yang tertimpa, tambahkan .returnValues(ReturnValue.ALL_OLD).
Lebih suka objek Java biasa? DynamoDB Enhanced Client (software.amazon.awssdk.enhanced.dynamodb) menulis kelas bean beranotasi alih-alih map AttributeValue.

Lakukan secara visual

Menulis put bersyarat dengan tangan? DynamoDB Expression Builder menyusun ConditionExpression dan menyalin kodenya.

Untuk menambah dan mengedit item di GUI — form per atribut, pemilih tipe, dan copy-as-code — unduh DynoTable.

Contoh terkait

DynamoDB PutItem di Go — penulisan bersyarat yang sama dengan AWS SDK for Go v2.
DynamoDB UpdateItem di Java — ubah atribut tertentu alih-alih menggantikan item.
DynamoDB condition expressions — attribute_not_exists, optimistic locking, dan lainnya.
DynamoDB ConditionalCheckFailedException — apa yang dilempar kondisi create-only ketika item sudah ada.
DynamoDB ValidationException — catch-all untuk item atau expression yang tidak valid.

References

Terakhir diverifikasi 2026-07-13 terhadap dokumentasi resmi AWS yang ditautkan di atas.