Bekerja dengan item dan atribut

Di Amazon DynamoDB, item adalah koleksi atribut. Setiap atribut mempunyai nama dan nilai. Nilai atribut dapat berupa skalar, himpunan, atau tipe dokumen. Untuk informasi selengkapnya, lihat Amazon DynamoDB: Cara kerjanya.

DynamoDB menyediakan empat operasi untuk fungsionalitas dasar buat, baca, perbarui, dan hapus (CRUD). Semua operasi ini bersifat atom.

• PutItem — Membuat item.

• GetItem — Membaca item

• UpdateItem — Memperbarui item

• DeleteItem — Menghapus item

Setiap operasi ini mengharuskan Anda menentukan kunci primer item yang ingin Anda gunakan. Misalnya, untuk membaca item menggunakan GetItem, Anda harus menentukan kunci partisi dan kunci urutan (jika ada) untuk item tersebut.

Selain empat operasi CRUD dasar, DynamoDB juga menyediakan hal berikut ini:

• BatchGetItem — Membaca hingga 100 item dari satu tabel atau lebih.

• BatchWriteItem — Membuat atau menghapus hingga 25 item dalam satu atau beberapa tabel.

Operasi batch ini menggabungkan beberapa operasi CRUD ke dalam satu permintaan. Selain itu, operasi batch membaca dan menulis item secara paralel untuk meminimalkan latensi respons.

Bagian ini menjelaskan cara menggunakan operasi ini dan mencakup topik terkait, seperti pembaruan bersyarat dan penghitung atom. Bagian ini juga mencakup contoh kode yang menggunakan AWS SDK.

Topik

• Membaca item
• Menulis item
• Nilai yang ditampilkan
• Operasi batch
• Penghitung atom
• Penulisan bersyarat
• Menggunakan ekspresi di DynamoDB
• Waktu untuk Hidup (TTL)
• Bekerja dengan item: Java
• Bekerja dengan item: .NET

Membaca item

Untuk membaca item dari tabel DynamoDB, gunakan operasi GetItem. Anda harus memberikan nama tabel, beserta kunci primer item yang Anda inginkan.

contoh

AWS CLI Contoh berikut menunjukkan cara membaca item dari ProductCatalog tabel.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}'

catatan

Dengan GetItem, Anda harus menentukan seluruh kunci primer, bukan hanya sebagian darinya. Misalnya, jika tabel memiliki kunci primer gabungan (kunci partisi dan kunci urutan), Anda harus menyediakan nilai untuk kunci partisi dan nilai untuk kunci urutan.

Pada akhirnya, permintaan GetItem melakukan pembacaan konsisten secara default. Sebagai gantinya, Anda dapat menggunakan parameter ConsistentRead untuk meminta bacaan sangat konsisten. (Ini mengkonsumsi unit kapasitas baca tambahan, tetapi mengembalikan sebagian besar up-to-date versi item.)

GetItem mengembalikan semua atribut item. Anda dapat menggunakan ekspresi proyeksi untuk mengembalikan sebagian atribut saja. Untuk informasi selengkapnya, lihat Ekspresi proyeksi.

Untuk mengembalikan jumlah unit kapasitas baca yang dikonsumsi oleh GetItem, tetapkan parameter ReturnConsumedCapacity menjadi TOTAL.

contoh

Berikut AWS Command Line Interface (AWS CLI) contoh menunjukkan beberapa GetItem parameter opsional.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL

Menulis item

Untuk membuat, memperbarui, atau menghapus item dalam tabel DynamoDB, gunakan salah satu operasi berikut:

• PutItem

• UpdateItem

• DeleteItem

Untuk setiap operasi ini, Anda harus menentukan seluruh kunci primer, bukan hanya sebagian saja. Misalnya, jika tabel memiliki kunci primer gabungan (kunci partisi dan kunci urutan), Anda harus memberikan nilai untuk kunci partisi dan nilai untuk kunci urutan.

Untuk mengembalikan jumlah unit kapasitas tulis yang digunakan oleh salah satu operasi ini, atur parameter ReturnConsumedCapacity ke salah satu dari berikut ini:

• TOTAL — Mengembalikan jumlah total unit kapasitas tulis yang dikonsumsi.

• INDEXES — Mengembalikan jumlah total unit kapasitas tulis yang digunakan, dengan subtotal untuk tabel dan indeks sekunder apa pun yang terpengaruh oleh operasi.

