Tindakan Berbasis Item DynamoDB

API DynamoDB dibagi menjadi tiga kelompok: tindakan berbasis item yang bekerja pada satu item berdasarkan kunci utamanya, Kueri yang membaca rentang dalam satu partisi, dan Pindai yang membaca semuanya. Panduan ini adalah keluarga pertama — empat operasi yang paling sering Anda gunakan: GetItem, PutItem, UpdateItem, DeleteItem. Itu yang termurah, panggilan tercepat yang ditawarkan DynamoDB, dan membedakannya dengan benar (terutama Put vs Update) mencegah serangkaian bug kehilangan data yang tidak disengaja.

Apa saja operasi berbasis item DynamoDB?

Operasi berbasis item DynamoDB adalah empat panggilan yang bertindak pada satu item dengan kunci utama lengkapnya: GetItem membacanya, PutItem membuat atau menggantinya sepenuhnya, UpdateItem memodifikasi atribut tertentu di tempatnya, dan DeleteItem menghapusnya. Masing-masing alamat tepat satu item, menjadikannya panggilan tercepat dan termurah — tidak seperti Kueri dan Pemindaian, yang membaca banyak item.

GetItem — membaca satu item dengan kunci utama lengkapnya.
PutItem — membuat atau mengganti sepenuhnya satu item.
UpdateItem — membuat atau memodifikasi atribut tertentu dari satu item di tempatnya.
DeleteItem — menghapus satu item dengan kunci utama lengkapnya.
Keempatnya memerlukan kunci utama yang lengkap (kunci partisi, ditambah kunci pengurutan jika tabel punya satu) — mereka membahas tepat satu item.
PutItem menimpa seluruh item; UpdateItem bersifat bedah — membingungkan mereka bagaimana atribut menghilang secara diam-diam.

Ciri yang menentukan: satu item, kunci lengkap

Setiap tindakan berbasis item menargetkan satu item berdasarkan kunci utama lengkapnya. Itu apa yang membuatnya cepat dan murah — DynamoDB melakukan hash pada kunci partisi, langsung menuju ke barang, selesai. Tanpa pemfilteran, tanpa pemindaian. Jika Anda tidak mengetahui kunci lengkapnya, ini bukan kuncinya alat yang tepat; itulah gunanya Kueri dan Pemindaian.

Katakanlah Anda menjalankan akun pengguna yang dikunci oleh USER#<id>:

PK: USER#204   email, displayName, plan, createdAt

GetItem di USER#204 → pengguna itu, secara langsung.
DeleteItem di USER#204 → menghapus pengguna itu.

Keduanya membutuhkan kunci yang tepat. Tanpa kunci, tanpa tindakan berbasis item.

`PutItem` vs `UpdateItem` — yang menggigit

Inilah perbedaan yang patut diinternalisasikan:

PutItem menulis keseluruhan item. Jika USER#204 sudah ada dan Anda PutItem hanya dengan {email, displayName}, atribut plan dan createdAt yang ada hilang — put menggantikan keseluruhan item, namun tidak digabungkan.
UpdateItem hanya mengubah nama Anda. UpdateItem dengan a SET email = … meninggalkan setiap atribut lainnya tidak tersentuh, dan membuat item jika tidak ada (upsert).

Aturan praktisnya: jangkau UpdateItem untuk mengubah item yang ada, dan gunakan PutItem hanya jika Anda benar-benar bermaksud "tulis item ini sebagai status baru yang lengkap". Keduanya PutItem dan UpdateItem menerima a ekspresi kondisi sehingga Anda dapat menulis bersyarat ("hanya jika belum ada").

Tindakan berbasis item di DynoTable

Ingin panggilan API mentah di balik tindakan ini? Kumpulkan ekspresi dan nilai yang diketik memetakan di pembuat ekspresi DynamoDB, dan mengonversi item JSON biasa menjadi format yang diketik API dengan Konverter DynamoDB JSON.

Di DynoTable, pekerjaan yang sama bersifat visual: membuka item di grid untuk membacanya (a GetItem), edit atribut dan komit (UpdateItem), tambahkan atau ganti baris (a PutItem), atau hapus satu — satu item dalam satu waktu.

<gambar kelas="doc-media-placeholder" jenis data="tangkapan layar" data-src="docs/guide-dynamodb-item-based-actions-grid.png"

Membaca satu item di Tampilan Cepat DynoTable, dengan tindakan Edit Item dan Salin sebagai JSON.

Jebakan + langkah selanjutnya

