Bekerja dengan item dan atribut di DynamoDB

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

DynamoDB menyediakan empat operasi untuk fungsi dasar create, read, update, dan delete CRUD (). Semua operasi ini bersifat atom.

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 CRUD operasi dasar, DynamoDB juga menyediakan yang berikut:

Operasi batch ini menggabungkan beberapa CRUD operasi menjadi 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 SDKs.

Membaca item

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

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

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 Menggunakan ekspresi proyeksi di DynamoDB.

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

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:

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:

PutItem

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

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

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"},
    "Message": {"S": "First post in this thread"},
    "LastPostedBy": {"S": "fred@example.com"},
    "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 Menggunakan ekspresi pembaruan di DynamoDB.

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

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":"barney@example.com"}
}

DeleteItem

DeleteItem menghapus item dengan kunci tertentu.

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

Nilai yang dikembalikan

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 untukReturnValues, yang diatur oleh operasi DynamoDBAPI.

PutItem

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.

DeleteItem

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.

aws dynamodb batch-get-item \
    --request-items 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.

aws dynamodb batch-write-item \
    --request-items 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.

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 Contoh ekspresi kondisi DynamoDB CLI.

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.

Penulisan bersyarat yang gagal akan menampilkan ConditionalCheckFailedException. Ketika ini terjadi, Anda tidak menerima informasi apa pun dalam tanggapan tentang kapasitas tulis yang dikonsumsi.

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