• NONE — Tidak ada detail kapasitas tulis dikembalikan. (Ini adalah pengaturan default.)

PutItem

PutItem membuat item baru. Jika item dengan kunci yang sama sudah ada di tabel, item tersebut akan diganti dengan item baru.

contoh

Tulis item baru ke tabel Thread. Kunci primer untuk Thread terdiri dari ForumName (kunci partisi) dan Subject (kunci urutan).

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json

Argumen untuk --item disimpan dalam file item.json.

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"},
    "Message": {"S": "First post in this thread"},
    "LastPostedBy": {"S": "[e-mail]"},
    "LastPostDateTime": {"S": "201603190422"}
}

UpdateItem

Jika item dengan kunci tertentu tidak ada, UpdateItem akan membuat item baru. Jika tidak, ini akan mengubah atribut item yang sudah ada.

Anda menggunakan ekspresi pembaruan untuk menentukan atribut yang ingin Anda ubah dan nilai barunya. Untuk informasi selengkapnya, lihat Ekspresi pembaruan.

Dalam ekspresi pembaruan, Anda menggunakan nilai atribut ekspresi sebagai pengganti nilai aktual. Untuk informasi selengkapnya, lihat Nilai atribut ekspresi.

contoh

Modifikasi berbagai atribut dalam item Thread. Parameter ReturnValues opsional menunjukkan item seperti yang muncul setelah pembaruan. Untuk informasi selengkapnya, lihat Nilai yang ditampilkan.

aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW

Argumen untuk --key disimpan dalam file key.json.

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}

Argumen untuk --expression-attribute-values disimpan dalam file expression-attribute-values.json.

{
    ":zero": {"N":"0"},
    ":lastpostedby": {"S":"[e-mail]"}
}

DeleteItem

DeleteItem menghapus item dengan kunci tertentu.

contoh

AWS CLI Contoh berikut menunjukkan cara menghapus Thread item.

aws dynamodb delete-item \
    --table-name Thread \
    --key file://key.json

Nilai yang ditampilkan

Dalam beberapa kasus, Anda mungkin ingin DynamoDB mengembalikan nilai-nilai atribut tertentu seperti nilai yang muncul sebelum atau setelah Anda memodifikasi mereka. Operasi PutItem, UpdateItem, dan DeleteItem memiliki parameter ReturnValues yang dapat Anda gunakan untuk mengembalikan nilai atribut sebelum atau setelah dimodifikasi.

Nilai default untuk ReturnValues adalah NONE, yang berarti DynamoDB tidak mengembalikan informasi apa pun tentang atribut yang dimodifikasi.

Berikut ini adalah pengaturan valid lainnya untuk ReturnValues, yang diatur oleh operasi DynamoDB API.

PutItem

• ReturnValues: ALL_OLD

  • Jika Anda menimpa item yang ada, ALL_OLD akan mengembalikan seluruh item seperti item yang muncul sebelum penimpaan.

  • Jika Anda menulis item yang tidak ada, ALL_OLD tidak akan berpengaruh.

UpdateItem

Penggunaan yang paling umum untuk UpdateItem adalah untuk memperbarui item yang ada. Namun, UpdateItem benar-benar melakukan upsert, yang berarti bahwa ini secara otomatis membuat item jika sudah tidak ada.

• ReturnValues: ALL_OLD

  • Jika Anda memperbarui item yang ada, ALL_OLD akan mengembalikan seluruh item seperti item yang muncul sebelum pembaruan.

  • Jika Anda memperbarui item yang tidak ada (upsert), ALL_OLD tidak akan berpengaruh.

• ReturnValues: ALL_NEW

  • Jika Anda memperbarui item yang ada, ALL_NEW menampilkan seluruh item seperti item yang muncul setelah pembaruan.

  • Jika Anda memperbarui item tidak ada (upsert), ALL_NEW akan mengembalikan seluruh item.

• ReturnValues: UPDATED_OLD

  • Jika Anda memperbarui item yang ada, UPDATED_OLD hanya mengembalikan atribut yang diperbarui seperti atribut yang muncul sebelum pembaruan.

  • Jika Anda memperbarui item yang tidak ada (upsert), UPDATED_OLD tidak akan berpengaruh.