PutItem menggantikan seluruh item — untuk mengubah beberapa bidang tanpa kehilangan selebihnya, gunakan UpdateItem.
Anda harus mengetahui kunci utama selengkapnya — tidak ada kunci yang berarti Kueri/Pemindaian, bukan tindakan item.
Banyak item sekaligus? Jangan ulangi satu per satu — operasi batch lipat menjadi lebih sedikit perjalanan bolak-balik.
Perlu nilai lama/baru kembali? Tetapkan ReturnValues alih-alih GetItem tindak lanjut.
Terkait: query vs scan mencakup sisi read-many.

Ingin membaca, menulis, dan menghapus item tanpa menulis sebaris kode API? Unduh DynoTable dan kerjakan tabel Anda secara langsung.

Biaya: satu item, satu lompatan

Pembacaan berbasis item adalah akses beralamat termurah di DynamoDB. GetItem aktif baris 2 KB menggunakan 1 RCU yang akhirnya konsisten (satu blok 4 KB, dibulatkan ke atas). Query yang mengembalikan baris yang sama karena Anda mengetahui kunci partisi dan kunci sortir memerlukan kapasitas yang sama — tetapi jika Anda hanya mengetahui kunci partisi dan filter dalam kode aplikasi, Anda membayar untuk setiap item di partisi.

Operasi	Kunci diperlukan	Penggunaan yang umum	Bentuk kapasitas
`GetItem`	Kunci utama penuh	Poin dibaca berdasarkan id	1 blok per item
`PutItem`	Kunci utama penuh	Membuat atau mengganti seluruh item	1 WCU per KB, dibulatkan
`UpdateItem`	Kunci utama penuh	Atribut tambalan	Tagihan untuk ukuran barang ditulis
`DeleteItem`	Kunci utama penuh	Hapus baris	Sama seperti menulis pada ukuran barang
`Query` + penyaring	Partisi (+ kondisi pengurutan opsional)	Banyak item dalam satu partisi	Jumlah item yang cocok

Tempelkan item representatif ke dalam kalkulator ukuran barang, lalu kalikan dengan permintaan per detik di kalkulator harga ketika jalur panas digunakan GetItem dalam satu lingkaran versus satu Query yang dikunci dengan baik.

Ekspresi kondisi pada penulisan

Baik PutItem dan UpdateItem menerima opsional ekspresi kondisi. Pola khas:

attribute_not_exists(pk) on put — penyisipan khusus buat tanpa balapan.
attribute_exists(pk) saat diperbarui — menolak membuat stub secara tidak sengaja.
plan = :old sedang diperbarui — konkurensi optimis; coba lagi jika penulis lain mengubah rencananya terlebih dahulu.

DeleteItem juga mendukung ketentuan — hapus hanya jika status = :closed, misalnya contoh. Ketentuan tidak menambahkan biaya baca terpisah; DynamoDB mengevaluasinya terhadap item yang disimpan selama upaya menulis.

Bangun kondisi secara visual di Pembuat ekspresi DynamoDB; salin ConditionExpression ditambah ExpressionAttributeNames dan ExpressionAttributeValues ke dalam panggilan SDK Anda.

Idempotensi dan timpa keamanan

PutItem tanpa syarat adalah kemenangan penulis terakhir di seluruh item. Untuk webhook penangan atau konsumen SQS, pasangkan dengan attribute_not_exists pada pemrosesan atribut penanda, atau gunakan UpdateItem dengan SET processed = :true dijaga oleh attribute_not_exists(processed).

Saat Anda memerlukan nilai atribut sebelumnya untuk log audit, tambahkan ReturnValues pada UpdateItem yang sama dari GetItem sebelumnya — satu perjalanan pulang pergi, tidak ada lomba baca/tulis.

Memilih tindakan item yang tepat

Maksud	Panggilan	Penjaga
Baca profil berdasarkan id pengguna	`GetItem`	—
Buat pengguna jika tidak ada	`PutItem`	`attribute_not_exists(pk)`
Ubah email, simpan kolom lainnya	`UpdateItem`	opsional `email <> :old`
Ganti seluruh gumpalan konfigurasi	`PutItem`	hanya ketika payload selesai
Hapus tiket tertutup	`DeleteItem`	`status = :closed`
Baca 50 tiket dengan kunci yang diketahui	`BatchGetItem`	bukan 50× `GetItem` dalam serial

Pementasan menulis dalam DynoTable

DynoTable menampilkan UpdateItem dan PutItem secara lokal sebelum dilakukan. Anda meninjau perbedaan atribut, jalankan pemeriksaan PartiQL opsional, lalu komit — yang memetakan ke panggilan API nyata di atas. Baris massal menghapus kumpulan ke dalam BatchWriteItem di bawah tenda dengan coba lagi pada item yang belum diproses.

Untuk pembuatan kode SDK, rakit klausa pembaruan di pembuat ekspresi dan tempelkan yang dipancarkan Cuplikan SDK v3 di samping pengujian pengendali Anda.