• ReturnValues: UPDATED_NEW

  • Jika Anda memperbarui item yang ada, UPDATED_NEW hanya menampilkan atribut yang terpengaruh, seperti yang muncul setelah pembaruan.

  • Jika Anda memperbarui item tidak ada (upsert), UPDATED_NEW hanya mengembalikan atribut diperbarui, seperti yang muncul setelah pembaruan.

DeleteItem

• ReturnValues: ALL_OLD

  • Jika Anda menghapus item yang ada, ALL_OLD akan mengembalikan seluruh item seperti yang muncul sebelum Anda menghapusnya.

  • Jika Anda menghapus item yang tidak ada, ALL_OLD tidak akan menampilkan data apa pun.

Operasi batch

Untuk aplikasi yang memerlukan membaca atau menulis beberapa item, DynamoDB menyediakan operasi BatchGetItem dan BatchWriteItem. Dengan menggunakan operasi ini, Anda dapat mengurangi jumlah perjalanan bolak-balik jaringan dari aplikasi Anda ke DynamoDB. Selain itu, DynamoDB melakukan operasi baca atau tulis individu secara paralel. Aplikasi Anda mendapatkan keuntungan dari paralelisme ini tanpa perlu mengelola konkurensi atau threading.

Operasi batch pada dasarnya merupakan pembungkus di sekitar beberapa permintaan baca atau tulis. Misalnya, jika permintaan BatchGetItem berisi lima item, DynamoDB melakukan lima operasi GetItem atas nama Anda. Demikian pula, jika permintaan BatchWriteItem berisi dua permintaan put dan empat permintaan penghapusan, DynamoDB akan melakukan dua permintaan PutItem dan empat DeleteItem.

Secara umum, operasi batch tidak gagal kecuali semua permintaan dalam batch mengalami kegagalan. Misalnya, bayangkan Anda melakukan operasi BatchGetItem, tetapi salah satu permintaan GetItem individu dalam batch mengalami kegagalan. Dalam kasus ini, BatchGetItem mengembalikan kunci dan data dari permintaan GetItem yang gagal. Permintaan GetItem lainnya dalam batch tidak akan terpengaruh.

BatchGetItem

Satu operasi BatchGetItem dapat berisi hingga 100 permintaan GetItem individu dapat mengambil data hingga 16 MB. Selain itu, operasi BatchGetItem dapat mengambil item dari beberapa tabel.

contoh

Ambil dua item dari tabel Thread, menggunakan ekspresi proyeksi untuk mengembalikan beberapa atribut saja.

aws dynamodb batch-get-item \
    --request-items file://request-items.json

Argumen untuk --request-items disimpan dalam file request-items.json.

{
    "Thread": {
        "Keys": [
            {
                "ForumName":{"S": "Amazon DynamoDB"},
                "Subject":{"S": "DynamoDB Thread 1"}
            },
            {
                "ForumName":{"S": "Amazon S3"},
                "Subject":{"S": "S3 Thread 1"}
            }
        ],
        "ProjectionExpression":"ForumName, Subject, LastPostedDateTime, Replies"
    }
}

BatchWriteItem

Operasi BatchWriteItem dapat berisi hingga 25 permintaan PutItem dan DeleteItem individu, serta dapat menulis data hingga 16 MB. (Ukuran maksimum item individu adalah sebesar 400 KB.) Selain itu, operasi BatchWriteItem dapat menempatkan atau menghapus item dalam beberapa tabel.

catatan

BatchWriteItem tidak mendukung permintaan UpdateItem.

contoh

Tulis dua item ke tabel ProductCatalog.

aws dynamodb batch-write-item \
    --request-items file://request-items.json

Argumen untuk --request-items disimpan dalam file request-items.json.

{
    "ProductCatalog": [
        {
            "PutRequest": {
                "Item": {
                    "Id": { "N": "601" },
                    "Description": { "S": "Snowboard" },
                    "QuantityOnHand": { "N": "5" },
                    "Price": { "N": "100" }
                }
            }
        },
        {
            "PutRequest": {
                "Item": {
                    "Id": { "N": "602" },
                    "Description": { "S": "Snow shovel" }
                }
            }
        }
    ]
}

Penghitung atom

Anda dapat menggunakan operasi UpdateItem untuk mengimplementasikan penghitung atom—atribut numerik yang bertambah, tanpa syarat, tanpa mengganggu permintaan tulis lainnya. (Semua permintaan tulis diterapkan sesuai urutan penerimaannya.) Dengan penghitung atom, pembaruan tidak idempotent. Dengan kata lain, nilai numerik bertambah atau berkurang setiap kali Anda menelepon. UpdateItem Jika nilai kenaikan yang digunakan untuk memperbarui penghitung atom positif, maka itu dapat menyebabkan penghitungan berlebihan. Jika nilai kenaikan negatif, maka dapat menyebabkan kekurangan perhitungan.

Anda dapat menggunakan penghitung atom untuk melacak jumlah pengunjung ke situs web. Dalam hal ini, aplikasi Anda akan menaikkan nilai numerik, terlepas dari nilai saat ini. Jika operasi UpdateItem gagal, aplikasi hanya dapat mencoba ulang operasi. Tindakan ini akan berisiko memperbarui penghitung dua kali, tetapi Anda mungkin bisa menoleransi sedikit kelebihan penghitungan atau kekurangan penghitungan dari pengunjung situs web.

Penghitung atom tidak akan cocok ketika kelebihan penghitungan atau kekurangan penghitungan tidak dapat ditoleransi (misalnya, dalam aplikasi perbankan). Dalam kasus ini, lebih aman menggunakan pembaruan bersyarat, bukannya penghitung atom.

Untuk informasi selengkapnya, lihat Menambahkan dan mengurangi atribut numerik.

contoh

AWS CLI Contoh berikut menambah produk Price sebesar 5. Untuk contoh ini, item diketahui ada sebelum penghitung diperbarui. Karena UpdateItem tidak idempotent, Price meningkat setiap kali Anda menjalankan kode ini.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id": { "N": "601" }}' \
    --update-expression "SET Price = Price + :incr" \
    --expression-attribute-values '{":incr":{"N":"5"}}' \
    --return-values UPDATED_NEW

Penulisan bersyarat

Secara default, operasi tulis DynamoDB (PutItem, UpdateItem, DeleteItem) bersifat tanpa syarat: Setiap operasi menimpa item yang ada yang memiliki kunci primer tertentu.

DynamoDB secara opsional mendukung penulisan bersyarat untuk operasi ini. Penulisan bersyarat akan berhasil hanya jika atribut item memenuhi satu atau beberapa kondisi yang diharapkan. Jika tidak, operasi ini akan mengembalikan kesalahan.

Penulisan bersyarat memeriksa kondisinya terhadap versi item yang terbaru diperbarui. Perhatikan bahwa jika item sebelumnya tidak ada atau jika operasi sukses terbaru terhadap item tersebut adalah penghapusan, maka penulisan bersyarat tidak akan menemukan item sebelumnya.

Penulisan bersyarat sangat membantu dalam banyak situasi. Misalnya, Anda mungkin ingin operasi PutItem bisa berhasil hanya jika sudah tidak ada item dengan kunci primer yang sama. Atau Anda dapat mencegah operasi UpdateItem memodifikasi item jika salah satu atributnya memiliki nilai tertentu.

Penulisan bersyarat berguna jika beberapa pengguna mencoba mengubah item yang sama. Perhatikan diagram berikut, di mana dua pengguna (Alice dan Bob) bekerja dengan item yang sama dari tabel DynamoDB.

Misalkan Alice menggunakan AWS CLI untuk memperbarui Price atribut ke 8.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --update-expression "SET Price = :newval" \
    --expression-attribute-values file://expression-attribute-values.json

Argumen untuk --expression-attribute-values disimpan dalam file expression-attribute-values.json:

{
    ":newval":{"N":"8"}
}

Sekarang anggaplah Bob mengeluarkan permintaan UpdateItem yang serupa kemudian, tetapi mengubah Price menjadi 12. Untuk Bob, parameter --expression-attribute-values akan terlihat seperti berikut ini.

{
    ":newval":{"N":"12"}
}

Permintaan Bob berhasil, tetapi pembaruan Alice sebelumnya hilang.

Untuk meminta PutItem, DeleteItem, atau UpdateItem bersyarat, Andalah yang menentukan ekspresi kondisi. Ekspresi kondisi adalah string yang berisi nama atribut, operator bersyarat, dan fungsi bawaan. Seluruh ekspresi harus bernilai benar. Jika tidak, operasi gagal.

Sekarang pertimbangkan diagram berikut yang menunjukkan bagaimana penulisan bersyarat akan mencegah pembaruan Alice ditimpa.

Alice mencoba pertama kali untuk memperbarui Price menjadi 8, tetapi hanya jika Price saat ini adalah 10.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --update-expression "SET Price = :newval" \
    --condition-expression "Price = :currval" \
    --expression-attribute-values file://expression-attribute-values.json

Argumen untuk --expression-attribute-values disimpan dalam file expression-attribute-values.json.

{
    ":newval":{"N":"8"},
    ":currval":{"N":"10"}
}

Pembaruan Alice berhasil karena kondisi bernilai benar.

Berikutnya, Bob mencoba memperbarui Price menjadi 12, tetapi hanya jika Price saat ini adalah 10. Untuk Bob, parameter --expression-attribute-values akan terlihat seperti berikut ini.

{
    ":newval":{"N":"12"},
    ":currval":{"N":"10"}
}

Karena Alice sebelumnya telah mengubah Price ke 8, ekspresi kondisi bernilai SALAH, dan pembaruan Bob mengalami kegagalan.

Untuk informasi selengkapnya, lihat Ekspresi kondisi.

Idempotensi penulisan bersyarat

Penulisan bersyarat dapat menjadi idempotent jika pemeriksaan bersyarat berada pada atribut yang sama dan sedang diperbarui. Ini berarti bahwa DynamoDB melakukan permintaan tulis yang diberikan hanya jika nilai atribut tertentu dalam item cocok dengan tempat mereka berada pada saat permintaan sesuai harapan Anda.

Misalnya, misalnya Anda mengeluarkan permintaan UpdateItem untuk meningkatkan Price dari item sebesar 3, tetapi hanya jika Price saat ini adalah 20. Setelah Anda mengirimkan permintaan, tetapi sebelum Anda mendapatkan hasil kembali, terjadi kesalahan jaringan, dan Anda tidak tahu apakah permintaan tersebut berhasil. Karena penulisan bersyarat ini idempotent, Anda dapat mencoba kembali permintaan UpdateItem yang sama, dan DynamoDB memperbarui item hanya jika Price saat ini adalah 20.

Unit kapasitas yang digunakan oleh penulisan bersyarat

Jika ConditionExpression bernilai false selama penulisan bersyarat, DynamoDB masih menggunakan kapasitas tulis dari tabel. Jumlah yang dikonsumsi tergantung dari besar kecilnya barang yang ada (atau minimal 1). Misalnya, jika item yang ada berukuran 300kb dan item baru yang Anda coba buat atau perbarui berukuran 310kb, unit kapasitas tulis yang digunakan akan menjadi 300 jika kondisi gagal, dan 310 jika kondisi berhasil. Jika ini adalah item baru (belum ada item yang ada), maka unit kapasitas tulis yang digunakan adalah 1 jika kondisi gagal dan 310 jika kondisi berhasil.

catatan

Operasi tulis hanya mengonsumsi unit kapasitas tulis. Operasi tersebut tidak pernah mengonsumsi unit kapasitas baca.

Penulisan bersyarat yang gagal akan menampilkan ConditionalCheckFailedException. Ketika hal ini terjadi, Anda tidak menerima informasi apa pun sebagai respons tentang kapasitas tulis yang dikonsumsi. Namun, Anda dapat melihat ConsumedWriteCapacityUnits metrik untuk tabel di Amazon CloudWatch. Untuk informasi selengkapnya, lihat Metrik DynamoDB di Pencatatan dan pemantauan di DynamoDB.

Untuk mengembalikan jumlah unit kapasitas tulis yang dikonsumsi selama penulisan bersyarat, Anda menggunakan parameter ReturnConsumedCapacity:

• TOTAL — Mengembalikan jumlah total unit kapasitas tulis yang dikonsumsi.

• INDEXES — Mengembalikan jumlah total unit kapasitas tulis yang digunakan, dengan subtotal untuk tabel dan indeks sekunder apa pun yang terpengaruh oleh operasi.

• NONE — Tidak ada detail kapasitas tulis dikembalikan. (Ini menjadi opsi default.)

catatan

Tidak seperti indeks sekunder global, indeks sekunder lokal berbagi kapasitas throughput yang disediakan dengan tabelnya. Aktivitas baca dan tulis pada indeks sekunder lokal mengonsumsi kapasitas throughput yang disediakan dari tabel.