kvp in attributeList)
{
string attributeName = kvp.Key;
AttributeValue value = kvp.Value;
Console.WriteLine(
attributeName + " " +
(value.S == null ? "" : "S=[" + value.S + "]") +
(value.N == null ? "" : "N=[" + value.N + "]") +
(value.SS == null ? "" : "SS=[" + string.Join(",", value.SS.ToArray()) + "]") +
(value.NS == null ? "" : "NS=[" + string.Join(",", value.NS.ToArray()) + "]") +
(value.B == null ? "" : "B=[" + FromGzipMemoryStream(value.B) + "]")
);
}
Console.WriteLine("************************************************");
}
private static MemoryStream ToGzipMemoryStream(string value)
{
MemoryStream output = new MemoryStream();
using (GZipStream zipStream = new GZipStream(output, CompressionMode.Compress, true))
using (StreamWriter writer = new StreamWriter(zipStream))
{
writer.Write(value);
}
return output;
}
private static string FromGzipMemoryStream(MemoryStream stream)
{
using (GZipStream zipStream = new GZipStream(stream, CompressionMode.Decompress))
using (StreamReader reader = new StreamReader(zipStream))
{
return reader.ReadToEnd();
}
}
}
}
```
# Meningkatkan akses data dengan indeks sekunder di DynamoDB
Amazon DynamoDB menyediakan akses cepat ke item-item dalam sebuah tabel dengan menentukan nilai-nilai kunci primer. Namun, banyak aplikasi mungkin mendapat manfaat dari tersedianya satu atau lebih kunci sekunder (atau alternatif), untuk memungkinkan akses efisien ke data dengan atribut selain kunci primer. Untuk mengatasi hal ini, Anda dapat membuat satu atau lebih indeks sekunder pada tabel dan mengeluarkan permintaan `Query` atau `Scan` terhadap indeks ini.
*Indeks sekunder* adalah struktur data yang berisi subset atribut dari tabel, bersama dengan kunci alternatif untuk mendukung operasi `Query`. Anda dapat mengambil data dari indeks menggunakan sebuah `Query`, dengan cara yang sama seperti saat Anda menggunakan `Query` dengan tabel. Sebuah tabel dapat memiliki beberapa indeks sekunder, yang memberikan aplikasi Anda akses ke banyak pola kueri yang berbeda.
**catatan**
Anda juga dapat melakukan `Scan` pada indeks, dengan cara yang sama seperti Anda melakukan `Scan` pada tabel.
Akses lintas akun untuk operasi pemindaian indeks sekunder saat ini tidak didukung dengan kebijakan berbasis [sumber daya](access-control-resource-based.md).
Setiap indeks sekunder dikaitkan dengan tepat satu tabel, dari mana indeks memperoleh datanya. Ini disebut *tabel dasar* untuk indeks. Saat Anda membuat indeks, Anda menentukan kunci alternatif untuk indeks tersebut (kunci partisi dan kunci urutan). Anda juga menentukan atribut yang ingin Anda *proyeksikan*, atau salin, dari tabel dasar ke dalam indeks. DynamoDB menyalin atribut ini ke dalam indeks, bersama dengan atribut kunci primer dari tabel dasar. Anda kemudian dapat mengkueri atau memindai indeks sama seperti Anda mengkueri atau memindai tabel.
Setiap indeks sekunder dikelola secara otomatis oleh DynamoDB. Saat Anda menambahkan, mengubah, atau menghapus item di tabel dasar, indeks apa pun di tabel tersebut juga diperbarui untuk mencerminkan perubahan ini.
DynamoDB mendukung dua jenis indeks sekunder:
+ **[Indeks sekunder global](GSI.html) — **Indeks dengan kunci partisi dan kunci urutan yang mungkin berbeda dari yang ada di tabel dasar. Indeks sekunder global dianggap "global" karena kueri pada indeks dapat menjangkau semua data di tabel dasar, di semua partisi. Indeks sekunder global disimpan dalam ruang partisinya sendiri jauh dari tabel dasar dan diskalakan secara terpisah dari tabel dasar.
+ **[Indeks sekunder lokal](LSI.html) – **Indeks yang memiliki kunci partisi yang sama dengan tabel, namun kunci urutan berbeda. Indeks sekunder lokal bersifat "lokal" dalam arti bahwa setiap partisi indeks sekunder lokal dicakup ke partisi tabel dasar yang memiliki nilai kunci partisi yang sama.
Untuk perbandingan indeks sekunder global dan indeks sekunder lokal, lihat video ini.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/BkEu7zBWge8)
**Topics**
+ [Menggunakan Indeks Sekunder Global di DynamoDB](GSI.md)
+ [Indeks sekunder lokal](LSI.md)
Anda harus mempertimbangkan persyaratan aplikasi Anda saat menentukan jenis indeks yang akan digunakan. Tabel berikut menunjukkan perbedaan utama antara indeks sekunder global dan indeks sekunder lokal.
****
| Karakteristik | Indeks sekunder global | Indeks sekunder lokal |
| --- | --- | --- |
| Skema Kunci | Kunci primer indeks sekunder global dapat berupa sederhana (kunci partisi) atau gabungan (kunci partisi dan kunci urutan). | Kunci primer dari indeks sekunder lokal harus gabungan (kunci partisi dan kunci urutan). |
| Atribut Kunci | Kunci partisi indeks dan kunci urutan (jika ada) dapat berupa atribut tabel dasar apa pun berupa jenis string, angka, atau biner. | Kunci partisi indeks adalah atribut yang sama dengan kunci partisi dari tabel dasar. Kunci urutan dapat berupa atribut tabel dasar apa pun dari jenis string, angka, atau biner. |
| Pembatasan Ukuran Per Nilai Kunci Partisi | Tidak ada batasan ukuran untuk indeks sekunder global. | Untuk setiap nilai kunci partisi, ukuran total semua item yang diindeks harus 10 GB atau kurang. |
| Operasi Indeks Online | Indeks sekunder global dapat dibuat pada saat yang sama saat Anda membuat tabel. Anda juga dapat menambahkan indeks sekunder global baru ke tabel yang ada, atau menghapus indeks sekunder global yang ada. Untuk informasi selengkapnya, lihat [Mengelola Indeks Sekunder Global di DynamoDB](GSI.OnlineOps.md). | Indeks sekunder lokal dibuat pada saat yang sama saat Anda membuat tabel. Anda tidak dapat menambahkan indeks sekunder lokal ke tabel yang sudah ada, Anda juga tidak dapat menghapus indeks sekunder lokal yang saat ini ada. |
| Kueri dan Partisi | Indeks sekunder global memungkinkan Anda melakukan kueri di seluruh tabel, di semua partisi. | Indeks sekunder lokal memungkinkan Anda melakukan kueri pada satu partisi, seperti yang ditentukan oleh nilai kunci partisi dalam kueri. |
| Konsistensi Baca | Kueri pada indeks sekunder global hanya mendukung konsistensi akhir. | Saat Anda melakukan kueri indeks sekunder lokal, Anda dapat memilih konsistensi akhir atau konsistensi kuat. |
| Konsumsi Throughput yang Disediakan | Setiap indeks sekunder global memiliki pengaturan throughput yang disediakan sendiri untuk aktivitas baca dan tulis. Kueri atau pemindaian pada indeks sekunder global menggunakan unit kapasitas dari indeks, bukan dari tabel dasar. Hal yang sama berlaku untuk pembaruan indeks sekunder global karena penulisan tabel. Indeks sekunder global yang terkait dengan tabel global mengonsumsi unit kapasitas tulis. | Kueri atau pemindaian pada indeks sekunder lokal menggunakan unit kapasitas baca dari tabel dasar. Saat Anda menulis ke tabel, indeks sekunder lokalnya juga diperbarui, dan pembaruan ini menggunakan unit kapasitas tulis dari tabel dasar. Indeks sekunder lokal yang terkait dengan tabel global mengonsumsi unit kapasitas tulis. |
| Atribut yang Diproyeksikan | Dengan kueri atau pemindaian indeks sekunder global, Anda hanya dapat meminta atribut yang diproyeksikan ke dalam indeks. DynamoDB tidak mengambil atribut apa pun dari tabel. | Jika Anda membuat kueri atau memindai indeks sekunder lokal, Anda dapat meminta atribut yang tidak diproyeksikan ke dalam indeks. DynamoDB secara otomatis mengambil atribut tersebut dari tabel. |
Jika ingin membuat lebih dari satu tabel dengan indeks sekunder, Anda harus melakukannya secara berurutan. Misalnya, Anda akan membuat tabel pertama dan menunggu agar tabel menjadi `ACTIVE`, buat tabel berikutnya dan tunggu agar tabel menjadi `ACTIVE`, dan seterusnya. Jika Anda mencoba membuat lebih dari satu tabel secara bersamaan dengan indeks sekunder, DynamoDB mengembalikan `LimitExceededException`.
Setiap indeks sekunder menggunakan [kelas tabel](HowItWorks.TableClasses.html) dan [mode kapasitas](capacity-mode.md) yang sama dengan tabel dasar yang terkait dengannya. Untuk setiap indeks sekunder, Anda harus menentukan hal berikut:
+ Jenis indeks yang akan dibuat – baik indeks sekunder global atau indeks sekunder lokal.
+ Nama untuk indeks. Aturan penamaan untuk indeks sama dengan aturan untuk tabel, seperti yang tercantum dalam [Kuota di Amazon DynamoDB](ServiceQuotas.md). Nama harus unik untuk tabel dasar yang terkait dengannya, namun Anda dapat menggunakan nama yang sama untuk indeks yang terkait dengan tabel dasar berbeda.
+ Skema kunci indeks. Setiap atribut dalam skema kunci indeks harus merupakan atribut tingkat atas dari jenis `String`, `Number`, atau `Binary`. Jenis data lain, termasuk dokumen dan set, tidak diperbolehkan. Persyaratan lain untuk skema kunci bergantung pada jenis indeks:
+ Untuk indeks sekunder global, kunci partisi dapat berupa atribut skalar apa pun dari tabel dasar. Kunci urutan bersifat opsional, dan dapat berupa atribut skalar apa pun dari tabel dasar.
+ Untuk indeks sekunder lokal, kunci partisi harus sama dengan kunci partisi tabel dasar, dan kunci urutan harus berupa atribut tabel dasar non-kunci.
+ Atribut tambahan, jika ada, untuk diproyeksikan dari tabel dasar ke dalam indeks. Atribut ini merupakan tambahan dari atribut kunci tabel, yang secara otomatis diproyeksikan ke dalam setiap indeks. Anda dapat memproyeksikan atribut dari jenis data apa pun, termasuk skalar, dokumen, dan set.
+ Pengaturan throughput yang disediakan untuk indeks, jika perlu:
+ Untuk indeks sekunder global, Anda harus menentukan pengaturan unit kapasitas baca dan tulis. Pengaturan throughput yang disediakan ini tidak tergantung pada pengaturan tabel dasar.
+ Untuk indeks sekunder lokal, Anda tidak perlu menentukan pengaturan unit kapasitas baca dan tulis. Setiap operasi baca dan tulis pada indeks sekunder lokal diambil dari pengaturan throughput yang disediakan dari tabel dasarnya.
Untuk fleksibilitas kueri maksimum, Anda dapat membuat hingga 20 indeks sekunder global (kuota default) dan hingga 5 indeks sekunder lokal per tabel.
Untuk mendapatkan daftar rinci indeks sekunder pada tabel, gunakan operasi `DescribeTable`. `DescribeTable` menampilkan nama, ukuran penyimpanan, dan jumlah item untuk setiap indeks sekunder pada tabel. Nilai-nilai ini tidak diperbarui secara real time, tetapi diperbarui kira-kira setiap enam jam.
Anda dapat mengakses data dalam indeks sekunder menggunakan operasi `Query` atau `Scan`. Kueri harus menentukan nama tabel dasar dan nama indeks yang ingin Anda gunakan, atribut yang akan dihasilkan dalam hasil kueri, dan syarat kueri apa pun yang ingin Anda terapkan. DynamoDB dapat menampilkan hasil dalam urutan menaik atau menurun.
Saat Anda menghapus tabel, semua indeks yang terkait dengan tabel tersebut juga akan dihapus.
Untuk praktik terbaik, lihat [Praktik terbaik untuk menggunakan indeks sekunder di DynamoDB](bp-indexes.md).
# Menggunakan Indeks Sekunder Global di DynamoDB
Beberapa aplikasi mungkin perlu melakukan banyak jenis kueri, menggunakan berbagai atribut berbeda sebagai kriteria kueri. Untuk mendukung persyaratan ini, Anda dapat membuat satu atau beberapa* indeks sekunder global* dan mengeluarkan permintaan `Query` terhadap indeks ini di Amazon DynamoDB.
**Topics**
+ [Skenario: Menggunakan Indeks Sekunder Global](#GSI.scenario)
+ [Proyeksi atribut](#GSI.Projections)
+ [Skema kunci multi-atribut](#GSI.MultiAttributeKeys)
+ [Membaca data dari Indeks Sekunder Global](#GSI.Reading)
+ [Sinkronisasi data antara tabel dan Indeks Sekunder Global](#GSI.Writes)
+ [Kelas tabel dengan Indeks Sekunder Global](#GSI.tableclasses)
+ [Pertimbangan Throughput yang disediakan untuk Indeks Sekunder Global](#GSI.ThroughputConsiderations)
+ [Pertimbangan penyimpanan untuk Indeks Sekunder Global](#GSI.StorageConsiderations)
+ [Pola desain](GSI.DesignPatterns.md)
+ [Mengelola Indeks Sekunder Global di DynamoDB](GSI.OnlineOps.md)
+ [Mendeteksi dan memperbaiki pelanggaran kunci indeks di DynamoDB](GSI.OnlineOps.ViolationDetection.md)
+ [Menggunakan Indeks Sekunder Global: Java](GSIJavaDocumentAPI.md)
+ [Menggunakan Indek Sekunder Global: .NET](GSILowLevelDotNet.md)
+ [Bekerja dengan Indeks Sekunder Global di DynamoDB menggunakan AWS CLI](GCICli.md)
## Skenario: Menggunakan Indeks Sekunder Global
Sebagai ilustrasi, pertimbangkan tabel bernama `GameScores` yang melacak pengguna dan skor untuk aplikasi game seluler. Setiap item dalam `GameScores` diidentifikasi dengan kunci partisi (`UserId`) dan kunci urutan (`GameTitle`). Diagram berikut menunjukkan bagaimana item dalam tabel akan diatur. (Tidak semua atribut ditampilkan.)
![\[GameScores tabel yang berisi daftar id pengguna, judul, skor, tanggal, dan kemenangan/kerugian.\]](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/GSI_01.png)
Sekarang, anggaplah Anda ingin menulis aplikasi papan peringkat untuk menampilkan skor teratas untuk setiap game. Kueri yang menentukan atribut kunci (`UserId` dan `GameTitle`) akan sangat efisien. Namun, jika aplikasi perlu mengambil data dari `GameScores` berdasarkan `GameTitle` saja, aplikasi tersebut perlu menggunakan operasi `Scan`. Karena lebih banyak item ditambahkan ke tabel, pemindaian semua data akan lambat dan tidak efisien. Hal ini membuat pertanyaan-pertanyaan seperti berikut ini sulit dijawab:
+ Berapa skor tertinggi yang pernah tercatat untuk game Meteor Blasters?
+ Pengguna mana yang memiliki skor tertinggi untuk Galaxy Invaders?
+ Berapa rasio tertinggi untuk kemenangan vs kekalahan?
Untuk mempercepat kueri pada atribut non-kunci, Anda dapat membuat indeks sekunder global. Indeks sekunder global berisi pilihan atribut dari tabel dasar, tetapi atribut tersebut diatur oleh kunci primer yang berbeda dari tabel. Kunci indeks tidak perlu memiliki atribut kunci apa pun dari tabel. Bahkan tidak perlu memiliki skema kunci yang sama dengan tabel.
Misalnya, Anda dapat membuat indeks sekunder global bernama `GameTitleIndex`, dengan kunci partisi `GameTitle` dan kunci urutan `TopScore`. Atribut kunci primer tabel dasar selalu diproyeksikan ke dalam indeks, sehingga atribut `UserId` juga ada. Diagram berikut menunjukkan seperti apa tampilan indeks `GameTitleIndex`.
![\[GameTitleIndex tabel yang berisi daftar judul, skor, dan id pengguna.\]](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/GSI_02.png)
Sekarang Anda dapat meminta `GameTitleIndex` dan dengan mudah mendapatkan skor untuk Meteor Blasters. Hasilnya diurutkan berdasarkan nilai kunci urutan, `TopScore`. Jika Anda mangatur parameter `ScanIndexForward` ke false, hasilnya ditampilkan dalam urutan menurun, sehingga skor tertinggi ditampilkan terlebih dahulu.
Setiap indeks sekunder global harus memiliki kunci partisi, dan dapat memiliki kunci urutan opsional. Skema kunci indeks dapat berbeda dari skema tabel dasar. Anda dapat memiliki tabel dengan kunci primer sederhana (kunci partisi), dan membuat indeks sekunder global dengan kunci primer komposit (kunci partisi dan kunci urutan)—atau sebaliknya. Atribut kunci indeks dapat terdiri dari atribut `String`, `Number`, atau `Binary` tingkat atas dari tabel dasar. Jenis skalar, jenis dokumen, dan jenis kumpulan lain tidak diperbolehkan.
Anda dapat memproyeksikan atribut tabel dasar lain ke dalam indeks jika ingin. Saat Anda mengkueri indeks, DynamoDB dapat mengambil atribut yang diproyeksikan ini secara efisien. Namun, kueri indeks sekunder global tidak dapat mengambil atribut dari tabel dasar. Misalnya, jika Anda mengkueri `GameTitleIndex` seperti yang ditunjukkan pada diagram sebelumnya, kueri tidak dapat mengakses atribut non-kunci selain `TopScore` (meskipun atribut kunci `GameTitle` dan `UserId` akan diproyeksikan secara otomatis).
Dalam tabel DynamoDB, setiap nilai kunci harus unik. Namun, nilai kunci dalam indeks sekunder global tidak perlu unik. Sebagai ilustrasi, anggaplah sebuah game bernama Comet Quest sangat sulit, dengan banyak pengguna baru yang telah mencoba tetapi gagal mendapatkan skor di atas nol. Berikut adalah beberapa data yang dapat mewakili hal tersebut.
****
| UserId | GameTitle | TopScore |
| --- | --- | --- |
| 123 | Comet Quest | 0 |
| 201 | Comet Quest | 0 |
| 301 | Comet Quest | 0 |
Ketika data ini ditambahkan ke tabel `GameScores`, DynamoDB menyebarkannya ke `GameTitleIndex`. Jika kita kemudian mengkueri indeks menggunakan Comet Quest untuk `GameTitle` dan 0 untuk `TopScore`, data berikut dikembalikan.
![\[Tabel berisi daftar judul, skor teratas, dan id pengguna.\]](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/GSI_05.png)
Hanya item dengan nilai kunci tertentu yang muncul dalam respons. Dalam kumpulan data itu, item-item tersebut tidak berada dalam urutan tertentu.
Indeks sekunder global hanya melacak item data yang atribut utamanya benar-benar ada. Misalnya, katakanlah Anda menambahkan item baru ke tabel `GameScores`, tetapi hanya menyediakan atribut kunci primer yang diperlukan.
****
| UserId | GameTitle |
| --- | --- |
| 400 | Comet Quest |
Karena Anda tidak menentukan atribut `TopScore`, DynamoDB tidak akan menyebarkan item ini ke `GameTitleIndex`. Jadi, jika mengkueri `GameScores` untuk semua item Comet Quest, Anda akan mendapatkan empat item berikut.
![\[Tabel berisi daftar 4 judul, skor teratas, dan id pengguna.\]](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/GSI_04.png)
Kueri serupa pada `GameTitleIndex` masih akan mengembalikan tiga item, bukan empat. Ini karena item dengan `TopScore` yang tidak ada tidak disebarkan ke indeks.
![\[Tabel berisi daftar 3 judul, skor teratas, dan id pengguna.\]](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/GSI_05.png)
## Proyeksi atribut
*Proyeksi* adalah kumpulan atribut yang disalin dari tabel ke indeks sekunder. Kunci partisi dan kunci urutan tabel selalu diproyeksikan ke dalam indeks; Anda dapat memproyeksikan atribut lain untuk mendukung persyaratan kueri aplikasi Anda. Saat Anda mengkueri indeks, Amazon DynamoDB dapat mengakses atribut apa pun dalam proyeksi seolah-olah atribut tersebut berada dalam tabelnya sendiri.
Saat membuat indeks sekunder, Anda perlu menentukan atribut yang akan diproyeksikan ke dalam indeks. DynamoDB menyediakan tiga opsi berbeda untuk ini:
+ *KEYS\$1ONLY* – Setiap item dalam indeks hanya terdiri dari kunci partisi tabel dan nilai kunci urutan, ditambah nilai kunci indeks. Opsi `KEYS_ONLY` menghasilkan indeks sekunder sekecil mungkin.
+ *INCLUDE* – Selain atribut yang dijelaskan dalam `KEYS_ONLY`, indeks sekunder akan menyertakan atribut non-kunci lain yang Anda tentukan.
+ *ALL* – Indeks sekunder menyertakan semua atribut dari tabel sumber. Karena semua data tabel diduplikasi dalam indeks, proyeksi `ALL` menghasilkan indeks sekunder sebesar yang mungkin.
Pada diagram sebelumnya, `GameTitleIndex` hanya memiliki satu atribut yang diproyeksikan: `UserId`. Jadi, meskipun aplikasi dapat secara efisien menentukan `UserId` dari pencetak skor terbanyak untuk setiap game menggunakan `GameTitle` dan `TopScore` dalam kueri, aplikasi tidak dapat secara efisien menentukan rasio kemenangan vs. kekalahan tertinggi untuk pencetak skor terbanyak. Untuk melakukannya, aplikasi harus melakukan kueri tambahan di tabel dasar untuk mengambil kemenangan dan kerugian untuk masing-masing pencetak gol terbanyak. Cara yang lebih efisien untuk mendukung kueri pada data ini adalah dengan memproyeksikan atribut-atribut ini dari tabel dasar ke dalam indeks sekunder global, seperti yang ditunjukkan dalam diagram ini.
![\[Penggambaran memproyeksikan atribut non-kunci ke dalam GSI untuk mendukung kueri yang efisien.\]](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/GSI_06.png)
Karena atribut non-kunci `Wins` dan `Losses` diproyeksikan ke dalam indeks, aplikasi dapat menentukan rasio kemenangan vs. kekalahan untuk game apa pun, atau untuk kombinasi game dan ID pengguna mana pun.
Saat memilih atribut untuk diproyeksikan ke dalam indeks sekunder global, Anda harus mempertimbangkan tradeoff antara biaya throughput yang disediakan dan biaya penyimpanan:
+ Jika Anda hanya perlu mengakses beberapa atribut dengan latensi serendah mungkin, pertimbangkan untuk hanya memproyeksikan atribut tersebut ke dalam indeks sekunder global. Semakin kecil indeks, semakin sedikit biaya penyimpanannya, dan semakin sedikit pula biaya tulis Anda.
+ Jika aplikasi Anda sering mengakses beberapa atribut non-kunci, sebaiknya Anda memproyeksikan atribut tersebut ke dalam indeks sekunder global. Biaya penyimpanan tambahan untuk indeks sekunder global mengimbangi biaya melakukan pemindaian tabel yang sering dilakukan.
+ Jika sering mengakses sebagian besar atribut non-kunci, Anda dapat memproyeksikan atribut ini—atau bahkan seluruh tabel dasar— ke dalam indeks sekunder global. Hal ini akan memberi Anda fleksibilitas maksimum. Namun, biaya penyimpanan Anda akan meningkat, atau bahkan berlipat ganda.
+ Jika aplikasi Anda jarang mengkueri tabel, tetapi harus melakukan banyak penulisan atau pembaruan terhadap data dalam tabel, pertimbangkan untuk memproyeksikan `KEYS_ONLY`. Indeks sekunder global akan berukuran minimal, tetapi akan tetap tersedia jika diperlukan untuk aktivitas kueri.
## Skema kunci multi-atribut
Global Secondary Indexes mendukung kunci multi-atribut, memungkinkan Anda untuk membuat kunci partisi dan mengurutkan kunci dari beberapa atribut. Dengan kunci multi-atribut, Anda dapat membuat kunci partisi dari hingga empat atribut dan kunci pengurutan dari hingga empat atribut, dengan total hingga delapan atribut per skema kunci.
Kunci multi-atribut menyederhanakan model data Anda dengan menghilangkan kebutuhan untuk menggabungkan atribut secara manual menjadi kunci sintetis. Alih-alih membuat string komposit seperti`TOURNAMENT#WINTER2024#REGION#NA-EAST`, Anda dapat menggunakan atribut alami dari model domain Anda secara langsung. DynamoDB menangani logika kunci komposit secara otomatis, melakukan hashing beberapa atribut kunci partisi bersama-sama untuk distribusi data dan mempertahankan urutan pengurutan hierarkis di beberapa atribut kunci pengurutan.
Misalnya, pertimbangkan sistem turnamen game di mana Anda ingin mengatur pertandingan berdasarkan turnamen dan wilayah. Dengan kunci multi-atribut, Anda dapat mendefinisikan kunci partisi Anda sebagai dua atribut terpisah: `tournamentId` dan`region`. Demikian pula, Anda dapat menentukan kunci pengurutan Anda menggunakan beberapa atribut seperti `round``bracket`,, dan `matchId` untuk membuat hierarki alami. Pendekatan ini membuat data Anda diketik dan kode Anda bersih, tanpa manipulasi string atau penguraian.
Saat Anda menanyakan indeks sekunder global dengan kunci multi-atribut, Anda harus menentukan semua atribut kunci partisi menggunakan kondisi kesetaraan. Untuk mengurutkan atribut kunci, Anda dapat menanyakannya left-to-right dalam urutan yang ditentukan dalam skema kunci. Ini berarti Anda dapat menanyakan atribut kunci sortir pertama saja, dua atribut pertama bersama-sama, atau semua atribut bersama-sama, tetapi Anda tidak dapat melewati atribut di tengah. Kondisi ketidaksetaraan seperti`>`,`<`,`BETWEEN`, atau `begins_with()` harus menjadi kondisi terakhir dalam kueri Anda.
Kunci multi-atribut bekerja sangat baik saat membuat indeks sekunder global pada tabel yang ada. Anda dapat menggunakan atribut yang sudah ada di tabel Anda tanpa mengisi kembali kunci sintetis di seluruh data Anda. Ini membuatnya mudah untuk menambahkan pola kueri baru ke aplikasi Anda dengan membuat indeks yang mengatur ulang data Anda menggunakan kombinasi atribut yang berbeda.
Setiap atribut dalam kunci multi-atribut dapat memiliki tipe datanya sendiri: `String` (S), `Number` (N), atau `Binary` (B). Saat memilih tipe data, pertimbangkan bahwa `Number` atribut mengurutkan secara numerik tanpa memerlukan padding nol, sementara atribut mengurutkan secara leksikografis. `String` Misalnya, jika Anda menggunakan `Number` tipe untuk atribut skor, nilai 5, 50, 500, dan 1000 diurutkan dalam urutan numerik alami. Nilai yang sama dengan `String` tipe akan diurutkan sebagai “1000", “5", “50", “500" kecuali Anda menutupinya dengan angka nol di depan.
Saat mendesain kunci multi-atribut, urutkan atribut Anda dari yang paling umum ke yang paling spesifik. Untuk kunci partisi, gabungkan atribut yang selalu ditanyakan bersama dan yang menyediakan distribusi data yang baik. Untuk kunci sortir, tempatkan atribut yang sering ditanyakan terlebih dahulu dalam hierarki untuk memaksimalkan fleksibilitas kueri. Urutan ini memungkinkan Anda untuk menanyakan pada tingkat perincian apa pun yang cocok dengan pola akses Anda.
Lihat [Kunci multi-atribut](GSI.DesignPattern.MultiAttributeKeys.md) contoh implementasi untuk.
## Membaca data dari Indeks Sekunder Global
Anda dapat mengambil item dari indeks sekunder global menggunakan operasi `Query` dan `Scan`. Operasi `GetItem` dan `BatchGetItem` tidak dapat digunakan pada indeks sekunder global.
### Mengkueri Indeks Sekunder Global
Anda dapat menggunakan operasi `Query` untuk mengakses satu atau beberapa item dalam indeks sekunder global. Kueri harus menentukan nama tabel dasar dan nama indeks yang ingin Anda gunakan, atribut yang akan dihasilkan dalam hasil kueri, dan syarat kueri apa pun yang ingin Anda terapkan. DynamoDB dapat menampilkan hasil dalam urutan menaik atau menurun.
Pertimbangkan data berikut yang dihasilkan dari `Query` yang meminta data game untuk aplikasi papan peringkat.
```
{
"TableName": "GameScores",
"IndexName": "GameTitleIndex",
"KeyConditionExpression": "GameTitle = :v_title",
"ExpressionAttributeValues": {
":v_title": {"S": "Meteor Blasters"}
},
"ProjectionExpression": "UserId, TopScore",
"ScanIndexForward": false
}
```
Dalam kueri ini:
+ DynamoDB *GameTitleIndex*mengakses, menggunakan kunci partisi untuk menemukan *GameTitle*item indeks untuk Meteor Blasters. Semua item indeks dengan kunci ini disimpan berdekatan satu sama lain untuk pengambilan cepat.
+ Dalam game ini, DynamoDB menggunakan indeks untuk mengakses semua IDs pengguna dan skor teratas untuk game ini.
+ Hasilnya ditampilkan dalam urutan menurun karena parameter `ScanIndexForward` diatur ke false.
### Memindai Indeks Sekunder Global
Anda dapat menggunakan operasi `Scan` untuk mengambil semua data dari indeks sekunder global. Anda harus memberikan nama tabel dasar dan nama indeks dalam permintaan. Dengan `Scan`, DynamoDB membaca semua data dalam indeks dan mengembalikannya ke aplikasi. Anda juga dapat meminta agar hanya sebagian data yang dikembalikan, dan data yang tersisa harus dibuang. Untuk melakukannya, gunakan parameter `FilterExpression` dari operasi `Scan`. Untuk informasi selengkapnya, lihat [Ekspresi filter untuk pemindaian](Scan.md#Scan.FilterExpression).
## Sinkronisasi data antara tabel dan Indeks Sekunder Global
DynamoDB otomatis menyinkronkan setiap indeks sekunder global dengan tabel dasarnya. Saat aplikasi menulis atau menghapus item dalam tabel, indeks sekunder global apa pun di tabel tersebut diperbarui secara asinkron, menggunakan model yang akhirnya konsisten. Aplikasi tidak pernah menulis langsung ke indeks. Namun, Anda harus memahami implikasi dari cara DynamoDB mempertahankan indeks ini.
Indeks sekunder global mewarisi mode read/write kapasitas dari tabel dasar. Untuk informasi selengkapnya, lihat [Pertimbangan saat mengganti mode kapasitas di DynamoDB](bp-switching-capacity-modes.md).
Saat membuat indeks sekunder global, Anda menentukan satu atau beberapa atribut kunci indeks dan jenis datanya. Ini berarti bahwa setiap kali Anda menulis item ke tabel dasar, jenis data untuk atribut tersebut harus cocok dengan jenis data skema kunci indeks. Dalam kasus `GameTitleIndex`, kunci partisi `GameTitle` dalam indeks didefinisikan sebagai jenis data `String`. Kunci urutan `TopScore` dalam indeks adalah jenis `Number`. Jika Anda mencoba menambahkan item ke tabel `GameScores` dan menentukan jenis data yang berbeda untuk `GameTitle` atau `TopScore`, DynamoDB mengembalikan `ValidationException` karena jenis data tidak cocok.
Saat Anda memasukkan atau menghapus item dalam tabel, indeks sekunder global pada tabel tersebut diperbarui secara konsisten. Perubahan pada data tabel disebarkan ke indeks sekunder global dalam sepersekian detik, dalam kondisi normal. Namun, dalam beberapa skenario kegagalan yang tidak terduga, penundaan penyebaran yang lebih lama mungkin terjadi. Oleh karena itu, aplikasi Anda perlu mengantisipasi dan menangani situasi ketika kueri pada indeks sekunder global mengembalikan hasil yang tidak mutakhir.
Jika menulis item ke tabel, Anda tidak perlu menentukan atribut untuk kunci urutan indeks sekunder global. Menggunakan `GameTitleIndex`, misalnya, Anda tidak perlu menentukan nilai atribut `TopScore` untuk menulis item baru ke tabel `GameScores`. Dalam hal ini, DynamoDB tidak menulis data apa pun ke indeks untuk item khusus ini.
Tabel dengan banyak indeks sekunder global menimbulkan biaya lebih tinggi untuk aktivitas tulis dibandingkan tabel dengan lebih sedikit indeks. Untuk informasi selengkapnya, lihat [Pertimbangan Throughput yang disediakan untuk Indeks Sekunder Global](#GSI.ThroughputConsiderations).
## Kelas tabel dengan Indeks Sekunder Global
Indeks sekunder global akan selalu menggunakan kelas tabel yang sama dengan tabel dasarnya. Setiap kali indeks sekunder global baru ditambahkan untuk tabel, indeks baru akan menggunakan kelas tabel yang sama dengan tabel dasarnya. Ketika kelas tabel diperbarui, semua indeks sekunder global terkait juga diperbarui.
## Pertimbangan Throughput yang disediakan untuk Indeks Sekunder Global
Saat membuat indeks sekunder global pada tabel mode yang disediakan, Anda harus menentukan unit kapasitas baca dan tulis untuk beban kerja yang diharapkan pada indeks tersebut. Pengaturan throughput yang disediakan pada indeks sekunder global terpisah dari pengaturan tabel dasarnya. Operasi `Query` pada indeks sekunder global menggunakan unit kapasitas baca dari indeks, bukan tabel dasar. Saat Anda memasukkan, memperbarui, atau menghapus item dalam tabel, indeks sekunder global pada tabel tersebut juga diperbarui. Pembaruan indeks ini menggunakan unit kapasitas tulis dari indeks, bukan dari tabel dasar.
Misalnya, jika Anda `Query` indeks sekunder global dan melebihi kapasitas baca yang disediakan, permintaan Anda akan mengalami throttling. Jika Anda melakukan aktivitas tulis berat pada tabel, tetapi indeks sekunder global pada tabel tersebut memiliki kapasitas tulis yang tidak memadai, aktivitas tulis pada tabel akan mengalami throttling.
**penting**
Untuk menghindari potensi throttling, kapasitas tulis yang disediakan untuk indeks sekunder global harus sama atau lebih besar dari kapasitas tulis tabel dasar karena pembaruan baru menulis ke tabel dasar dan indeks sekunder global.
Untuk melihat pengaturan throughput yang disediakan untuk indeks sekunder global, gunakan operasi `DescribeTable`. Informasi mendetail tentang semua indeks sekunder global tabel ditampilkan.
### Unit kapasitas baca
Indeks sekunder global mendukung bacaan akhir konsisten, yang masing-masing menggunakan setengah dari unit kapasitas baca. Artinya, satu kueri indeks sekunder global dapat mengambil hingga 2 × 4 KB = 8 KB per unit kapasitas baca.
Untuk kueri indeks sekunder global, DynamoDB menghitung aktivitas baca yang disediakan dengan cara yang sama seperti kueri terhadap tabel. Satu-satunya hal yang membedakan adalah penghitungan didasarkan pada ukuran entri indeks, bukan ukuran item dalam tabel dasar. Jumlah unit kapasitas baca adalah jumlah dari semua ukuran atribut yang diproyeksikan di semua item yang dikembalikan. Hasilnya kemudian dibulatkan ke batas 4 KB berikutnya. Untuk informasi selengkapnya tentang cara DynamoDB menghitung penggunaan throughput yang disediakan, lihat [DynamoDB menyediakan mode kapasitas](provisioned-capacity-mode.md).
Ukuran maksimum hasil yang dikembalikan oleh operasi `Query` adalah 1 MB. Ini termasuk ukuran semua nama dan nilai atribut di semua item yang dikembalikan.
Misalnya, pertimbangkan indeks sekunder global yang setiap itemnya berisi 2.000 byte data. Sekarang, anggaplah Anda `Query` indeks ini dan `KeyConditionExpression` kueri cocok dengan delapan item. Ukuran total item yang cocok adalah 2.000 byte × 8 item = 16.000 byte. Hasil ini kemudian dibulatkan ke batas 4 KB terdekat. Karena kueri indeks sekunder global pada akhirnya konsisten, biaya totalnya adalah 0,5 × (16 KB / 4 KB), atau 2 unit kapasitas baca.
### Unit kapasitas tulis
Ketika item dalam tabel ditambahkan, diperbarui, atau dihapus, dan indeks sekunder global terpengaruh oleh ini, indeks sekunder global menggunakan unit kapasitas tulis yang disediakan untuk operasi. Total biaya throughput yang disediakan untuk penulisan terdiri dari jumlah unit kapasitas tulis yang digunakan dengan menulis ke tabel dasar dan yang digunakan dengan memperbarui indeks sekunder global. Jika penulisan ke tabel tidak memerlukan pembaruan indeks sekunder global, tidak ada kapasitas tulis yang digunakan dari indeks.
Agar penulisan tabel berhasil, pengaturan throughput yang disediakan untuk tabel dan semua indeks sekunder globalnya harus memiliki kapasitas tulis yang memadai untuk mengakomodasi penulisan. Jika tidak, penulisan ke tabel akan mengalami throttling.
**penting**
Saat membuat Indeks Sekunder Global (GSI), operasi tulis ke tabel dasar dapat dibatasi jika aktivitas GSI yang dihasilkan dari penulisan ke tabel dasar melebihi kapasitas tulis yang disediakan GSI. Pelambatan ini memengaruhi semua operasi penulisan, mulai dari proses pengindeksan hingga berpotensi mengganggu beban kerja produksi Anda. Untuk informasi selengkapnya, lihat [Pemecahan masalah pembatasan di Amazon](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TroubleshootingThrottling.html) DynamoDB.
Biaya tulis item ke indeks sekunder global tergantung pada beberapa faktor:
+ Jika Anda menulis item baru ke tabel yang menentukan atribut yang diindeks, atau Anda memperbarui item yang ada untuk menentukan atribut terindeks yang sebelumnya tidak ditentukan, satu operasi tulis diperlukan untuk memasukkan item ke dalam indeks.
+ Jika pembaruan pada tabel mengubah nilai atribut kunci yang diindeks (dari A menjadi B), diperlukan dua penulisan, satu untuk menghapus item sebelumnya dari indeks dan satu lagi untuk memasukkan item baru ke dalam indeks.
+ Jika suatu item ada dalam indeks, tetapi penulisan ke tabel menyebabkan atribut yang diindeks terhapus, satu penulisan diperlukan untuk menghapus proyeksi item lama dari indeks.
+ Jika item tidak ada dalam indeks sebelum atau setelah item diperbarui, tidak ada biaya penulisan tambahan untuk indeks tersebut.
+ Jika pembaruan pada tabel hanya mengubah nilai atribut yang diproyeksikan dalam skema kunci indeks, tetapi tidak mengubah nilai atribut kunci yang diindeks, satu penulisan diperlukan untuk memperbarui nilai atribut yang diproyeksikan ke dalam indeks.
Semua faktor ini mengasumsikan bahwa ukuran setiap item dalam indeks kurang dari atau sama dengan ukuran item 1 KB untuk menghitung unit kapasitas tulis. Entri indeks yang lebih besar memerlukan unit kapasitas tulis tambahan. Anda dapat meminimalkan biaya penulisan dengan mempertimbangkan atribut yang perlu dikembalikan oleh kueri dan hanya memproyeksikan atribut tersebut ke dalam indeks.
## Pertimbangan penyimpanan untuk Indeks Sekunder Global
Saat aplikasi menulis item ke tabel, DynamoDB otomatis menyalin subset atribut yang benar ke indeks sekunder global tempat atribut tersebut akan muncul. AWS Akun Anda dikenakan biaya untuk penyimpanan item di tabel dasar dan juga untuk penyimpanan atribut dalam indeks sekunder global apa pun di tabel itu.
Jumlah ruang yang digunakan oleh item indeks adalah jumlah dari berikut ini:
+ Ukuran kunci primer tabel dasar dalam byte (kunci partisi dan kunci urutan)
+ Ukuran atribut kunci indeks dalam byte
+ Ukuran atribut yang diproyeksikan dalam byte (jika ada)
+ 100 byte dari overhead per item indeks
Untuk memperkirakan kebutuhan penyimpanan indeks sekunder global, Anda dapat memperkirakan ukuran rata-rata item dalam indeks lalu mengalikannya dengan jumlah item dalam tabel dasar yang memiliki atribut kunci indeks sekunder global.
Jika tabel berisi item di mana atribut tertentu tidak didefinisikan, tetapi atribut tersebut didefinisikan sebagai kunci partisi indeks atau kunci sortir, DynamoDB tidak menulis data apa pun untuk item tersebut ke indeks.
# Pola desain
Pola desain memberikan solusi yang terbukti untuk tantangan umum saat bekerja dengan indeks sekunder global. Pola-pola ini membantu Anda membangun aplikasi yang efisien dan dapat diskalakan dengan menunjukkan kepada Anda cara menyusun indeks Anda untuk kasus penggunaan tertentu.
Setiap pola menyertakan panduan implementasi lengkap dengan contoh kode, praktik terbaik, dan kasus penggunaan dunia nyata untuk membantu Anda menerapkan pola ke aplikasi Anda sendiri.
**Topics**
+ [Kunci multi-atribut](GSI.DesignPattern.MultiAttributeKeys.md)
# Pola kunci multi-atribut
## Gambaran umum
Kunci multi-atribut memungkinkan Anda membuat partisi Global Secondary Index (GSI) dan mengurutkan kunci masing-masing terdiri dari hingga empat atribut. Ini mengurangi kode sisi klien dan membuatnya lebih mudah untuk awalnya memodelkan data dan menambahkan pola akses baru nanti.
Pertimbangkan skenario umum: untuk membuat GSI yang menanyakan item dengan beberapa atribut hierarkis, Anda secara tradisional perlu membuat kunci sintetis dengan menggabungkan nilai. Misalnya, dalam aplikasi game, untuk menanyakan pertandingan turnamen berdasarkan turnamen, wilayah, dan putaran, Anda dapat membuat kunci partisi GSI sintetis seperti TURNAMEN \$1 WINTER2 024 \$1REGION \$1NA -EAST dan kunci pengurutan sintetis seperti ROUND \$1SEMIFINALS \$1BRACKET \$1UPPER. Pendekatan ini berfungsi, tetapi memerlukan penggabungan string saat menulis data, mengurai saat membaca, dan mengisi kembali kunci sintetis di semua item yang ada jika Anda menambahkan GSI ke tabel yang ada. Hal ini membuat kode lebih berantakan dan menantang untuk menjaga keamanan tipe pada masing-masing komponen kunci.
Kunci multi-atribut memecahkan masalah ini untuk GSIs. Anda menentukan kunci partisi GSI Anda menggunakan beberapa atribut yang ada seperti TournamentID dan wilayah. DynamoDB menangani logika kunci komposit secara otomatis, hashing mereka bersama-sama untuk distribusi data. Anda menulis item menggunakan atribut alami dari model domain Anda, dan GSI secara otomatis mengindeksnya. Tidak ada penggabungan, tidak ada penguraian, tidak ada penimbunan ulang. Kode Anda tetap bersih, data Anda tetap diketik, dan kueri Anda tetap sederhana. Pendekatan ini sangat berguna ketika Anda memiliki data hierarkis dengan pengelompokan atribut alami (seperti turnamen → wilayah → putaran, atau organisasi → departemen → tim).
## Contoh aplikasi
Panduan ini berjalan melalui pembangunan sistem pelacakan pertandingan turnamen untuk platform esports. Platform perlu menanyakan kecocokan secara efisien di berbagai dimensi: berdasarkan turnamen dan wilayah untuk manajemen braket, oleh pemain untuk riwayat pertandingan, dan berdasarkan tanggal untuk penjadwalan.
## Model Data
Dalam panduan ini, sistem pelacakan pertandingan turnamen mendukung tiga pola akses utama, masing-masing membutuhkan struktur kunci yang berbeda:
**Pola akses 1:** Cari kecocokan tertentu berdasarkan ID uniknya
+ **Solusi:** Tabel dasar dengan `matchId` kunci partisi
**Pola akses 2:** Kueri semua pertandingan untuk turnamen dan wilayah tertentu, secara opsional memfilter berdasarkan putaran, braket, atau pertandingan
+ **Solusi:** Indeks Sekunder Global dengan kunci partisi multi-atribut (`tournamentId`\$1`region`) dan kunci pengurutan multi-atribut (`round`\$1 \$1`bracket`) `matchId`
+ **Contoh kueri:** “Semua WINTER2 024 pertandingan di wilayah NA-EAST” atau “Semua Semifinal cocok di braket UPPER untuk 024/NA-EAST” WINTER2
**Pola akses 3:** Menanyakan riwayat pertandingan pemain, secara opsional memfilter berdasarkan rentang tanggal atau putaran turnamen
+ **Solusi:** Indeks Sekunder Global dengan kunci partisi tunggal (`player1Id`) dan kunci pengurutan multi-atribut (`matchDate`\$1`round`)
+ **Contoh pertanyaan:** “Semua pertandingan untuk pemain 101" atau “Pertandingan Pemain 101 pada Januari 2024"
Perbedaan utama antara pendekatan tradisional dan multi-atribut menjadi jelas saat memeriksa struktur item:
**Pendekatan Indeks Sekunder Global Tradisional (kunci gabungan):**
```
// Manual concatenation required for GSI keys
const item = {
matchId: 'match-001', // Base table PK
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
// Synthetic keys needed for GSI
GSI_PK: `TOURNAMENT#${tournamentId}#REGION#${region}`, // Must concatenate
GSI_SK: `${round}#${bracket}#${matchId}`, // Must concatenate
// ... other attributes
};
```
**Pendekatan Indeks Sekunder Global multi-atribut (kunci asli):**
```
// Use existing attributes directly - no concatenation needed
const item = {
matchId: 'match-001', // Base table PK
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
matchDate: '2024-01-18',
// No synthetic keys needed - GSI uses existing attributes directly
// ... other attributes
};
```
Dengan kunci multi-atribut, Anda menulis item sekali dengan atribut domain alami. DynamoDB secara otomatis mengindeks mereka di GSIs beberapa tanpa memerlukan kunci gabungan sintetis.
**Skema tabel dasar:**
+ Kunci partisi: `matchId` (1 atribut)
**Skema Indeks Sekunder Global (TournamentRegionIndex dengan kunci multi-atribut):**
+ Kunci partisi:`tournamentId`, `region` (2 atribut)
+ Kunci sortir:`round`,`bracket`, `matchId` (3 atribut)
**Skema Indeks Sekunder Global (PlayerMatchHistoryIndex dengan kunci multi-atribut):**
+ Kunci partisi: `player1Id` (1 atribut)
+ Kunci sortir:`matchDate`, `round` (2 atribut)
### Tabel dasar: TournamentMatches
| MatchID (PK) | TurnamenID | region | bulat | tanda kurung | Player1id | Player2id | MatchDate | pemenang | skor |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| pertandingan-001 | WINTER2024 | NA-TIMUR | FINAL | KEJUARAAN | 101 | 103 | 2024-01-20 | 101 | 3-1 |
| pertandingan-002 | WINTER2024 | NA-TIMUR | SEMIFINAL | ATAS | 101 | 105 | 2024-01-18 | 101 | 3-2 |
| pertandingan-003 | WINTER2024 | NA-TIMUR | SEMIFINAL | ATAS | 103 | 107 | 2024-01-18 | 103 | 3-0 |
| pertandingan-004 | WINTER2024 | NA-TIMUR | PEREMPAT FINAL | ATAS | 101 | 109 | 2024-01-15 | 101 | 3-1 |
| pertandingan-005 | WINTER2024 | NA-BARAT | FINAL | KEJUARAAN | 102 | 104 | 2024-01-20 | 102 | 3-2 |
| pertandingan-006 | WINTER2024 | NA-BARAT | SEMIFINAL | ATAS | 102 | 106 | 2024-01-18 | 102 | 3-1 |
| pertandingan-007 | SPRING2024 | NA-TIMUR | PEREMPAT FINAL | ATAS | 101 | 108 | 2024-03-15 | 101 | 3-0 |
| pertandingan-008 | SPRING2024 | NA-TIMUR | PEREMPAT FINAL | LEBIH RENDAH | 103 | 110 | 2024-03-15 | 103 | 3-2 |
### GSI: TournamentRegionIndex (kunci multi-atribut)
| TurnamenID (PK) | wilayah (PK) | bulat (SK) | braket (SK) | MatchID (SK) | Player1id | Player2id | MatchDate | pemenang | skor |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| WINTER2024 | NA-TIMUR | FINAL | KEJUARAAN | pertandingan-001 | 101 | 103 | 2024-01-20 | 101 | 3-1 |
| WINTER2024 | NA-TIMUR | PEREMPAT FINAL | ATAS | pertandingan-004 | 101 | 109 | 2024-01-15 | 101 | 3-1 |
| WINTER2024 | NA-TIMUR | SEMIFINAL | ATAS | pertandingan-002 | 101 | 105 | 2024-01-18 | 101 | 3-2 |
| WINTER2024 | NA-TIMUR | SEMIFINAL | ATAS | pertandingan-003 | 103 | 107 | 2024-01-18 | 103 | 3-0 |
| WINTER2024 | NA-BARAT | FINAL | KEJUARAAN | pertandingan-005 | 102 | 104 | 2024-01-20 | 102 | 3-2 |
| WINTER2024 | NA-BARAT | SEMIFINAL | ATAS | pertandingan-006 | 102 | 106 | 2024-01-18 | 102 | 3-1 |
| SPRING2024 | NA-TIMUR | PEREMPAT FINAL | LEBIH RENDAH | pertandingan-008 | 103 | 110 | 2024-03-15 | 103 | 3-2 |
| SPRING2024 | NA-TIMUR | PEREMPAT FINAL | ATAS | pertandingan-007 | 101 | 108 | 2024-03-15 | 101 | 3-0 |
### GSI: PlayerMatchHistoryIndex (kunci multi-atribut)
| Player1ID (PK) | MatchDate (SK) | bulat (SK) | TurnamenID | region | tanda kurung | MatchID | Player2id | pemenang | skor |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 101 | 2024-01-15 | PEREMPAT FINAL | WINTER2024 | NA-TIMUR | ATAS | pertandingan-004 | 109 | 101 | 3-1 |
| 101 | 2024-01-18 | SEMIFINAL | WINTER2024 | NA-TIMUR | ATAS | pertandingan-002 | 105 | 101 | 3-2 |
| 101 | 2024-01-20 | FINAL | WINTER2024 | NA-TIMUR | KEJUARAAN | pertandingan-001 | 103 | 101 | 3-1 |
| 101 | 2024-03-15 | PEREMPAT FINAL | SPRING2024 | NA-TIMUR | ATAS | pertandingan-007 | 108 | 101 | 3-0 |
| 102 | 2024-01-18 | SEMIFINAL | WINTER2024 | NA-BARAT | ATAS | pertandingan-006 | 106 | 102 | 3-1 |
| 102 | 2024-01-20 | FINAL | WINTER2024 | NA-BARAT | KEJUARAAN | pertandingan-005 | 104 | 102 | 3-2 |
| 103 | 2024-01-18 | SEMIFINAL | WINTER2024 | NA-TIMUR | ATAS | pertandingan-003 | 107 | 103 | 3-0 |
| 103 | 2024-03-15 | PEREMPAT FINAL | SPRING2024 | NA-TIMUR | LEBIH RENDAH | pertandingan-008 | 110 | 103 | 3-2 |
## Prasyarat
Sebelum Anda mulai, pastikan Anda memiliki:
### Akun dan izin
+ AWS Akun aktif ([buat satu di sini](https://aws.amazon.com/free/) jika diperlukan)
+ Izin IAM untuk operasi DynamoDB:
+ `dynamodb:CreateTable`
+ `dynamodb:DeleteTable`
+ `dynamodb:DescribeTable`
+ `dynamodb:PutItem`
+ `dynamodb:Query`
+ `dynamodb:BatchWriteItem`
**catatan**
**Catatan Keamanan:** Untuk penggunaan produksi, buat kebijakan IAM khusus hanya dengan izin yang Anda butuhkan. Untuk tutorial ini, Anda dapat menggunakan kebijakan AWS terkelola`AmazonDynamoDBFullAccessV2`.
### Lingkungan Pengembangan
+ Node.js diinstal pada mesin Anda
+ AWS kredensil yang dikonfigurasi menggunakan salah satu metode ini:
**Opsi 1: AWS CLI**
```
aws configure
```
**Opsi 2: Variabel Lingkungan**
```
export AWS_ACCESS_KEY_ID=your_access_key_here
export AWS_SECRET_ACCESS_KEY=your_secret_key_here
export AWS_DEFAULT_REGION=us-east-1
```
### Instal Paket yang Diperlukan
```
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
```
## Implementasi
### Langkah 1: Buat tabel dengan GSIs menggunakan tombol multi-atribut
Buat tabel dengan struktur kunci dasar sederhana dan GSIs yang menggunakan kunci multi-atribut.
#### Contoh kode
```
import { DynamoDBClient, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const response = await client.send(new CreateTableCommand({
TableName: 'TournamentMatches',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'matchId', KeyType: 'HASH' } // Simple PK
],
AttributeDefinitions: [
{ AttributeName: 'matchId', AttributeType: 'S' },
{ AttributeName: 'tournamentId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'round', AttributeType: 'S' },
{ AttributeName: 'bracket', AttributeType: 'S' },
{ AttributeName: 'player1Id', AttributeType: 'S' },
{ AttributeName: 'matchDate', AttributeType: 'S' }
],
// GSIs with multi-attribute keys
GlobalSecondaryIndexes: [
{
IndexName: 'TournamentRegionIndex',
KeySchema: [
{ AttributeName: 'tournamentId', KeyType: 'HASH' }, // GSI PK attribute 1
{ AttributeName: 'region', KeyType: 'HASH' }, // GSI PK attribute 2
{ AttributeName: 'round', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'bracket', KeyType: 'RANGE' }, // GSI SK attribute 2
{ AttributeName: 'matchId', KeyType: 'RANGE' } // GSI SK attribute 3
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'PlayerMatchHistoryIndex',
KeySchema: [
{ AttributeName: 'player1Id', KeyType: 'HASH' }, // GSI PK
{ AttributeName: 'matchDate', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'round', KeyType: 'RANGE' } // GSI SK attribute 2
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}));
console.log("Table with multi-attribute GSI keys created successfully");
```
**Keputusan desain utama:**
**Tabel dasar:** Tabel dasar menggunakan kunci `matchId` partisi sederhana untuk pencarian kecocokan langsung, menjaga struktur tabel dasar tetap mudah sementara GSIs menyediakan pola kueri yang kompleks.
**TournamentRegionIndex Indeks Sekunder Global: Indeks** Sekunder `TournamentRegionIndex` Global menggunakan `tournamentId` \$1 `region` sebagai kunci partisi multi-atribut, menciptakan isolasi wilayah turnamen di mana data didistribusikan oleh hash dari kedua atribut yang digabungkan, memungkinkan kueri yang efisien dalam konteks wilayah turnamen tertentu. Kunci pengurutan multi-atribut (`round`\$1 `bracket` \$1`matchId`) menyediakan penyortiran hierarkis yang mendukung kueri di setiap tingkat hierarki dengan urutan alami dari umum (putaran) ke spesifik (ID kecocokan).
**PlayerMatchHistoryIndex Indeks Sekunder Global: Indeks** Sekunder `PlayerMatchHistoryIndex` Global mengatur ulang data berdasarkan pemain menggunakan `player1Id` kunci partisi, memungkinkan kueri lintas-turnamen untuk pemain tertentu. Kunci pengurutan multi-atribut (`matchDate`\$1`round`) menyediakan urutan kronologis dengan kemampuan untuk memfilter berdasarkan rentang tanggal atau putaran turnamen tertentu.
### Langkah 2: Masukkan data dengan atribut asli
Tambahkan data pertandingan turnamen menggunakan atribut alami. GSI akan secara otomatis mengindeks atribut ini tanpa memerlukan kunci sintetis.
#### Contoh kode
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Tournament match data - no synthetic keys needed for GSIs
const matches = [
// Winter 2024 Tournament, NA-EAST region
{
matchId: 'match-001',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'FINALS',
bracket: 'CHAMPIONSHIP',
player1Id: '101',
player2Id: '103',
matchDate: '2024-01-20',
winner: '101',
score: '3-1'
},
{
matchId: 'match-002',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '105',
matchDate: '2024-01-18',
winner: '101',
score: '3-2'
},
{
matchId: 'match-003',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '103',
player2Id: '107',
matchDate: '2024-01-18',
winner: '103',
score: '3-0'
},
{
matchId: 'match-004',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '109',
matchDate: '2024-01-15',
winner: '101',
score: '3-1'
},
// Winter 2024 Tournament, NA-WEST region
{
matchId: 'match-005',
tournamentId: 'WINTER2024',
region: 'NA-WEST',
round: 'FINALS',
bracket: 'CHAMPIONSHIP',
player1Id: '102',
player2Id: '104',
matchDate: '2024-01-20',
winner: '102',
score: '3-2'
},
{
matchId: 'match-006',
tournamentId: 'WINTER2024',
region: 'NA-WEST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '102',
player2Id: '106',
matchDate: '2024-01-18',
winner: '102',
score: '3-1'
},
// Spring 2024 Tournament, NA-EAST region
{
matchId: 'match-007',
tournamentId: 'SPRING2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '108',
matchDate: '2024-03-15',
winner: '101',
score: '3-0'
},
{
matchId: 'match-008',
tournamentId: 'SPRING2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'LOWER',
player1Id: '103',
player2Id: '110',
matchDate: '2024-03-15',
winner: '103',
score: '3-2'
}
];
// Insert all matches
for (const match of matches) {
await docClient.send(new PutCommand({
TableName: 'TournamentMatches',
Item: match
}));
console.log(`Added: ${match.matchId} - ${match.tournamentId}/${match.region} - ${match.round} ${match.bracket}`);
}
console.log(`\nInserted ${matches.length} tournament matches`);
console.log("No synthetic keys created - GSIs use native attributes automatically");
```
**Struktur data dijelaskan:**
**Penggunaan atribut alami:** Setiap atribut mewakili konsep turnamen nyata tanpa penggabungan string atau penguraian yang diperlukan, menyediakan pemetaan langsung ke model domain.
**Pengindeksan Indeks Sekunder Global Otomatis:** GSIs Secara otomatis mengindeks item menggunakan atribut yang ada (`tournamentId``region`,,`round`,`bracket`, `matchId` untuk TournamentRegionIndex dan`player1Id`,`matchDate`, `round` untuk PlayerMatchHistoryIndex) tanpa memerlukan kunci gabungan sintetis.
**Tidak perlu pengisian ulang:** Saat Anda menambahkan Indeks Sekunder Global baru dengan kunci multi-atribut ke tabel yang ada, DynamoDB secara otomatis mengindeks semua item yang ada menggunakan atribut alamiahnya—tidak perlu memperbarui item dengan kunci sintetis.
### Langkah 3: Kueri Indeks Sekunder TournamentRegionIndex Global dengan semua atribut kunci partisi
Contoh ini menanyakan Indeks Sekunder TournamentRegionIndex Global yang memiliki kunci partisi multi-atribut (`tournamentId`\$1`region`). Semua atribut kunci partisi harus ditentukan dengan kondisi kesetaraan dalam kueri—Anda tidak dapat melakukan kueri hanya dengan `tournamentId` sendirian atau menggunakan operator ketidaksetaraan pada atribut kunci partisi.
#### Contoh kode
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query GSI: All matches for WINTER2024 tournament in NA-EAST region
const response = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
ExpressionAttributeNames: {
'#region': 'region', // 'region' is a reserved keyword
'#tournament': 'tournament'
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST'
}
}));
console.log(`Found ${response.Items.length} matches for WINTER2024/NA-EAST:\n`);
response.Items.forEach(match => {
console.log(` ${match.round} | ${match.bracket} | ${match.matchId}`);
console.log(` Players: ${match.player1Id} vs ${match.player2Id}`);
console.log(` Winner: ${match.winner}, Score: ${match.score}\n`);
});
```
**Output yang diharapkan:**
```
Found 4 matches for WINTER2024/NA-EAST:
FINALS | CHAMPIONSHIP | match-001
Players: 101 vs 103
Winner: 101, Score: 3-1
QUARTERFINALS | UPPER | match-004
Players: 101 vs 109
Winner: 101, Score: 3-1
SEMIFINALS | UPPER | match-002
Players: 101 vs 105
Winner: 101, Score: 3-2
SEMIFINALS | UPPER | match-003
Players: 103 vs 107
Winner: 103, Score: 3-0
```
**Kueri tidak valid:**
```
// Missing region attribute
KeyConditionExpression: 'tournamentId = :tournament'
// Using inequality on partition key attribute
KeyConditionExpression: 'tournamentId = :tournament AND #region > :region'
```
**Kinerja:** Kunci partisi multi-atribut di-hash bersama, memberikan kinerja pencarian O (1) yang sama dengan kunci atribut tunggal.
### Langkah 4: Kueri kunci pengurutan Indeks Sekunder Global left-to-right
Atribut kunci sortir harus ditanyakan left-to-right dalam urutan yang ditentukan dalam Indeks Sekunder Global. Contoh ini menunjukkan kueri TournamentRegionIndex pada tingkat hierarki yang berbeda: memfilter hanya dengan, dengan `round` \$1 `round``bracket`, atau dengan ketiga atribut kunci pengurutan. Anda tidak dapat melewati atribut di tengah—misalnya, Anda tidak dapat melakukan kueri dengan `round` dan `matchId` saat melompati. `bracket`
#### Contoh kode
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: Filter by first sort key attribute (round)
console.log("Query 1: All SEMIFINALS matches");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS'
}
}));
console.log(` Found ${query1.Items.length} matches\n`);
// Query 2: Filter by first two sort key attributes (round + bracket)
console.log("Query 2: SEMIFINALS UPPER bracket matches");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':bracket': 'UPPER'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Filter by all three sort key attributes (round + bracket + matchId)
console.log("Query 3: Specific match in SEMIFINALS UPPER bracket");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket AND matchId = :matchId',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':bracket': 'UPPER',
':matchId': 'match-002'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: INVALID - skipping round
console.log("Query 4: Attempting to skip first sort key attribute (WILL FAIL)");
try {
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':bracket': 'UPPER'
}
}));
} catch (error) {
console.log(` Error: ${error.message}`);
console.log(` Cannot skip sort key attributes - must query left-to-right\n`);
}
```
**Output yang diharapkan:**
```
Query 1: All SEMIFINALS matches
Found 2 matches
Query 2: SEMIFINALS UPPER bracket matches
Found 2 matches
Query 3: Specific match in SEMIFINALS UPPER bracket
Found 1 matches
Query 4: Attempting to skip first sort key attribute (WILL FAIL)
Error: Query key condition not supported
Cannot skip sort key attributes - must query left-to-right
```
**Left-to-right aturan kueri:** Anda harus menanyakan atribut secara berurutan dari kiri ke kanan, tanpa melewatkan apa pun.
**Pola yang valid:**
+ Atribut pertama saja: `round = 'SEMIFINALS'`
+ Dua atribut pertama: `round = 'SEMIFINALS' AND bracket = 'UPPER'`
+ Ketiga atribut: `round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId = 'match-002'`
**Pola tidak valid:**
+ Melewatkan atribut pertama: `bracket = 'UPPER'` (melompat-lompat)
+ Menanyakan di luar pesanan: `matchId = 'match-002' AND round = 'SEMIFINALS'`
+ Meninggalkan celah: `round = 'SEMIFINALS' AND matchId = 'match-002'` (melompati braket)
**catatan**
**Tip desain:** Urutkan atribut kunci urutan dari yang paling umum hingga yang paling spesifik untuk memaksimalkan fleksibilitas kueri.
### Langkah 5: Gunakan kondisi ketidaksetaraan pada kunci pengurutan Indeks Sekunder Global
Kondisi ketidaksetaraan harus menjadi kondisi terakhir dalam kueri Anda. Contoh ini menunjukkan menggunakan operator perbandingan (`>=`,`BETWEEN`) dan awalan pencocokan (`begins_with()`) pada atribut kunci sortir. Setelah Anda menggunakan operator ketidaksetaraan, Anda tidak dapat menambahkan kondisi kunci pengurutan tambahan setelahnya — ketidaksetaraan harus menjadi kondisi akhir dalam ekspresi kondisi kunci Anda.
#### Contoh kode
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: Round comparison (inequality on first sort key attribute)
console.log("Query 1: Matches from QUARTERFINALS onwards");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round >= :round',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'QUARTERFINALS'
}
}));
console.log(` Found ${query1.Items.length} matches\n`);
// Query 2: Round range with BETWEEN
console.log("Query 2: Matches between QUARTERFINALS and SEMIFINALS");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round BETWEEN :start AND :end',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':start': 'QUARTERFINALS',
':end': 'SEMIFINALS'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Prefix matching with begins_with (treated as inequality)
console.log("Query 3: Matches in brackets starting with 'U'");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND begins_with(bracket, :prefix)',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':prefix': 'U'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: INVALID - condition after inequality
console.log("Query 4: Attempting condition after inequality (WILL FAIL)");
try {
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round > :round AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'QUARTERFINALS',
':bracket': 'UPPER'
}
}));
} catch (error) {
console.log(` Error: ${error.message}`);
console.log(` Cannot add conditions after inequality - it must be last\n`);
}
```
**Aturan operator ketidaksetaraan:** Anda dapat menggunakan operator perbandingan (`>`,,`>=`,`<=`)`<`, `BETWEEN` untuk kueri rentang, dan `begins_with()` untuk pencocokan awalan. Ketidaksetaraan harus menjadi kondisi terakhir dalam kueri Anda.
**Pola yang valid:**
+ Kondisi kesetaraan diikuti oleh ketidaksetaraan: `round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId > 'match-001'`
+ Ketimpangan pada atribut pertama: `round BETWEEN 'QUARTERFINALS' AND 'SEMIFINALS'`
+ Pencocokan awalan sebagai kondisi akhir: `round = 'SEMIFINALS' AND begins_with(bracket, 'U')`
**Pola tidak valid:**
+ Menambahkan kondisi setelah ketidaksetaraan: `round > 'QUARTERFINALS' AND bracket = 'UPPER'`
+ Menggunakan beberapa ketidaksetaraan: `round > 'QUARTERFINALS' AND bracket > 'L'`
**penting**
`begins_with()`diperlakukan sebagai kondisi ketidaksetaraan, jadi tidak ada kondisi kunci pengurutan tambahan yang dapat mengikutinya.
### Langkah 6: Kueri Indeks Sekunder PlayerMatchHistoryIndex Global dengan kunci pengurutan multi-atribut
Contoh ini menanyakan PlayerMatchHistoryIndex yang memiliki kunci partisi tunggal (`player1Id`) dan kunci sortir multi-atribut (`matchDate`\$1`round`). Hal ini memungkinkan analisis lintas-turnamen dengan menanyakan semua pertandingan untuk pemain tertentu tanpa mengetahui turnamen IDs — sedangkan tabel dasar akan membutuhkan kueri terpisah per kombinasi turnamen-wilayah.
#### Contoh kode
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: All matches for Player 101 across all tournaments
console.log("Query 1: All matches for Player 101");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player',
ExpressionAttributeValues: {
':player': '101'
}
}));
console.log(` Found ${query1.Items.length} matches for Player 101:`);
query1.Items.forEach(match => {
console.log(` ${match.tournamentId}/${match.region} - ${match.matchDate} - ${match.round}`);
});
console.log();
// Query 2: Player 101 matches on specific date
console.log("Query 2: Player 101 matches on 2024-01-18");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate = :date',
ExpressionAttributeValues: {
':player': '101',
':date': '2024-01-18'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Player 101 SEMIFINALS matches on specific date
console.log("Query 3: Player 101 SEMIFINALS matches on 2024-01-18");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate = :date AND round = :round',
ExpressionAttributeValues: {
':player': '101',
':date': '2024-01-18',
':round': 'SEMIFINALS'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: Player 101 matches in date range
console.log("Query 4: Player 101 matches in January 2024");
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate BETWEEN :start AND :end',
ExpressionAttributeValues: {
':player': '101',
':start': '2024-01-01',
':end': '2024-01-31'
}
}));
console.log(` Found ${query4.Items.length} matches\n`);
```
## Variasi pola
### Data deret waktu dengan kunci multi-atribut
Optimalkan kueri deret waktu dengan atribut waktu hierarkis
#### Contoh kode
```
{
TableName: 'IoTReadings',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'readingId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'readingId', AttributeType: 'S' },
{ AttributeName: 'deviceId', AttributeType: 'S' },
{ AttributeName: 'locationId', AttributeType: 'S' },
{ AttributeName: 'year', AttributeType: 'S' },
{ AttributeName: 'month', AttributeType: 'S' },
{ AttributeName: 'day', AttributeType: 'S' },
{ AttributeName: 'timestamp', AttributeType: 'S' }
],
// GSI with multi-attribute keys for time-series queries
GlobalSecondaryIndexes: [{
IndexName: 'DeviceLocationTimeIndex',
KeySchema: [
{ AttributeName: 'deviceId', KeyType: 'HASH' },
{ AttributeName: 'locationId', KeyType: 'HASH' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' },
{ AttributeName: 'day', KeyType: 'RANGE' },
{ AttributeName: 'timestamp', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}
// Query patterns enabled via GSI:
// - All readings for device in location
// - Readings for specific year
// - Readings for specific month in year
// - Readings for specific day
// - Readings in time range
```
**Manfaat:** Hirarki waktu alami (tahun → bulan → hari → stempel waktu) memungkinkan kueri yang efisien setiap saat perincian tanpa penguraian atau manipulasi tanggal. Global Secondary Index secara otomatis mengindeks semua bacaan menggunakan atribut waktu alaminya.
### Pesanan e-niaga dengan kunci multi-atribut
Lacak pesanan dengan berbagai dimensi
#### Contoh kode
```
{
TableName: 'Orders',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'orderId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'orderId', AttributeType: 'S' },
{ AttributeName: 'sellerId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'orderDate', AttributeType: 'S' },
{ AttributeName: 'category', AttributeType: 'S' },
{ AttributeName: 'customerId', AttributeType: 'S' },
{ AttributeName: 'orderStatus', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'SellerRegionIndex',
KeySchema: [
{ AttributeName: 'sellerId', KeyType: 'HASH' },
{ AttributeName: 'region', KeyType: 'HASH' },
{ AttributeName: 'orderDate', KeyType: 'RANGE' },
{ AttributeName: 'category', KeyType: 'RANGE' },
{ AttributeName: 'orderId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'CustomerOrdersIndex',
KeySchema: [
{ AttributeName: 'customerId', KeyType: 'HASH' },
{ AttributeName: 'orderDate', KeyType: 'RANGE' },
{ AttributeName: 'orderStatus', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// SellerRegionIndex GSI queries:
// - Orders by seller and region
// - Orders by seller, region, and date
// - Orders by seller, region, date, and category
// CustomerOrdersIndex GSI queries:
// - Customer's orders
// - Customer's orders by date
// - Customer's orders by date and status
```
### Data organisasi hierarkis
Model hierarki organisasi
#### Contoh kode
```
{
TableName: 'Employees',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'employeeId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'employeeId', AttributeType: 'S' },
{ AttributeName: 'companyId', AttributeType: 'S' },
{ AttributeName: 'divisionId', AttributeType: 'S' },
{ AttributeName: 'departmentId', AttributeType: 'S' },
{ AttributeName: 'teamId', AttributeType: 'S' },
{ AttributeName: 'skillCategory', AttributeType: 'S' },
{ AttributeName: 'skillLevel', AttributeType: 'S' },
{ AttributeName: 'yearsExperience', AttributeType: 'N' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'OrganizationIndex',
KeySchema: [
{ AttributeName: 'companyId', KeyType: 'HASH' },
{ AttributeName: 'divisionId', KeyType: 'HASH' },
{ AttributeName: 'departmentId', KeyType: 'RANGE' },
{ AttributeName: 'teamId', KeyType: 'RANGE' },
{ AttributeName: 'employeeId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'SkillsIndex',
KeySchema: [
{ AttributeName: 'skillCategory', KeyType: 'HASH' },
{ AttributeName: 'skillLevel', KeyType: 'RANGE' },
{ AttributeName: 'yearsExperience', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'INCLUDE', NonKeyAttributes: ['employeeId', 'name'] }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// OrganizationIndex GSI query patterns:
// - All employees in company/division
// - Employees in specific department
// - Employees in specific team
// SkillsIndex GSI query patterns:
// - Employees by skill and experience level
```
### Kunci multi-atribut jarang
Gabungkan kunci multi-atribut untuk membuat GSI yang jarang
#### Contoh kode
```
{
TableName: 'Products',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'productId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'productId', AttributeType: 'S' },
{ AttributeName: 'categoryId', AttributeType: 'S' },
{ AttributeName: 'subcategoryId', AttributeType: 'S' },
{ AttributeName: 'averageRating', AttributeType: 'N' },
{ AttributeName: 'reviewCount', AttributeType: 'N' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'CategoryIndex',
KeySchema: [
{ AttributeName: 'categoryId', KeyType: 'HASH' },
{ AttributeName: 'subcategoryId', KeyType: 'HASH' },
{ AttributeName: 'productId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'ReviewedProductsIndex',
KeySchema: [
{ AttributeName: 'categoryId', KeyType: 'HASH' },
{ AttributeName: 'averageRating', KeyType: 'RANGE' }, // Optional attribute
{ AttributeName: 'reviewCount', KeyType: 'RANGE' } // Optional attribute
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// Only products with reviews appear in ReviewedProductsIndex GSI
// Automatic filtering without application logic
// Multi-attribute sort key enables rating and count queries
```
### SaaS multi-tenancy
Platform SaaS multi-penyewa dengan isolasi pelanggan
#### Contoh kode
```
// Table design
{
TableName: 'SaasData',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'resourceId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'resourceId', AttributeType: 'S' },
{ AttributeName: 'tenantId', AttributeType: 'S' },
{ AttributeName: 'customerId', AttributeType: 'S' },
{ AttributeName: 'resourceType', AttributeType: 'S' }
],
// GSI with multi-attribute keys for tenant-customer isolation
GlobalSecondaryIndexes: [{
IndexName: 'TenantCustomerIndex',
KeySchema: [
{ AttributeName: 'tenantId', KeyType: 'HASH' },
{ AttributeName: 'customerId', KeyType: 'HASH' },
{ AttributeName: 'resourceType', KeyType: 'RANGE' },
{ AttributeName: 'resourceId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}
// Query GSI: All resources for tenant T001, customer C001
const resources = await docClient.send(new QueryCommand({
TableName: 'SaasData',
IndexName: 'TenantCustomerIndex',
KeyConditionExpression: 'tenantId = :tenant AND customerId = :customer',
ExpressionAttributeValues: {
':tenant': 'T001',
':customer': 'C001'
}
}));
// Query GSI: Specific resource type for tenant/customer
const documents = await docClient.send(new QueryCommand({
TableName: 'SaasData',
IndexName: 'TenantCustomerIndex',
KeyConditionExpression: 'tenantId = :tenant AND customerId = :customer AND resourceType = :type',
ExpressionAttributeValues: {
':tenant': 'T001',
':customer': 'C001',
':type': 'document'
}
}));
```
**Manfaat:** Kueri yang efisien dalam konteks penyewa-pelanggan dan organisasi data alami.
### Transaksi keuangan
Sistem perbankan melacak transaksi rekening menggunakan GSIs
#### Contoh kode
```
// Table design
{
TableName: 'BankTransactions',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'transactionId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'transactionId', AttributeType: 'S' },
{ AttributeName: 'accountId', AttributeType: 'S' },
{ AttributeName: 'year', AttributeType: 'S' },
{ AttributeName: 'month', AttributeType: 'S' },
{ AttributeName: 'day', AttributeType: 'S' },
{ AttributeName: 'transactionType', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'AccountTimeIndex',
KeySchema: [
{ AttributeName: 'accountId', KeyType: 'HASH' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' },
{ AttributeName: 'day', KeyType: 'RANGE' },
{ AttributeName: 'transactionId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'TransactionTypeIndex',
KeySchema: [
{ AttributeName: 'accountId', KeyType: 'HASH' },
{ AttributeName: 'transactionType', KeyType: 'RANGE' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// Query AccountTimeIndex GSI: All transactions for account in 2023
const yearTransactions = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'AccountTimeIndex',
KeyConditionExpression: 'accountId = :account AND #year = :year',
ExpressionAttributeNames: { '#year': 'year' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':year': '2023'
}
}));
// Query AccountTimeIndex GSI: Transactions in specific month
const monthTransactions = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'AccountTimeIndex',
KeyConditionExpression: 'accountId = :account AND #year = :year AND #month = :month',
ExpressionAttributeNames: { '#year': 'year', '#month': 'month' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':year': '2023',
':month': '11'
}
}));
// Query TransactionTypeIndex GSI: Deposits in 2023
const deposits = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'TransactionTypeIndex',
KeyConditionExpression: 'accountId = :account AND transactionType = :type AND #year = :year',
ExpressionAttributeNames: { '#year': 'year' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':type': 'deposit',
':year': '2023'
}
}));
```
## Contoh lengkap
Contoh berikut menunjukkan kunci multi-atribut dari penyiapan ke pembersihan:
### Contoh kode
```
import {
DynamoDBClient,
CreateTableCommand,
DeleteTableCommand,
waitUntilTableExists
} from "@aws-sdk/client-dynamodb";
import {
DynamoDBDocumentClient,
PutCommand,
QueryCommand
} from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
async function multiAttributeKeysDemo() {
console.log("Starting Multi-Attribute GSI Keys Demo\n");
// Step 1: Create table with GSIs using multi-attribute keys
console.log("1. Creating table with multi-attribute GSI keys...");
await client.send(new CreateTableCommand({
TableName: 'TournamentMatches',
KeySchema: [
{ AttributeName: 'matchId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'matchId', AttributeType: 'S' },
{ AttributeName: 'tournamentId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'round', AttributeType: 'S' },
{ AttributeName: 'bracket', AttributeType: 'S' },
{ AttributeName: 'player1Id', AttributeType: 'S' },
{ AttributeName: 'matchDate', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'TournamentRegionIndex',
KeySchema: [
{ AttributeName: 'tournamentId', KeyType: 'HASH' },
{ AttributeName: 'region', KeyType: 'HASH' },
{ AttributeName: 'round', KeyType: 'RANGE' },
{ AttributeName: 'bracket', KeyType: 'RANGE' },
{ AttributeName: 'matchId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'PlayerMatchHistoryIndex',
KeySchema: [
{ AttributeName: 'player1Id', KeyType: 'HASH' },
{ AttributeName: 'matchDate', KeyType: 'RANGE' },
{ AttributeName: 'round', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}));
await waitUntilTableExists({ client, maxWaitTime: 120 }, { TableName: 'TournamentMatches' });
console.log("Table created\n");
// Step 2: Insert tournament matches
console.log("2. Inserting tournament matches...");
const matches = [
{ matchId: 'match-001', tournamentId: 'WINTER2024', region: 'NA-EAST', round: 'FINALS', bracket: 'CHAMPIONSHIP', player1Id: '101', player2Id: '103', matchDate: '2024-01-20', winner: '101', score: '3-1' },
{ matchId: 'match-002', tournamentId: 'WINTER2024', region: 'NA-EAST', round: 'SEMIFINALS', bracket: 'UPPER', player1Id: '101', player2Id: '105', matchDate: '2024-01-18', winner: '101', score: '3-2' },
{ matchId: 'match-003', tournamentId: 'WINTER2024', region: 'NA-WEST', round: 'FINALS', bracket: 'CHAMPIONSHIP', player1Id: '102', player2Id: '104', matchDate: '2024-01-20', winner: '102', score: '3-2' },
{ matchId: 'match-004', tournamentId: 'SPRING2024', region: 'NA-EAST', round: 'QUARTERFINALS', bracket: 'UPPER', player1Id: '101', player2Id: '108', matchDate: '2024-03-15', winner: '101', score: '3-0' }
];
for (const match of matches) {
await docClient.send(new PutCommand({ TableName: 'TournamentMatches', Item: match }));
}
console.log(`Inserted ${matches.length} tournament matches\n`);
// Step 3: Query GSI with multi-attribute partition key
console.log("3. Query TournamentRegionIndex GSI: WINTER2024/NA-EAST matches");
const gsiQuery1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
ExpressionAttributeNames: { '#region': 'region' },
ExpressionAttributeValues: { ':tournament': 'WINTER2024', ':region': 'NA-EAST' }
}));
console.log(` Found ${gsiQuery1.Items.length} matches:`);
gsiQuery1.Items.forEach(match => {
console.log(` ${match.round} - ${match.bracket} - ${match.winner} won`);
});
// Step 4: Query GSI with multi-attribute sort key
console.log("\n4. Query PlayerMatchHistoryIndex GSI: All matches for Player 101");
const gsiQuery2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player',
ExpressionAttributeValues: { ':player': '101' }
}));
console.log(` Found ${gsiQuery2.Items.length} matches for Player 101:`);
gsiQuery2.Items.forEach(match => {
console.log(` ${match.tournamentId}/${match.region} - ${match.matchDate} - ${match.round}`);
});
console.log("\nDemo complete");
console.log("No synthetic keys needed - GSIs use native attributes automatically");
}
async function cleanup() {
console.log("Deleting table...");
await client.send(new DeleteTableCommand({ TableName: 'TournamentMatches' }));
console.log("Table deleted");
}
// Run demo
multiAttributeKeysDemo().catch(console.error);
// Uncomment to cleanup:
// cleanup().catch(console.error);
```
**Perancah kode minimal**
### Contoh kode
```
// 1. Create table with GSI using multi-attribute keys
await client.send(new CreateTableCommand({
TableName: 'MyTable',
KeySchema: [
{ AttributeName: 'id', KeyType: 'HASH' } // Simple base table PK
],
AttributeDefinitions: [
{ AttributeName: 'id', AttributeType: 'S' },
{ AttributeName: 'attr1', AttributeType: 'S' },
{ AttributeName: 'attr2', AttributeType: 'S' },
{ AttributeName: 'attr3', AttributeType: 'S' },
{ AttributeName: 'attr4', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [{
IndexName: 'MyGSI',
KeySchema: [
{ AttributeName: 'attr1', KeyType: 'HASH' }, // GSI PK attribute 1
{ AttributeName: 'attr2', KeyType: 'HASH' }, // GSI PK attribute 2
{ AttributeName: 'attr3', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'attr4', KeyType: 'RANGE' } // GSI SK attribute 2
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}));
// 2. Insert items with native attributes (no concatenation needed for GSI)
await docClient.send(new PutCommand({
TableName: 'MyTable',
Item: {
id: 'item-001',
attr1: 'value1',
attr2: 'value2',
attr3: 'value3',
attr4: 'value4',
// ... other attributes
}
}));
// 3. Query GSI with all partition key attributes
await docClient.send(new QueryCommand({
TableName: 'MyTable',
IndexName: 'MyGSI',
KeyConditionExpression: 'attr1 = :v1 AND attr2 = :v2',
ExpressionAttributeValues: {
':v1': 'value1',
':v2': 'value2'
}
}));
// 4. Query GSI with sort key attributes (left-to-right)
await docClient.send(new QueryCommand({
TableName: 'MyTable',
IndexName: 'MyGSI',
KeyConditionExpression: 'attr1 = :v1 AND attr2 = :v2 AND attr3 = :v3',
ExpressionAttributeValues: {
':v1': 'value1',
':v2': 'value2',
':v3': 'value3'
}
}));
// Note: If any attribute name is a DynamoDB reserved keyword, use ExpressionAttributeNames:
// KeyConditionExpression: 'attr1 = :v1 AND #attr2 = :v2'
// ExpressionAttributeNames: { '#attr2': 'attr2' }
```
## Sumber daya tambahan
+ [Praktik Terbaik DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html)
+ [Bekerja dengan Tabel dan Data](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.html)
+ [Indeks Sekunder Global](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html)
+ [Operasi Kueri dan Pemindaian](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html)
# Mengelola Indeks Sekunder Global di DynamoDB
Bagian ini menjelaskan cara membuat, mengubah, dan menghapus indeks sekunder global di Amazon DynamoDB.
**Topics**
+ [Membuat tabel dengan Indeks Sekunder Global](#GSI.Creating)
+ [Mendeskripsikan Indeks Sekunder Global pada tabel](#GSI.Describing)
+ [Menambahkan Indeks Sekunder Global ke tabel yang sudah ada](#GSI.OnlineOps.Creating)
+ [Menghapus Indeks Sekunder Global](#GSI.OnlineOps.Deleting)
+ [Mengubah Indeks Sekunder Global selama pembuatan](#GSI.OnlineOps.Creating.Modify)
## Membuat tabel dengan Indeks Sekunder Global
Untuk membuat tabel dengan satu atau beberapa indeks sekunder global, gunakan operasi `CreateTable` dengan parameter `GlobalSecondaryIndexes`. Untuk fleksibilitas kueri maksimum, Anda dapat membuat hingga 20 indeks sekunder global (kuota default) per tabel.
Anda harus menentukan satu atribut untuk bertindak sebagai kunci partisi indeks. Anda dapat secara opsional menentukan atribut lain untuk kunci urutan indeks. Atribut kunci ini tidak perlu sama dengan atribut kunci dalam tabel. Misalnya, dalam *GameScores*tabel (lihat[Menggunakan Indeks Sekunder Global di DynamoDB](GSI.md)), tidak `TopScore` `TopScoreDateTime` juga atribut kunci. Anda dapat membuat indeks sekunder global dengan kunci partisi `TopScore` dan kunci urutan `TopScoreDateTime`. Anda dapat menggunakan indeks semacam itu untuk menentukan apakah ada korelasi antara skor tinggi dan waktu game dimainkan.
Setiap atribut kunci indeks harus berupa skalar berjenis `String`, `Number`, atau `Binary`. (Tidak boleh berupa dokumen atau kumpulan.) Anda dapat memproyeksikan atribut jenis data apa pun ke dalam indeks sekunder global. Ini termasuk skalar, dokumen, dan kumpulan. Untuk daftar lengkap jenis data, lihat [Jenis Data](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes).
Jika menggunakan mode yang disediakan, Anda harus menyediakan pengaturan `ProvisionedThroughput` untuk indeks, yang terdiri dari `ReadCapacityUnits` dan `WriteCapacityUnits`. Pengaturan throughput yang disediakan ini terpisah dari pengaturan tabel, tetapi berperilaku dengan cara yang serupa. Untuk informasi selengkapnya, lihat [Pertimbangan Throughput yang disediakan untuk Indeks Sekunder Global](GSI.md#GSI.ThroughputConsiderations).
Indeks sekunder global mewarisi mode read/write kapasitas dari tabel dasar. Untuk informasi selengkapnya, lihat [Pertimbangan saat mengganti mode kapasitas di DynamoDB](bp-switching-capacity-modes.md).
**catatan**
Saat membuat GSI baru, penting untuk memeriksa apakah pilihan kunci partisi Anda menghasilkan distribusi data atau lalu lintas yang tidak merata atau menyempit di seluruh nilai kunci partisi indeks baru. Jika ini terjadi, Anda mungkin melihat operasi backfill dan tulis terjadi secara bersamaan dan membatasi penulisan ke tabel dasar. Layanan mengambil tindakan untuk meminimalkan potensi skenario ini, tetapi tidak memiliki wawasan tentang bentuk data pelanggan sehubungan dengan kunci partisi indeks, proyeksi yang dipilih, atau ketersebaran kunci primer indeks.
Jika Anda mencurigai bahwa indeks sekunder global Anda yang baru mungkin memiliki data atau distribusi lalu lintas yang sempit atau tidak merata di seluruh nilai kunci partisi, pertimbangkan hal berikut sebelum menambahkan indeks baru ke tabel yang penting secara operasional.
Mungkin yang paling aman adalah menambahkan indeks pada saat aplikasi Anda menghasilkan jumlah lalu lintas paling sedikit.
Pertimbangkan untuk mengaktifkan CloudWatch Contributor Insights pada tabel dasar dan indeks Anda. Ini akan memberi Anda wawasan berharga mengenai distribusi lalu lintas Anda.
Tonton`WriteThrottleEvents`,`ThrottledRequests`, dan `OnlineIndexPercentageProgress` CloudWatch metrik selama proses berlangsung. Sesuaikan kapasitas penulisan yang disediakan sesuai kebutuhan untuk menyelesaikan pengisian ulang dalam waktu yang wajar tanpa efek pelambatan yang signifikan pada operasi Anda yang sedang berlangsung. `OnlineIndexConsumedWriteCapacity`dan `OnlineThrottleEvents` diharapkan menunjukkan 0 selama pengurukan indeks.
Bersiaplah untuk membatalkan pembuatan indeks jika Anda mengalami dampak operasional karena pembatasan penulisan.
## Mendeskripsikan Indeks Sekunder Global pada tabel
Untuk melihat status semua indeks sekunder global pada tabel, gunakan operasi `DescribeTable`. Bagian `GlobalSecondaryIndexes` dari respons menunjukkan semua indeks pada tabel, beserta status masing-masing indeks saat ini ( `IndexStatus`).
`IndexStatus` untuk indeks sekunder global akan menjadi salah satu dari berikut ini:
+ `CREATING` — Indeks sedang dibuat, dan belum tersedia untuk digunakan.
+ `ACTIVE` — Indeks siap digunakan, dan aplikasi dapat melakukan operasi `Query` pada indeks.
+ `UPDATING` — Pengaturan throughput indeks yang tersedia sedang diubah.
+ `DELETING` — Indeks saat ini sedang dihapus, dan tidak dapat lagi digunakan.
Setelah DynamoDB selesai membuat indeks sekunder global, status indeks berubah dari `CREATING` menjadi `ACTIVE`.
## Menambahkan Indeks Sekunder Global ke tabel yang sudah ada
Untuk menambahkan indeks sekunder global ke tabel yang sudah ada, gunakan operasi `UpdateTable` dengan parameter `GlobalSecondaryIndexUpdates`. Anda harus memasukkan berikut ini:
+ Nama indeks. Nama harus berbeda dari semua indeks pada tabel.
+ Skema kunci indeks. Anda harus menentukan satu atribut untuk kunci partisi indeks; Anda dapat secara opsional menentukan atribut lain untuk kunci urutan indeks. Atribut kunci ini tidak perlu sama dengan atribut kunci dalam tabel. Jenis data untuk setiap atribut skema harus skalar: `String`, `Number`, atau `Binary`.
+ Atribut yang akan diproyeksikan dari tabel ke dalam indeks:
+ `KEYS_ONLY` — Setiap item dalam indeks hanya terdiri dari kunci partisi tabel dan nilai kunci urutan, ditambah nilai kunci indeks.
+ `INCLUDE` — Selain atribut yang dijelaskan dalam `KEYS_ONLY`, indeks sekunder menyertakan atribut non-kunci lain yang Anda tentukan.
+ `ALL` — Indeks menyertakan semua atribut dari tabel sumber.
+ Setelan throughput yang disediakan untuk indeks, yang terdiri dari `ReadCapacityUnits` dan `WriteCapacityUnits`. Pengaturan throughput yang disediakan ini terpisah dari pengaturan tabel.
Anda hanya dapat membuat satu indeks sekunder global per operasi `UpdateTable`.
### Fase pembuatan indeks
Saat Anda menambahkan indeks sekunder global baru ke tabel yang sudah ada, tabel akan terus tersedia meskipun indeks sedang dibuat. Namun, indeks baru tidak tersedia untuk operasi Kueri hingga statusnya berubah dari `CREATING` menjadi `ACTIVE`.
**catatan**
Pembuatan indeks sekunder global tidak menggunakan Application Auto Scaling. Meningkatkan kapasitas Application Auto Scaling `MIN` tidak akan mengurangi waktu pembuatan indeks sekunder global.
Di balik layar, DynamoDB membuat indeks dalam dua fase:
**Alokasi Sumber Daya**
DynamoDB mengalokasikan sumber daya komputasi dan penyimpanan yang diperlukan untuk membuat indeks.
Selama fase alokasi sumber daya, atribut `IndexStatus` adalah `CREATING` dan atribut `Backfilling` adalah false. Gunakan operasi `DescribeTable` untuk mengambil status tabel dan semua indeks sekundernya.
Saat indeks berada dalam fase alokasi sumber daya, Anda tidak dapat menghapus indeks atau menghapus tabel induknya. Anda juga tidak dapat mengubah throughput indeks atau tabel yang disediakan. Anda tidak dapat menambahkan atau menghapus indeks lain pada tabel. Namun, Anda dapat mengubah throughput yang disediakan dari indeks lain tersebut.
**Backfill**
Untuk setiap item dalam tabel, DynamoDB menentukan kumpulan atribut yang akan ditulis ke indeks berdasarkan proyeksinya (`KEYS_ONLY`, `INCLUDE`, atau `ALL`). Kemudian atribut ini ditulis ke indeks. Selama fase backfill, DynamoDB melacak item yang ditambahkan, dihapus, atau diperbarui dalam tabel. Atribut dari item ini juga ditambahkan, dihapus, atau diperbarui dalam indeks yang sesuai.
Selama fase backfill, atribut `IndexStatus` diatur ke `CREATING`, dan atribut `Backfilling` adalah true. Gunakan operasi `DescribeTable` untuk mengambil status tabel dan semua indeks sekundernya.
Saat indeks sedang melakukan backfill, Anda tidak dapat menghapus tabel induknya. Namun, Anda masih dapat menghapus indeks atau mengubah throughput tabel yang disediakan dan indeks sekunder globalnya.
Selama fase backfill, beberapa penulisan item yang melanggar mungkin berhasil, sementara yang lain ditolak. Setelah backfill, semua penulisan ke item yang melanggar skema kunci indeks baru akan ditolak. Sebaiknya Anda menjalankan alat Detektor Pelanggaran setelah fase backfill selesai untuk mendeteksi dan mengatasi pelanggaran utama yang mungkin terjadi. Untuk informasi selengkapnya, lihat [Mendeteksi dan memperbaiki pelanggaran kunci indeks di DynamoDB](GSI.OnlineOps.ViolationDetection.md).
Saat fase alokasi sumber daya dan backfill sedang berlangsung, indeks berada dalam status `CREATING`. Selama waktu ini, DynamoDB melakukan operasi baca pada tabel. Operasi baca dari tabel dasar untuk mengisi indeks sekunder global tidak dikenakan biaya.
Setelah pembuatan indeks selesai, statusnya berubah menjadi `ACTIVE`. Anda tidak dapat `Query` atau `Scan` indeks sampai indeks itu `ACTIVE`.
**catatan**
Dalam beberapa kasus, DynamoDB tidak dapat menulis data dari tabel ke indeks karena pelanggaran kunci indeks. Hal ini dapat terjadi jika:
Jenis data nilai atribut tidak cocok dengan jenis data skema kunci indeks.
Ukuran atribut melebihi panjang maksimum atribut kunci indeks.
Atribut kunci indeks memiliki String kosong atau nilai atribut Binari kosong.
Pelanggaran kunci indeks tidak mengganggu pembuatan indeks sekunder global. Namun, ketika indeks menjadi `ACTIVE`, kunci yang melanggar tidak ada dalam indeks.
DynamoDB menyediakan alat mandiri untuk menemukan dan menyelesaikan masalah ini. Untuk informasi selengkapnya, lihat [Mendeteksi dan memperbaiki pelanggaran kunci indeks di DynamoDB](GSI.OnlineOps.ViolationDetection.md).
### Menambahkan Indeks Sekunder Global ke tabel besar
Waktu yang dibutuhkan untuk membuat indeks sekunder global tergantung beberapa faktor, seperti berikut ini:
+ Ukuran ruang tabel
+ Jumlah item dalam tabel yang memenuhi syarat untuk dimasukkan dalam indeks
+ Jumlah atribut yang diproyeksikan ke dalam indeks
+ Aktivitas tulis di tabel utama selama pembuatan indeks
Jika Anda menambahkan indeks sekunder global ke tabel yang sangat besar, mungkin perlu waktu lama untuk menyelesaikan proses pembuatan. Untuk memantau kemajuan dan menentukan apakah indeks memiliki kapasitas tulis yang memadai, lihat CloudWatch metrik Amazon berikut:
+ `OnlineIndexPercentageProgress`
Untuk informasi selengkapnya tentang CloudWatch metrik yang terkait dengan DynamoDB, lihat. [Metrik DynamoDB](metrics-dimensions.md#dynamodb-metrics)
**penting**
Anda mungkin perlu mengizinkan daftar tabel yang sangat besar sebelum membuat atau memperbarui Indeks Sekunder Global. Silakan hubungi AWS Support untuk mengizinkan daftar tabel Anda.
Saat indeks sedang melakukan backfill, DynamoDB menggunakan kapasitas sistem internal untuk membaca dari tabel. Hal ini bertujuan untuk meminimalkan dampak pembuatan indeks dan untuk memastikan bahwa tabel Anda tidak kehabisan kapasitas baca.
## Menghapus Indeks Sekunder Global
Jika tidak lagi memerlukan indeks sekunder global, Anda dapat menghapusnya menggunakan operasi `UpdateTable`.
Anda hanya dapat menghapus satu indeks sekunder global per operasi `UpdateTable`.
Saat indeks sekunder global sedang dihapus, aktivitas baca atau tulis apa pun di tabel induk tidak akan terpengaruh. Saat penghapusan sedang berlangsung, Anda masih dapat mengubah throughput yang disediakan pada indeks lain.
**catatan**
Saat Anda menghapus tabel menggunakan tindakan `DeleteTable`, semua indeks sekunder global pada tabel tersebut juga dihapus.
Akun Anda tidak akan dikenakan biaya untuk operasi penghapusan indeks sekunder global.
## Mengubah Indeks Sekunder Global selama pembuatan
Saat indeks sedang dibuat, Anda dapat menggunakan operasi `DescribeTable` untuk mengetahui fasenya. Deskripsi untuk indeks menyertakan atribut Boolean, `Backfilling`, untuk menunjukkan apakah DynamoDB saat ini memuat indeks dengan item dari tabel. Jika nilai `Backfilling` adalah true, artinya fase alokasi sumber daya sudah selesai dan indeks sekarang melakukan backfill.
Selama fase backfill, Anda dapat menghapus indeks yang sedang dibuat. Selama fase ini, Anda tidak dapat menambahkan atau menghapus indeks lain di tabel.
**catatan**
Untuk indeks yang dibuat sebagai bagian dari operasi `CreateTable`, atribut `Backfilling` tidak muncul di output `DescribeTable`. Lihat informasi yang lebih lengkap di [Fase pembuatan indeks](#GSI.OnlineOps.Creating.Phases).
# Mendeteksi dan memperbaiki pelanggaran kunci indeks di DynamoDB
Selama fase backfill pembuatan indeks sekunder global, Amazon DynamoDB memeriksa setiap item dalam tabel untuk menentukan apakah item tersebut memenuhi syarat untuk dimasukkan dalam indeks. Beberapa item mungkin tidak memenuhi syarat karena akan menyebabkan pelanggaran kunci indeks. Dalam kasus ini, item tetap berada di tabel, tetapi indeks tidak memiliki entri yang sesuai untuk item tersebut.
*Pelanggaran kunci indeks* terjadi dalam situasi berikut:
+ Ada ketidakcocokan jenis data antara nilai atribut dan jenis data skema kunci indeks. Misalnya, katakanlah salah satu item dalam tabel `GameScores` memiliki nilai `TopScore` jenis `String`. Jika Anda menambahkan indeks sekunder global dengan kunci partisi `TopScore`, jenis `Number`, item dari tabel tersebut akan melanggar kunci indeks.
+ Nilai atribut dari tabel melebihi panjang maksimum untuk atribut kunci indeks. Panjang maksimum kunci partisi adalah 2048 byte, dan panjang maksimum kunci urutan adalah 1024 byte. Jika salah satu nilai atribut yang sesuai dalam tabel melebihi batas ini, item dari tabel akan melanggar kunci indeks.
**catatan**
Jika nilai atribut Binari atau String ditetapkan untuk atribut yang digunakan sebagai kunci indeks, maka nilai atribut harus memiliki panjang lebih besar dari nol;, jika tidak, item dari tabel akan melanggar kunci indeks.
Alat ini tidak menandai pelanggaran kunci indeks ini, saat ini.
Jika pelanggaran kunci indeks terjadi, fase backfill berlanjut tanpa gangguan. Namun, item yang melanggar tidak termasuk dalam indeks. Setelah fase backfill selesai, semua penulisan ke item yang melanggar skema kunci indeks baru akan ditolak.
Untuk mengidentifikasi dan memperbaiki nilai atribut dalam tabel yang melanggar kunci indeks, gunakan alat Detektor Pelanggaran. Untuk menjalankan Detektor Pelanggaran, buat file konfigurasi yang menentukan nama tabel yang akan dipindai, nama dan jenis data kunci partisi indeks sekunder global dan kunci urutan, serta tindakan yang harus diambil jika ditemukan pelanggaran kunci indeks. Detektor Pelanggaran dapat dijalankan dalam salah satu dari dua mode berbeda:
+ **Mode deteksi** — Mendeteksi pelanggaran kunci indeks. Gunakan mode deteksi untuk melaporkan item dalam tabel yang akan menyebabkan pelanggaran kunci dalam indeks sekunder global. (Anda juga dapat meminta agar item tabel yang melanggar ini segera dihapus ketika ditemukan.) Output dari mode deteksi ditulis ke file, yang dapat Anda gunakan untuk analisis lebih lanjut.
+ **Mode koreksi** — Memperbaiki pelanggaran kunci indeks. Dalam mode koreksi, Detektor Pelanggaran membaca file input dengan format yang sama dengan file output dari mode deteksi. Mode koreksi membaca catatan dari file input dan, untuk setiap catatan, mode ini menghapus atau memperbarui item yang sesuai dalam tabel. (Perhatikan bahwa jika Anda memilih untuk memperbarui item, Anda harus mengedit file input dan menetapkan nilai yang sesuai untuk pembaruan ini.)
## Mengunduh dan menjalankan Detektor Pelanggaran
Detektor Pelanggaran tersedia sebagai Java Archive (file `.jar`) yang dapat dieksekusi, dan dapat dijalankan di komputer Windows, macOS, atau Linux. Detektor Pelanggaran membutuhkan Java 1.7 (atau yang lebih baru) dan Apache Maven.
+ [Unduh detektor pelanggaran dari GitHub](https://github.com/awslabs/dynamodb-online-index-violation-detector)
Ikuti petunjuk dalam file `README.md` untuk mengunduh dan menginstal Detektor Pelanggaran menggunakan Maven.
Untuk memulai Detektor Pelanggaran, buka direktori tempat Anda membuat `ViolationDetector.java` dan masukkan perintah berikut.
```
java -jar ViolationDetector.jar [options]
```
Baris perintah Detektor Pelanggaran menerima opsi berikut:
+ `-h | --help` — Mencetak ringkasan penggunaan dan opsi untuk Detektor Pelanggaran.
+ `-p | --configFilePath` `value` — Nama yang sepenuhnya memenuhi syarat untuk file konfigurasi Detektor Pelanggaran. Untuk informasi selengkapnya, lihat [File konfigurasi Detektor Pelanggaran](#GSI.OnlineOps.ViolationDetection.ConfigFile).
+ `-t | --detect` `value` — Mendeteksi pelanggaran kunci indeks di tabel, dan menuliskannya ke file output Detektor Pelanggaran. Jika nilai parameter ini diatur ke `keep`, item dengan pelanggaran kunci tidak diubah. Jika nilai diatur ke `delete`, item dengan pelanggaran kunci dihapus dari tabel.
+ `-c | --correct` `value` — Membaca pelanggaran kunci indeks dari file input, dan mengambil tindakan perbaikan pada item dalam tabel. Jika nilai parameter ini disetel ke `update`, item dengan pelanggaran kunci diperbarui dengan nilai baru yang tidak melanggar. Jika nilai diatur ke `delete`, item dengan pelanggaran kunci dihapus dari tabel.
## File konfigurasi Detektor Pelanggaran
Saat runtime, alat Detektor Pelanggaran memerlukan file konfigurasi. Parameter dalam file ini menentukan sumber daya DynamoDB yang dapat diakses oleh Detektor Pelanggaran, dan jumlah throughput yang disediakan yang dapat digunakan oleh sumber daya tersebut. Tabel berikut mendeskripsikan parameter ini.
****
| Nama parameter | Deskripsi | Diperlukan? |
| --- | --- | --- |
| `awsCredentialsFile` | Nama yang sepenuhnya memenuhi syarat untuk file yang berisi kredensial AWS Anda. File kredensial harus dalam format berikut: accessKey = access_key_id_goes_here
secretKey = secret_key_goes_here
| Ya |
| `dynamoDBRegion` | AWS Wilayah di mana tabel berada. Sebagai contoh: `us-west-2`. | Ya |
| `tableName` | Nama tabel DynamoDB yang akan dipindai. | Ya |
| `gsiHashKeyName` | Nama kunci partisi indeks. | Ya |
| `gsiHashKeyType` | Jenis data kunci partisi indeks—`String`, `Number`, atau `Binary`: `S \| N \| B` | Ya |
| `gsiRangeKeyName` | Nama kunci urutan indeks. Jangan tentukan parameter ini jika indeks hanya memiliki kunci primer sederhana (kunci partisi). | Tidak |
| `gsiRangeKeyType` | Jenis data untuk kunci urutan indeks—`String`, `Number`, atau `Binary`: `S \| N \| B` Jangan tentukan parameter ini jika indeks hanya memiliki kunci primer sederhana (kunci partisi). | Tidak |
| `recordDetails` | Apakah akan menulis detail lengkap pelanggaran kunci indeks ke file keluaran. Jika diatur ke `true` (default), informasi lengkap tentang item yang melanggar akan dilaporkan. Jika diatur ke `false`, hanya jumlah pelanggaran yang dilaporkan. | Tidak |
| `recordGsiValueInViolationRecord` | Apakah akan menulis nilai untuk kunci indeks yang melanggar ke file output. Jika diatur ke `true` (default), nilai kunci dilaporkan. Jika diatur ke `false`, nilai kunci tidak dilaporkan. | Tidak |
| `detectionOutputPath` | Jalur lengkap file output Detektor Pelanggaran. Parameter ini mendukung penulisan ke direktori lokal atau ke Amazon Simple Storage Service (Amazon S3). Berikut ini adalah beberapa contohnya: `detectionOutputPath = ``//local/path/filename.csv` `detectionOutputPath = ``s3://bucket/filename.csv` Informasi dalam file output muncul dalam format nilai yang dipisahkan koma (CSV). Jika Anda tidak mengatur `detectionOutputPath`, file outputnya bernama `violation_detection.csv` dan ditulis ke direktori kerja saat ini. | Tidak |
| `numOfSegments` | Jumlah segmen pemindaian paralel yang akan digunakan saat Detektor Pelanggaran memindai tabel. Nilai defaultnya adalah 1, artinya tabel dipindai secara berurutan. Jika nilainya 2 atau lebih tinggi, Detektor Pelanggaran membagi tabel menjadi banyak segmen logis dan jumlah utas pemindaian yang sama. Pengaturan maksimum untuk `numOfSegments` adalah 4096.Untuk tabel yang lebih besar, pemindaian paralel umumnya lebih cepat daripada pemindaian berurutan. Selain itu, jika tabel cukup besar untuk menjangkau beberapa partisi, pemindaian paralel mendistribusikan aktivitas bacanya secara merata di beberapa partisi.Untuk informasi selengkapnya tentang pemindaian paralel di DynamoDB, lihat [Pemindaian paralel](Scan.md#Scan.ParallelScan). | Tidak |
| `numOfViolations` | Batas atas pelanggaran kunci indeks untuk menulis ke file output. Jika diatur ke `-1` (default), seluruh tabel dipindai. Jika diatur ke angka bulat positif, Detektor Pelanggaran akan berhenti setelah menemukan jumlah pelanggaran tersebut. | Tidak |
| `numOfRecords` | Jumlah item dalam tabel yang akan dipindai. Jika diatur ke -1 (default), seluruh tabel dipindai. Jika diatur ke angka bulat positif, Detektor Pelanggaran akan berhenti setelah memindai jumlah item tersebut dalam tabel. | Tidak |
| `readWriteIOPSPercent` | Mengatur persentase unit kapasitas baca yang disediakan yang digunakan selama pemindaian tabel. Nilai yang valid berkisar dari `1` sampai `100`. Nilai default (`25`) berarti bahwa Detektor Pelanggaran akan menggunakan tidak lebih dari 25% dari throughput baca yang disediakan pada tabel. | Tidak |
| `correctionInputPath` | Jalur lengkap file input koreksi Detektor Pelanggaran. Jika Anda menjalankan Detektor Pelanggaran dalam mode koreksi, konten file ini digunakan untuk mengubah atau menghapus item data dalam tabel yang melanggar indeks sekunder global. Format file `correctionInputPath` sama dengan format file `detectionOutputPath`. Ini memungkinkan Anda memproses output dari mode deteksi sebagai input dalam mode koreksi. | Tidak |
| `correctionOutputPath` | Jalur lengkap file output koreksi Detektor Pelanggaran. File ini dibuat hanya jika ada kesalahan pembaruan. Parameter ini mendukung penulisan ke direktori lokal atau ke Amazon S3. Berikut ini adalah beberapa contohnya: `correctionOutputPath = ``//local/path/filename.csv` `correctionOutputPath = ``s3://bucket/filename.csv` Informasi dalam file output ditampilkan dalam format CSV. Jika Anda tidak mengatur `correctionOutputPath`, file outputnya bernama `violation_update_errors.csv` dan ditulis ke direktori kerja saat ini. | Tidak |
## Deteksi
Untuk mendeteksi pelanggaran kunci indeks, gunakan Detektor Pelanggaran dengan opsi baris perintah `--detect`. Untuk menunjukkan cara kerja opsi ini, pertimbangkan `ProductCatalog` tabel. Berikut ini adalah daftar item dalam tabel. Hanya kunci primer (`Id`) dan atribut `Price` yang ditampilkan.
****
| Id (kunci primer) | Harga |
| --- | --- |
| 101 | 5 |
| 102 | 20 |
| 103 | 200 |
| 201 | 100 |
| 202 | 200 |
| 203 | 300 |
| 204 | 400 |
| 205 | 500 |
Semua nilai untuk `Price` berjenis `Number`. Namun, karena DynamoDB tidak memiliki skema, Anda dapat menambahkan item dengan `Price` non-numerik. Misalnya, anggaplah Anda menambahkan item lain ke tabel `ProductCatalog`.
****
| Id (kunci primer) | Harga |
| --- | --- |
| 999 | "Hello" |
Tabel sekarang memiliki total sembilan item.
Sekarang Anda menambahkan indeks sekunder global baru ke tabel: `PriceIndex`. Kunci primer untuk indeks ini adalah kunci partisi, `Price`, yang berjenis `Number`. Setelah indeks dibuat, indeks akan berisi delapan item—tetapi tabel `ProductCatalog` memiliki sembilan item. Alasan perbedaan ini adalah bahwa nilai `"Hello"` adalah jenis `String`, tetapi `PriceIndex` memiliki kunci primer jenis `Number`. Nilai `String` melanggar kunci indeks sekunder global, sehingga tidak ada dalam indeks.
Untuk menggunakan Detektor Pelanggaran dalam skenario ini, Anda akan membuat file konfigurasi seperti berikut ini terlebih dahulu.
```
# Properties file for violation detection tool configuration.
# Parameters that are not specified will use default values.
awsCredentialsFile = /home/alice/credentials.txt
dynamoDBRegion = us-west-2
tableName = ProductCatalog
gsiHashKeyName = Price
gsiHashKeyType = N
recordDetails = true
recordGsiValueInViolationRecord = true
detectionOutputPath = ./gsi_violation_check.csv
correctionInputPath = ./gsi_violation_check.csv
numOfSegments = 1
readWriteIOPSPercent = 40
```
Selanjutnya, Anda menjalankan Detektor Pelanggaran seperti dalam contoh berikut.
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --detect keep
Violation detection started: sequential scan, Table name: ProductCatalog, GSI name: PriceIndex
Progress: Items scanned in total: 9, Items scanned by this thread: 9, Violations found by this thread: 1, Violations deleted by this thread: 0
Violation detection finished: Records scanned: 9, Violations found: 1, Violations deleted: 0, see results at: ./gsi_violation_check.csv
```
Jika parameter konfigurasi `recordDetails` diatur ke `true`, Detektor Pelanggaran menulis detail setiap pelanggaran ke file output, seperti dalam contoh berikut.
```
Table Hash Key,GSI Hash Key Value,GSI Hash Key Violation Type,GSI Hash Key Violation Description,GSI Hash Key Update Value(FOR USER),Delete Blank Attributes When Updating?(Y/N)
999,"{""S"":""Hello""}",Type Violation,Expected: N Found: S,,
```
File output dalam format CSV. Baris pertama dalam file tersebut adalah header, diikuti oleh satu catatan per item yang melanggar kunci indeks. Bidang catatan pelanggaran tersebut adalah sebagai berikut:
+ **Kunci hash tabel** — Nilai kunci partisi item dalam tabel.
+ **Kunci rentang tabel** — Nilai kunci urutan item dalam tabel.
+ **Nilai kunci hash GSI** — Nilai kunci partisi indeks sekunder global.
+ **Jenis pelanggaran kunci hash GSI** — `Type Violation` atau `Size Violation`.
+ **Deskripsi pelanggaran kunci hash GSI** — Penyebab pelanggaran.
+ **Nilai pembaruan kunci hash GSI (UNTUK PENGGUNA)** — Dalam mode koreksi, nilai baru yang diberikan pengguna untuk atribut tersebut.
+ **Nilai kunci rentang GSI** — Nilai kunci urutan indeks sekunder global.
+ **Jenis pelanggaran kunci rentang GSI** — `Type Violation` atau `Size Violation`.
+ **Deskripsi pelanggaran kunci rentang GSI** — Penyebab pelanggaran.
+ **Nilai pembaruan kunci rentang GSI (UNTUK PENGGUNA)** — Dalam mode koreksi, nilai baru yang diberikan pengguna untuk atribut tersebut.
+ **Hapus atribut kosong saat memperbarui (Y/T)** — Dalam mode koreksi, menentukan apakah akan menghapus (Y) atau menyimpan (T) item yang melanggar dalam tabel—tetapi hanya jika salah satu bidang berikut ini kosong:
+ `GSI Hash Key Update Value(FOR USER)`
+ `GSI Range Key Update Value(FOR USER)`
Jika salah satu dari bidang ini tidak kosong, `Delete Blank Attribute When Updating(Y/N)` tidak berpengaruh.
**catatan**
Format output mungkin berbeda, tergantung file konfigurasi dan opsi baris perintah. Misalnya, jika tabel memiliki kunci primer sederhana (tanpa kunci urutan), tidak ada bidang kunci urutan yang akan ditampilkan dalam output.
Catatan pelanggaran dalam file mungkin tidak diurutkan.
## Koreksi
Untuk memperbaiki pelanggaran kunci indeks, gunakan Detektor Pelanggaran dengan opsi baris perintah `--correct`. Dalam mode koreksi, Detektor Pelanggaran membaca file input yang ditentukan oleh parameter `correctionInputPath`. File ini memiliki format yang sama dengan file `detectionOutputPath`, sehingga Anda dapat menggunakan output dari deteksi sebagai input untuk koreksi.
Detektor Pelanggaran menyediakan dua cara berbeda untuk memperbaiki pelanggaran kunci indeks:
+ **Hapus pelanggaran** — Menghapus item tabel yang memiliki nilai atribut yang melanggar.
+ **Perbarui pelanggaran** — Memperbarui item tabel, mengganti atribut yang melanggar dengan nilai yang tidak melanggar.
Dalam kasus tersebut, Anda dapat menggunakan file output dari mode deteksi sebagai input untuk mode koreksi.
Melanjutkan contoh `ProductCatalog`, misalkan Anda ingin menghapus item yang melanggar dari tabel. Untuk melakukannya, gunakan perintah berikut.
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --correct delete
```
Pada tahap ini, Anda akan diminta untuk mengonfirmasi apakah Anda ingin menghapus item yang melanggar.
```
Are you sure to delete all violations on the table?y/n
y
Confirmed, will delete violations on the table...
Violation correction from file started: Reading records from file: ./gsi_violation_check.csv, will delete these records from table.
Violation correction from file finished: Violations delete: 1, Violations Update: 0
```
Sekarang, `ProductCatalog` dan `PriceIndex` memiliki jumlah item yang sama.
# Menggunakan Indeks Sekunder Global: Java
Anda dapat menggunakan AWS SDK untuk Java Document API untuk membuat tabel Amazon DynamoDB dengan satu atau beberapa indeks sekunder global, menjelaskan indeks pada tabel, dan melakukan kueri menggunakan indeks.
Berikut ini adalah langkah-langkah umum untuk operasi tabel.
1. Buat instans dari kelas `DynamoDB`.
1. Berikan parameter wajib dan opsional untuk operasi dengan membuat objek permintaan yang sesuai.
1. Panggil metode sesuai yang ditentukan oleh klien yang Anda buat pada langkah sebelumnya.
**Topics**
+ [Membuat tabel dengan Indeks Sekunder Global](#GSIJavaDocumentAPI.CreateTableWithIndex)
+ [Mendeskripsikan tabel dengan Indeks Sekunder Global](#GSIJavaDocumentAPI.DescribeTableWithIndex)
+ [Mengkueri Indeks Sekunder Global](#GSIJavaDocumentAPI.QueryAnIndex)
+ [Contoh: Indeks Sekunder Global menggunakan API AWS SDK untuk Java dokumen](GSIJavaDocumentAPI.Example.md)
## Membuat tabel dengan Indeks Sekunder Global
Anda dapat membuat indeks sekunder global pada saat membuat tabel. Untuk melakukannya, gunakan `CreateTable` dan berikan spesifikasi Anda untuk satu atau beberapa indeks sekunder global. Contoh kode Java berikut membuat tabel untuk menyimpan informasi tentang data cuaca. Kunci partisinya adalah `Location` dan kunci urutannya adalah `Date`. Indeks sekunder global bernama `PrecipIndex` memungkinkan akses cepat ke data curah hujan untuk berbagai lokasi.
Berikut adalah langkah-langkah untuk membuat tabel dengan indeks sekunder global, menggunakan API dokumen DynamoDB.
1. Buat instans dari kelas `DynamoDB`.
1. Buat instans dari kelas `CreateTableRequest` untuk memberikan informasi permintaan.
Anda harus memberikan nama tabel, kunci primernya, dan nilai throughput yang ditentukan. Untuk indeks sekunder global, Anda harus memberikan nama indeks, pengaturan throughput yang ditentukan, definisi atribut untuk kunci urutan indeks, skema kunci untuk indeks, dan proyeksi atribut.
1. Panggil metode `createTable` dengan menentukan objek permintaan sebagai parameter.
Contoh kode Java berikut mendemonstrasikan langkah sebelumnya. Kode tersebut membuat tabel (`WeatherData`) dengan indeks sekunder global (`PrecipIndex`). Kunci partisi indeksnya adalah `Date` dan kunci urutannya adalah `Precipitation`. Semua atribut tabel diproyeksikan ke dalam indeks. Pengguna dapat mengkueri indeks ini untuk mendapatkan data cuaca untuk tanggal tertentu, yang secara opsional mengurutkan data berdasarkan jumlah curah hujan.
Karena `Precipitation` bukan atribut kunci untuk tabel tersebut, maka tidak diperlukan. Namun, item `WeatherData` tanpa `Precipitation` tidak muncul di `PrecipIndex`.
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
// Attribute definitions
ArrayList attributeDefinitions = new ArrayList();
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Location")
.withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Date")
.withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Precipitation")
.withAttributeType("N"));
// Table key schema
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement()
.withAttributeName("Location")
.withKeyType(KeyType.HASH)); //Partition key
tableKeySchema.add(new KeySchemaElement()
.withAttributeName("Date")
.withKeyType(KeyType.RANGE)); //Sort key
// PrecipIndex
GlobalSecondaryIndex precipIndex = new GlobalSecondaryIndex()
.withIndexName("PrecipIndex")
.withProvisionedThroughput(new ProvisionedThroughput()
.withReadCapacityUnits((long) 10)
.withWriteCapacityUnits((long) 1))
.withProjection(new Projection().withProjectionType(ProjectionType.ALL));
ArrayList indexKeySchema = new ArrayList();
indexKeySchema.add(new KeySchemaElement()
.withAttributeName("Date")
.withKeyType(KeyType.HASH)); //Partition key
indexKeySchema.add(new KeySchemaElement()
.withAttributeName("Precipitation")
.withKeyType(KeyType.RANGE)); //Sort key
precipIndex.setKeySchema(indexKeySchema);
CreateTableRequest createTableRequest = new CreateTableRequest()
.withTableName("WeatherData")
.withProvisionedThroughput(new ProvisionedThroughput()
.withReadCapacityUnits((long) 5)
.withWriteCapacityUnits((long) 1))
.withAttributeDefinitions(attributeDefinitions)
.withKeySchema(tableKeySchema)
.withGlobalSecondaryIndexes(precipIndex);
Table table = dynamoDB.createTable(createTableRequest);
System.out.println(table.getDescription());
```
Anda harus menunggu hingga DynamoDB membuat tabel dan menetapkan status tabel menjadi `ACTIVE`. Setelah itu, Anda bisa mulai memasukkan item data ke dalam tabel.
## Mendeskripsikan tabel dengan Indeks Sekunder Global
Untuk mendapatkan informasi tentang indeks sekunder global pada sebuah tabel, gunakan `DescribeTable`. Untuk setiap indeks, Anda dapat mengakses namanya, skema kunci, dan atribut yang diproyeksikan.
Berikut ini adalah langkah-langkah untuk mengakses informasi indeks sekunder global sebuah tabel.
1. Buat instans dari kelas `DynamoDB`.
1. Buat instans dari kelas `Table` untuk mewakili indeks yang ingin Anda gunakan.
1. Panggil metode `describe` pada objek `Table`.
Contoh kode Java berikut mendemonstrasikan langkah sebelumnya.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
Table table = dynamoDB.getTable("WeatherData");
TableDescription tableDesc = table.describe();
Iterator gsiIter = tableDesc.getGlobalSecondaryIndexes().iterator();
while (gsiIter.hasNext()) {
GlobalSecondaryIndexDescription gsiDesc = gsiIter.next();
System.out.println("Info for index "
+ gsiDesc.getIndexName() + ":");
Iterator kseIter = gsiDesc.getKeySchema().iterator();
while (kseIter.hasNext()) {
KeySchemaElement kse = kseIter.next();
System.out.printf("\t%s: %s\n", kse.getAttributeName(), kse.getKeyType());
}
Projection projection = gsiDesc.getProjection();
System.out.println("\tThe projection type is: "
+ projection.getProjectionType());
if (projection.getProjectionType().toString().equals("INCLUDE")) {
System.out.println("\t\tThe non-key projected attributes are: "
+ projection.getNonKeyAttributes());
}
}
```
## Mengkueri Indeks Sekunder Global
Anda dapat menggunakan `Query` pada indeks sekunder global, sama seperti Anda `Query` tabel. Anda perlu menentukan nama indeks, kriteria kueri untuk kunci partisi indeks dan kunci urutan (jika ada), dan atribut yang ingin Anda kembalikan. Dalam contoh ini, indeks adalah `PrecipIndex`, yang memiliki kunci partisi `Date` dan kunci urutan `Precipitation`. Kueri indeks mengembalikan semua data cuaca untuk tanggal tertentu, dengan curah hujan lebih besar dari nol.
Berikut ini adalah langkah-langkah untuk query indeks sekunder global menggunakan AWS SDK untuk Java Document API.
1. Buat instans dari kelas `DynamoDB`.
1. Buat instans dari kelas `Table` untuk mewakili indeks yang ingin Anda gunakan.
1. Buat instans dari kelas `Index` untuk indeks yang ingin Anda kueri.
1. Panggil metode `query` pada objek `Index`.
Nama atribut `Date` adalah kata yang disimpan DynamoDB. Oleh karena itu, Anda harus menggunakan nama atribut ekspresi sebagai placeholder di `KeyConditionExpression`.
Contoh kode Java berikut mendemonstrasikan langkah sebelumnya.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
Table table = dynamoDB.getTable("WeatherData");
Index index = table.getIndex("PrecipIndex");
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("#d = :v_date and Precipitation = :v_precip")
.withNameMap(new NameMap()
.with("#d", "Date"))
.withValueMap(new ValueMap()
.withString(":v_date","2013-08-10")
.withNumber(":v_precip",0));
ItemCollection items = index.query(spec);
Iterator- iter = items.iterator();
while (iter.hasNext()) {
System.out.println(iter.next().toJSONPretty());
}
```
# Contoh: Indeks Sekunder Global menggunakan API AWS SDK untuk Java dokumen
Contoh kode Java berikut menunjukkan cara menggunakan indeks sekunder global. Contoh tersebut membuat tabel bernama `Issues`, yang dapat digunakan dalam sistem pelacakan bug sederhana untuk pengembangan perangkat lunak. Kunci partisinya adalah `IssueId` dan kunci urutannya adalah `Title`. Ada tiga indeks sekunder global pada tabel ini:
+ `CreateDateIndex` — Kunci partisinya adalah `CreateDate` dan kunci urutannya adalah `IssueId`. Selain kunci tabel, atribut `Description` dan `Status` diproyeksikan ke dalam indeks.
+ `TitleIndex` — Kunci partisinya adalah `Title` dan kunci urutannya adalah `IssueId`. Tidak ada atribut selain kunci tabel yang diproyeksikan ke dalam indeks.
+ `DueDateIndex` — Kunci partisinya adalah `DueDate`, dan tidak ada kunci urutan. Semua atribut tabel diproyeksikan ke dalam indeks.
Setelah tabel `Issues` dibuat, program memuat tabel dengan data yang mewakili laporan bug perangkat lunak. Kemudian, data dikueri menggunakan indeks sekunder global. Terakhir, program menghapus tabel `Issues`.
Untuk step-by-step instruksi untuk menguji contoh berikut, lihat[Contoh kode Java](CodeSamples.Java.md).
**Example**
```
package com.amazonaws.codesamples.document;
import java.util.ArrayList;
import java.util.Iterator;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.document.DynamoDB;
import com.amazonaws.services.dynamodbv2.document.Index;
import com.amazonaws.services.dynamodbv2.document.Item;
import com.amazonaws.services.dynamodbv2.document.ItemCollection;
import com.amazonaws.services.dynamodbv2.document.QueryOutcome;
import com.amazonaws.services.dynamodbv2.document.Table;
import com.amazonaws.services.dynamodbv2.document.spec.QuerySpec;
import com.amazonaws.services.dynamodbv2.document.utils.ValueMap;
import com.amazonaws.services.dynamodbv2.model.AttributeDefinition;
import com.amazonaws.services.dynamodbv2.model.CreateTableRequest;
import com.amazonaws.services.dynamodbv2.model.GlobalSecondaryIndex;
import com.amazonaws.services.dynamodbv2.model.KeySchemaElement;
import com.amazonaws.services.dynamodbv2.model.KeyType;
import com.amazonaws.services.dynamodbv2.model.Projection;
import com.amazonaws.services.dynamodbv2.model.ProvisionedThroughput;
public class DocumentAPIGlobalSecondaryIndexExample {
static AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
static DynamoDB dynamoDB = new DynamoDB(client);
public static String tableName = "Issues";
public static void main(String[] args) throws Exception {
createTable();
loadData();
queryIndex("CreateDateIndex");
queryIndex("TitleIndex");
queryIndex("DueDateIndex");
deleteTable(tableName);
}
public static void createTable() {
// Attribute definitions
ArrayList attributeDefinitions = new ArrayList();
attributeDefinitions.add(new AttributeDefinition().withAttributeName("IssueId").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("Title").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("CreateDate").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("DueDate").withAttributeType("S"));
// Key schema for table
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.HASH)); // Partition
// key
tableKeySchema.add(new KeySchemaElement().withAttributeName("Title").withKeyType(KeyType.RANGE)); // Sort
// key
// Initial provisioned throughput settings for the indexes
ProvisionedThroughput ptIndex = new ProvisionedThroughput().withReadCapacityUnits(1L)
.withWriteCapacityUnits(1L);
// CreateDateIndex
GlobalSecondaryIndex createDateIndex = new GlobalSecondaryIndex().withIndexName("CreateDateIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("CreateDate").withKeyType(KeyType.HASH), // Partition
// key
new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.RANGE)) // Sort
// key
.withProjection(
new Projection().withProjectionType("INCLUDE").withNonKeyAttributes("Description", "Status"));
// TitleIndex
GlobalSecondaryIndex titleIndex = new GlobalSecondaryIndex().withIndexName("TitleIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("Title").withKeyType(KeyType.HASH), // Partition
// key
new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.RANGE)) // Sort
// key
.withProjection(new Projection().withProjectionType("KEYS_ONLY"));
// DueDateIndex
GlobalSecondaryIndex dueDateIndex = new GlobalSecondaryIndex().withIndexName("DueDateIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("DueDate").withKeyType(KeyType.HASH)) // Partition
// key
.withProjection(new Projection().withProjectionType("ALL"));
CreateTableRequest createTableRequest = new CreateTableRequest().withTableName(tableName)
.withProvisionedThroughput(
new ProvisionedThroughput().withReadCapacityUnits((long) 1).withWriteCapacityUnits((long) 1))
.withAttributeDefinitions(attributeDefinitions).withKeySchema(tableKeySchema)
.withGlobalSecondaryIndexes(createDateIndex, titleIndex, dueDateIndex);
System.out.println("Creating table " + tableName + "...");
dynamoDB.createTable(createTableRequest);
// Wait for table to become active
System.out.println("Waiting for " + tableName + " to become ACTIVE...");
try {
Table table = dynamoDB.getTable(tableName);
table.waitForActive();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static void queryIndex(String indexName) {
Table table = dynamoDB.getTable(tableName);
System.out.println("\n***********************************************************\n");
System.out.print("Querying index " + indexName + "...");
Index index = table.getIndex(indexName);
ItemCollection items = null;
QuerySpec querySpec = new QuerySpec();
if (indexName == "CreateDateIndex") {
System.out.println("Issues filed on 2013-11-01");
querySpec.withKeyConditionExpression("CreateDate = :v_date and begins_with(IssueId, :v_issue)")
.withValueMap(new ValueMap().withString(":v_date", "2013-11-01").withString(":v_issue", "A-"));
items = index.query(querySpec);
} else if (indexName == "TitleIndex") {
System.out.println("Compilation errors");
querySpec.withKeyConditionExpression("Title = :v_title and begins_with(IssueId, :v_issue)")
.withValueMap(
new ValueMap().withString(":v_title", "Compilation error").withString(":v_issue", "A-"));
items = index.query(querySpec);
} else if (indexName == "DueDateIndex") {
System.out.println("Items that are due on 2013-11-30");
querySpec.withKeyConditionExpression("DueDate = :v_date")
.withValueMap(new ValueMap().withString(":v_date", "2013-11-30"));
items = index.query(querySpec);
} else {
System.out.println("\nNo valid index name provided");
return;
}
Iterator
- iterator = items.iterator();
System.out.println("Query: printing results...");
while (iterator.hasNext()) {
System.out.println(iterator.next().toJSONPretty());
}
}
public static void deleteTable(String tableName) {
System.out.println("Deleting table " + tableName + "...");
Table table = dynamoDB.getTable(tableName);
table.delete();
// Wait for table to be deleted
System.out.println("Waiting for " + tableName + " to be deleted...");
try {
table.waitForDelete();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static void loadData() {
System.out.println("Loading data into table " + tableName + "...");
// IssueId, Title,
// Description,
// CreateDate, LastUpdateDate, DueDate,
// Priority, Status
putItem("A-101", "Compilation error", "Can't compile Project X - bad version number. What does this mean?",
"2013-11-01", "2013-11-02", "2013-11-10", 1, "Assigned");
putItem("A-102", "Can't read data file", "The main data file is missing, or the permissions are incorrect",
"2013-11-01", "2013-11-04", "2013-11-30", 2, "In progress");
putItem("A-103", "Test failure", "Functional test of Project X produces errors", "2013-11-01", "2013-11-02",
"2013-11-10", 1, "In progress");
putItem("A-104", "Compilation error", "Variable 'messageCount' was not initialized.", "2013-11-15",
"2013-11-16", "2013-11-30", 3, "Assigned");
putItem("A-105", "Network issue", "Can't ping IP address 127.0.0.1. Please fix this.", "2013-11-15",
"2013-11-16", "2013-11-19", 5, "Assigned");
}
public static void putItem(
String issueId, String title, String description, String createDate, String lastUpdateDate, String dueDate,
Integer priority, String status) {
Table table = dynamoDB.getTable(tableName);
Item item = new Item().withPrimaryKey("IssueId", issueId).withString("Title", title)
.withString("Description", description).withString("CreateDate", createDate)
.withString("LastUpdateDate", lastUpdateDate).withString("DueDate", dueDate)
.withNumber("Priority", priority).withString("Status", status);
table.putItem(item);
}
}
```
# Menggunakan Indek Sekunder Global: .NET
Anda dapat menggunakan API AWS SDK untuk .NET tingkat rendah untuk membuat tabel Amazon DynamoDB dengan satu atau beberapa indeks sekunder global, menjelaskan indeks pada tabel, dan melakukan kueri menggunakan indeks. Operasi ini dipetakan ke operasi DynamoDB yang sesuai. Untuk informasi selengkapnya, lihat [Referensi Amazon DynamoDB API](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).
Berikut ini adalah langkah-langkah umum untuk operasi tabel menggunakan API tingkat rendah .NET.
1. Buat instans dari kelas `AmazonDynamoDBClient`.
1. Berikan parameter wajib dan opsional untuk operasi dengan membuat objek permintaan yang sesuai.
Misalnya, buat objek `CreateTableRequest` untuk membuat tabel dan objek `QueryRequest` untuk mengkueri tabel atau indeks.
1. Jalankan metode sesuai yang ditentukan oleh klien yang Anda buat pada langkah sebelumnya.
**Topics**
+ [Membuat tabel dengan Indeks Sekunder Global](#GSILowLevelDotNet.CreateTableWithIndex)
+ [Mendeskripsikan tabel dengan Indeks Sekunder Global](#GSILowLevelDotNet.DescribeTableWithIndex)
+ [Mengkueri Indeks Sekunder Global](#GSILowLevelDotNet.QueryAnIndex)
+ [Contoh: Indeks Sekunder Global menggunakan API tingkat AWS SDK untuk .NET rendah](GSILowLevelDotNet.Example.md)
## Membuat tabel dengan Indeks Sekunder Global
Anda dapat membuat indeks sekunder global pada saat membuat tabel. Untuk melakukannya, gunakan `CreateTable` dan berikan spesifikasi Anda untuk satu atau beberapa indeks sekunder global. Contoh kode C\$1 berikut membuat tabel untuk menyimpan informasi tentang data cuaca. Kunci partisinya adalah `Location` dan kunci urutannya adalah `Date`. Indeks sekunder global bernama `PrecipIndex` memungkinkan akses cepat ke data curah hujan untuk berbagai lokasi.
Berikut ini adalah langkah-langkah untuk membuat tabel dengan indeks sekunder global, menggunakan API tingkat rendah .NET.
1. Buat instans dari kelas `AmazonDynamoDBClient`.
1. Buat instans dari kelas `CreateTableRequest` untuk memberikan informasi permintaan.
Anda harus memberikan nama tabel, kunci primernya, dan nilai throughput yang ditentukan. Untuk indeks sekunder global, Anda harus memberikan nama indeks, pengaturan throughput yang ditentukan, definisi atribut untuk kunci urutan indeks, skema kunci untuk indeks, dan proyeksi atribut.
1. Jalankan metode `CreateTable` dengan menentukan objek permintaan sebagai parameter.
Contoh kode \$1C berikut mendemonstrasikan langkah sebelumnya. Kode tersebut membuat tabel (`WeatherData`) dengan indeks sekunder global (`PrecipIndex`). Kunci partisi indeksnya adalah `Date` dan kunci urutannya adalah `Precipitation`. Semua atribut tabel diproyeksikan ke dalam indeks. Pengguna dapat mengkueri indeks ini untuk mendapatkan data cuaca untuk tanggal tertentu, yang secara opsional mengurutkan data berdasarkan jumlah curah hujan.
Karena `Precipitation` bukan atribut kunci untuk tabel tersebut, maka tidak diperlukan. Namun, item `WeatherData` tanpa `Precipitation` tidak muncul di `PrecipIndex`.
```
client = new AmazonDynamoDBClient();
string tableName = "WeatherData";
// Attribute definitions
var attributeDefinitions = new List()
{
{new AttributeDefinition{
AttributeName = "Location",
AttributeType = "S"}},
{new AttributeDefinition{
AttributeName = "Date",
AttributeType = "S"}},
{new AttributeDefinition(){
AttributeName = "Precipitation",
AttributeType = "N"}
}
};
// Table key schema
var tableKeySchema = new List()
{
{new KeySchemaElement {
AttributeName = "Location",
KeyType = "HASH"}}, //Partition key
{new KeySchemaElement {
AttributeName = "Date",
KeyType = "RANGE"} //Sort key
}
};
// PrecipIndex
var precipIndex = new GlobalSecondaryIndex
{
IndexName = "PrecipIndex",
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)10,
WriteCapacityUnits = (long)1
},
Projection = new Projection { ProjectionType = "ALL" }
};
var indexKeySchema = new List {
{new KeySchemaElement { AttributeName = "Date", KeyType = "HASH"}}, //Partition key
{new KeySchemaElement{AttributeName = "Precipitation",KeyType = "RANGE"}} //Sort key
};
precipIndex.KeySchema = indexKeySchema;
CreateTableRequest createTableRequest = new CreateTableRequest
{
TableName = tableName,
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)5,
WriteCapacityUnits = (long)1
},
AttributeDefinitions = attributeDefinitions,
KeySchema = tableKeySchema,
GlobalSecondaryIndexes = { precipIndex }
};
CreateTableResponse response = client.CreateTable(createTableRequest);
Console.WriteLine(response.CreateTableResult.TableDescription.TableName);
Console.WriteLine(response.CreateTableResult.TableDescription.TableStatus);
```
Anda harus menunggu hingga DynamoDB membuat tabel dan menetapkan status tabel menjadi `ACTIVE`. Setelah itu, Anda bisa mulai memasukkan item data ke dalam tabel.
## Mendeskripsikan tabel dengan Indeks Sekunder Global
Untuk mendapatkan informasi tentang indeks sekunder global pada sebuah tabel, gunakan `DescribeTable`. Untuk setiap indeks, Anda dapat mengakses namanya, skema kunci, dan atribut yang diproyeksikan.
Berikut ini adalah langkah-langkah untuk mengakses informasi indeks sekunder global untuk tabel menggunakan API tingkat rendah .NET.
1. Buat instans dari kelas `AmazonDynamoDBClient`.
1. Jalankan metode `describeTable` dengan menyediakan objek permintaan sebagai parameter.
Buat instans dari kelas `DescribeTableRequest` untuk memberikan informasi permintaan. Anda harus memberikan nama tabel.
Contoh kode \$1C berikut mendemonstrasikan langkah sebelumnya.
**Example**
```
client = new AmazonDynamoDBClient();
string tableName = "WeatherData";
DescribeTableResponse response = client.DescribeTable(new DescribeTableRequest { TableName = tableName});
List globalSecondaryIndexes =
response.DescribeTableResult.Table.GlobalSecondaryIndexes;
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
foreach (GlobalSecondaryIndexDescription gsiDescription in globalSecondaryIndexes) {
Console.WriteLine("Info for index " + gsiDescription.IndexName + ":");
foreach (KeySchemaElement kse in gsiDescription.KeySchema) {
Console.WriteLine("\t" + kse.AttributeName + ": key type is " + kse.KeyType);
}
Projection projection = gsiDescription.Projection;
Console.WriteLine("\tThe projection type is: " + projection.ProjectionType);
if (projection.ProjectionType.ToString().Equals("INCLUDE")) {
Console.WriteLine("\t\tThe non-key projected attributes are: "
+ projection.NonKeyAttributes);
}
}
```
## Mengkueri Indeks Sekunder Global
Anda dapat menggunakan `Query` pada indeks sekunder global, sama seperti Anda `Query` tabel. Anda perlu menentukan nama indeks, kriteria kueri untuk kunci partisi indeks dan kunci urutan (jika ada), dan atribut yang ingin Anda kembalikan. Dalam contoh ini, indeks adalah `PrecipIndex`, yang memiliki kunci partisi `Date` dan kunci urutan `Precipitation`. Kueri indeks mengembalikan semua data cuaca untuk tanggal tertentu, dengan curah hujan lebih besar dari nol.
Berikut ini adalah langkah-langkah untuk mengkueri indeks sekunder global menggunakan API tingkat rendah .NET.
1. Buat instans dari kelas `AmazonDynamoDBClient`.
1. Buat instans dari kelas `QueryRequest` untuk memberikan informasi permintaan.
1. Jalankan metode `query` dengan menentukan objek permintaan sebagai parameter.
Nama atribut `Date` adalah kata yang disimpan DynamoDB. Oleh karena itu, Anda harus menggunakan nama atribut ekspresi sebagai placeholder di `KeyConditionExpression`.
Contoh kode \$1C berikut mendemonstrasikan langkah sebelumnya.
**Example**
```
client = new AmazonDynamoDBClient();
QueryRequest queryRequest = new QueryRequest
{
TableName = "WeatherData",
IndexName = "PrecipIndex",
KeyConditionExpression = "#dt = :v_date and Precipitation > :v_precip",
ExpressionAttributeNames = new Dictionary {
{"#dt", "Date"}
},
ExpressionAttributeValues = new Dictionary {
{":v_date", new AttributeValue { S = "2013-08-01" }},
{":v_precip", new AttributeValue { N = "0" }}
},
ScanIndexForward = true
};
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
Console.Write(attr + "---> ");
if (attr == "Precipitation")
{
Console.WriteLine(currentItem[attr].N);
}
else
{
Console.WriteLine(currentItem[attr].S);
}
}
Console.WriteLine();
}
```
# Contoh: Indeks Sekunder Global menggunakan API tingkat AWS SDK untuk .NET rendah
Contoh kode C\$1 berikut menunjukkan cara menggunakan indeks sekunder global. Contoh tersebut membuat tabel bernama `Issues`, yang dapat digunakan dalam sistem pelacakan bug sederhana untuk pengembangan perangkat lunak. Kunci partisinya adalah `IssueId` dan kunci urutannya adalah `Title`. Ada tiga indeks sekunder global pada tabel ini:
+ `CreateDateIndex` — Kunci partisinya adalah `CreateDate` dan kunci urutannya adalah `IssueId`. Selain kunci tabel, atribut `Description` dan `Status` diproyeksikan ke dalam indeks.
+ `TitleIndex` — Kunci partisinya adalah `Title` dan kunci urutannya adalah `IssueId`. Tidak ada atribut selain kunci tabel yang diproyeksikan ke dalam indeks.
+ `DueDateIndex` — Kunci partisinya adalah `DueDate`, dan tidak ada kunci urutan. Semua atribut tabel diproyeksikan ke dalam indeks.
Setelah tabel `Issues` dibuat, program memuat tabel dengan data yang mewakili laporan bug perangkat lunak. Kemudian, data dikueri menggunakan indeks sekunder global. Terakhir, program menghapus tabel `Issues`.
Untuk step-by-step petunjuk pengujian sampel berikut, lihat[Contoh kode .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using System.Linq;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelGlobalSecondaryIndexExample
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
public static String tableName = "Issues";
public static void Main(string[] args)
{
CreateTable();
LoadData();
QueryIndex("CreateDateIndex");
QueryIndex("TitleIndex");
QueryIndex("DueDateIndex");
DeleteTable(tableName);
Console.WriteLine("To continue, press enter");
Console.Read();
}
private static void CreateTable()
{
// Attribute definitions
var attributeDefinitions = new List()
{
{new AttributeDefinition {
AttributeName = "IssueId", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "Title", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "CreateDate", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "DueDate", AttributeType = "S"
}}
};
// Key schema for table
var tableKeySchema = new List() {
{
new KeySchemaElement {
AttributeName= "IssueId",
KeyType = "HASH" //Partition key
}
},
{
new KeySchemaElement {
AttributeName = "Title",
KeyType = "RANGE" //Sort key
}
}
};
// Initial provisioned throughput settings for the indexes
var ptIndex = new ProvisionedThroughput
{
ReadCapacityUnits = 1L,
WriteCapacityUnits = 1L
};
// CreateDateIndex
var createDateIndex = new GlobalSecondaryIndex()
{
IndexName = "CreateDateIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "CreateDate", KeyType = "HASH" //Partition key
},
new KeySchemaElement {
AttributeName = "IssueId", KeyType = "RANGE" //Sort key
}
},
Projection = new Projection
{
ProjectionType = "INCLUDE",
NonKeyAttributes = {
"Description", "Status"
}
}
};
// TitleIndex
var titleIndex = new GlobalSecondaryIndex()
{
IndexName = "TitleIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "Title", KeyType = "HASH" //Partition key
},
new KeySchemaElement {
AttributeName = "IssueId", KeyType = "RANGE" //Sort key
}
},
Projection = new Projection
{
ProjectionType = "KEYS_ONLY"
}
};
// DueDateIndex
var dueDateIndex = new GlobalSecondaryIndex()
{
IndexName = "DueDateIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "DueDate",
KeyType = "HASH" //Partition key
}
},
Projection = new Projection
{
ProjectionType = "ALL"
}
};
var createTableRequest = new CreateTableRequest
{
TableName = tableName,
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)1,
WriteCapacityUnits = (long)1
},
AttributeDefinitions = attributeDefinitions,
KeySchema = tableKeySchema,
GlobalSecondaryIndexes = {
createDateIndex, titleIndex, dueDateIndex
}
};
Console.WriteLine("Creating table " + tableName + "...");
client.CreateTable(createTableRequest);
WaitUntilTableReady(tableName);
}
private static void LoadData()
{
Console.WriteLine("Loading data into table " + tableName + "...");
// IssueId, Title,
// Description,
// CreateDate, LastUpdateDate, DueDate,
// Priority, Status
putItem("A-101", "Compilation error",
"Can't compile Project X - bad version number. What does this mean?",
"2013-11-01", "2013-11-02", "2013-11-10",
1, "Assigned");
putItem("A-102", "Can't read data file",
"The main data file is missing, or the permissions are incorrect",
"2013-11-01", "2013-11-04", "2013-11-30",
2, "In progress");
putItem("A-103", "Test failure",
"Functional test of Project X produces errors",
"2013-11-01", "2013-11-02", "2013-11-10",
1, "In progress");
putItem("A-104", "Compilation error",
"Variable 'messageCount' was not initialized.",
"2013-11-15", "2013-11-16", "2013-11-30",
3, "Assigned");
putItem("A-105", "Network issue",
"Can't ping IP address 127.0.0.1. Please fix this.",
"2013-11-15", "2013-11-16", "2013-11-19",
5, "Assigned");
}
private static void putItem(
String issueId, String title,
String description,
String createDate, String lastUpdateDate, String dueDate,
Int32 priority, String status)
{
Dictionary item = new Dictionary();
item.Add("IssueId", new AttributeValue
{
S = issueId
});
item.Add("Title", new AttributeValue
{
S = title
});
item.Add("Description", new AttributeValue
{
S = description
});
item.Add("CreateDate", new AttributeValue
{
S = createDate
});
item.Add("LastUpdateDate", new AttributeValue
{
S = lastUpdateDate
});
item.Add("DueDate", new AttributeValue
{
S = dueDate
});
item.Add("Priority", new AttributeValue
{
N = priority.ToString()
});
item.Add("Status", new AttributeValue
{
S = status
});
try
{
client.PutItem(new PutItemRequest
{
TableName = tableName,
Item = item
});
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
}
private static void QueryIndex(string indexName)
{
Console.WriteLine
("\n***********************************************************\n");
Console.WriteLine("Querying index " + indexName + "...");
QueryRequest queryRequest = new QueryRequest
{
TableName = tableName,
IndexName = indexName,
ScanIndexForward = true
};
String keyConditionExpression;
Dictionary expressionAttributeValues = new Dictionary();
if (indexName == "CreateDateIndex")
{
Console.WriteLine("Issues filed on 2013-11-01\n");
keyConditionExpression = "CreateDate = :v_date and begins_with(IssueId, :v_issue)";
expressionAttributeValues.Add(":v_date", new AttributeValue
{
S = "2013-11-01"
});
expressionAttributeValues.Add(":v_issue", new AttributeValue
{
S = "A-"
});
}
else if (indexName == "TitleIndex")
{
Console.WriteLine("Compilation errors\n");
keyConditionExpression = "Title = :v_title and begins_with(IssueId, :v_issue)";
expressionAttributeValues.Add(":v_title", new AttributeValue
{
S = "Compilation error"
});
expressionAttributeValues.Add(":v_issue", new AttributeValue
{
S = "A-"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else if (indexName == "DueDateIndex")
{
Console.WriteLine("Items that are due on 2013-11-30\n");
keyConditionExpression = "DueDate = :v_date";
expressionAttributeValues.Add(":v_date", new AttributeValue
{
S = "2013-11-30"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else
{
Console.WriteLine("\nNo valid index name provided");
return;
}
queryRequest.KeyConditionExpression = keyConditionExpression;
queryRequest.ExpressionAttributeValues = expressionAttributeValues;
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
if (attr == "Priority")
{
Console.WriteLine(attr + "---> " + currentItem[attr].N);
}
else
{
Console.WriteLine(attr + "---> " + currentItem[attr].S);
}
}
Console.WriteLine();
}
}
private static void DeleteTable(string tableName)
{
Console.WriteLine("Deleting table " + tableName + "...");
client.DeleteTable(new DeleteTableRequest
{
TableName = tableName
});
WaitForTableToBeDeleted(tableName);
}
private static void WaitUntilTableReady(string tableName)
{
string status = null;
// Let us wait until table is created. Call DescribeTable.
do
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
status = res.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found. So we handle the potential exception.
}
} while (status != "ACTIVE");
}
private static void WaitForTableToBeDeleted(string tableName)
{
bool tablePresent = true;
while (tablePresent)
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
}
catch (ResourceNotFoundException)
{
tablePresent = false;
}
}
}
}
}
```
# Bekerja dengan Indeks Sekunder Global di DynamoDB menggunakan AWS CLI
Anda dapat menggunakan AWS CLI untuk membuat tabel Amazon DynamoDB dengan satu atau lebih indeks sekunder global, menjelaskan indeks pada tabel, dan melakukan kueri menggunakan indeks.
**Topics**
+ [Membuat tabel dengan Indeks Sekunder Global](#GCICli.CreateTableWithIndex)
+ [Menambahkan Indeks Sekunder Global ke tabel yang sudah ada](#GCICli.CreateIndexAfterTable)
+ [Mendeskripsikan tabel dengan Indeks Sekunder Global](#GCICli.DescribeTableWithIndex)
+ [Mengkueri Indeks Sekunder Global](#GCICli.QueryAnIndex)
## Membuat tabel dengan Indeks Sekunder Global
Indeks sekunder global dapat dibuat pada saat Anda membuat tabel. Untuk melakukannya, gunakan parameter `create-table` dan berikan spesifikasi Anda untuk satu atau beberapa indeks sekunder global. Contoh berikut membuat tabel bernama `GameScores` dengan indeks sekunder global yang disebut `GameTitleIndex`. Tabel dasar memiliki kunci partisi `UserId` dan kunci urutan `GameTitle`, sehingga Anda dapat menemukan skor terbaik pengguna individu untuk game tertentu secara efisien, sedangkan GSI memiliki kunci partisi `GameTitle` dan kunci urutan `TopScore`, memungkinkan Anda untuk cepat menemukan skor tertinggi secara keseluruhan untuk game tertentu.
```
aws dynamodb create-table \
--table-name GameScores \
--attribute-definitions AttributeName=UserId,AttributeType=S \
AttributeName=GameTitle,AttributeType=S \
AttributeName=TopScore,AttributeType=N \
--key-schema AttributeName=UserId,KeyType=HASH \
AttributeName=GameTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--global-secondary-indexes \
"[
{
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
},
\"ProvisionedThroughput\": {
\"ReadCapacityUnits\": 10,
\"WriteCapacityUnits\": 5
}
}
]"
```
Anda harus menunggu hingga DynamoDB membuat tabel dan menetapkan status tabel menjadi `ACTIVE`. Setelah itu, Anda bisa mulai memasukkan item data ke dalam tabel. Anda dapat menggunakan [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) untuk menentukan status pembuatan tabel.
## Menambahkan Indeks Sekunder Global ke tabel yang sudah ada
Indeks sekunder global juga dapat ditambahkan atau diubah setelah pembuatan tabel. Untuk melakukannya, gunakan parameter `update-table` dan berikan spesifikasi Anda untuk satu atau beberapa indeks sekunder global. Contoh berikut menggunakan skema yang sama seperti contoh sebelumnya, tetapi mengasumsikan bahwa tabel telah dibuat dan GSI akan ditambahkan nanti.
```
aws dynamodb update-table \
--table-name GameScores \
--attribute-definitions AttributeName=TopScore,AttributeType=N \
--global-secondary-index-updates \
"[
{
\"Create\": {
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
}
}
}
]"
```
## Mendeskripsikan tabel dengan Indeks Sekunder Global
Untuk mendapatkan informasi tentang Indeks Sekunder Global pada sebuah tabel, gunakan parameter `describe-table`. Untuk setiap indeks, Anda dapat mengakses namanya, skema kunci, dan atribut yang diproyeksikan.
```
aws dynamodb describe-table --table-name GameScores
```
## Mengkueri Indeks Sekunder Global
Anda dapat menggunakan operasi `query` pada indeks sekunder global dengan cara yang hampir sama seperti Anda `query` tabel. Anda harus menentukan nama indeks, kriteria kueri untuk kunci urutan indeks, dan atribut yang ingin Anda kembalikan. Dalam contoh ini, indeks adalah `GameTitleIndex` dan kunci urutan indeks adalah `GameTitle`.
Satu-satunya atribut yang dikembalikan adalah atribut yang telah diproyeksikan ke dalam indeks. Anda dapat memodifikasi kueri ini untuk memilih atribut non-kunci juga, tetapi ini akan memerlukan aktivitas pengambilan tabel yang relatif mahal. Untuk informasi selengkapnya tentang pengambilan tabel, lihat [Proyeksi atribut](GSI.md#GSI.Projections).
```
aws dynamodb query --table-name GameScores\
--index-name GameTitleIndex \
--key-condition-expression "GameTitle = :v_game" \
--expression-attribute-values '{":v_game":{"S":"Alien Adventure"} }'
```
# Indeks sekunder lokal
Beberapa aplikasi hanya perlu mengkueri data menggunakan kunci primer tabel dasar. Namun, mungkin ada situasi ketika kunci urutan alternatif akan berguna. Untuk memberi aplikasi Anda pilihan kunci urutan, Anda dapat membuat satu atau beberapa indeks sekunder lokal pada tabel Amazon DynamoDB dan mengeluarkan permintaan `Query` atau `Scan` terhadap indeks ini.
**Topics**
+ [Skenario: Menggunakan Indeks Sekunder Lokal](#LSI.Scenario)
+ [Proyeksi atribut](#LSI.Projections)
+ [Membuat Indeks Sekunder Lokal](#LSI.Creating)
+ [Membaca data dari Indeks Sekunder Lokal](#LSI.Reading)
+ [Penulisan item dan Indeks Sekunder Lokal](#LSI.Writes)
+ [Pertimbangan throughput yang disediakan untuk Indeks Sekunder Lokal](#LSI.ThroughputConsiderations)
+ [Pertimbangan penyimpanan untuk Indeks Sekunder Lokal](#LSI.StorageConsiderations)
+ [Kumpulan item dalam Indeks Sekunder Lokal](#LSI.ItemCollections)
+ [Menggunakan Indeks Sekunder Lokal: Java](LSIJavaDocumentAPI.md)
+ [Menggunakan Indeks Sekunder Lokal: .NET](LSILowLevelDotNet.md)
+ [Bekerja dengan Indeks Sekunder Lokal di DynamoDB AWS CLI](LCICli.md)
## Skenario: Menggunakan Indeks Sekunder Lokal
Sebagai contoh, perhatikan `Thread` tabel. Tabel ini berguna untuk aplikasi seperti [forum diskusi AWS](https://forums.aws.amazon.com/). Diagram berikut menunjukkan bagaimana item dalam tabel akan diatur. (Tidak semua atribut ditampilkan.)
![\[Tabel utas yang berisi daftar nama forum, subjek, waktu posting terakhir, dan jumlah balasan.\]](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/LSI_01.png)
DynamoDB menyimpan semua item dengan nilai kunci partisi yang sama secara berkelanjutan. Dalam contoh ini, dengan `ForumName` tertentu, operasi `Query` dapat segera menemukan semua utas untuk forum itu. Dalam grup item dengan nilai kunci partisi yang sama, item diurutkan berdasarkan nilai kunci urutan. Jika kunci urutan (`Subject`) juga disediakan dalam kueri, DynamoDB dapat mempersempit hasil yang dikembalikan—misalnya, mengembalikan semua utas di forum "S3" yang memiliki `Subject` yang diawali dengan huruf "a".
Beberapa permintaan mungkin memerlukan pola akses data yang lebih kompleks. Misalnya:
+ Utas forum mana yang paling banyak dilihat dan mendapatkan balasan?
+ Utas mana di forum tertentu yang memiliki jumlah pesan terbanyak?
+ Berapa banyak utas yang diposting di forum tertentu dalam jangka waktu tertentu?
Untuk menjawab pertanyaan-pertanyaan ini, tindakan `Query` tidak akan cukup. Sebaliknya, Anda harus `Scan` seluruh tabel. Untuk tabel dengan jutaan item, ini akan menghabiskan banyak throughput baca yang disediakan dan membutuhkan waktu lama untuk selesai.
Namun, Anda dapat menentukan satu atau beberapa indeks sekunder lokal pada atribut non-kunci, seperti `Replies` atau `LastPostDateTime`.
*Indeks sekunder lokal* mempertahankan kunci urutan alternatif untuk nilai kunci partisi yang diberikan. Indeks sekunder lokal juga berisi salinan beberapa atau semua atribut dari tabel dasarnya. Anda akan menentukan atribut yang diproyeksikan ke indeks sekunder lokal saat membuat tabel. Data dalam indeks sekunder lokal diatur oleh kunci partisi yang sama dengan tabel dasar, tetapi dengan kunci urutan yang berbeda. Ini memungkinkan Anda mengakses item data secara efisien di seluruh dimensi yang berbeda ini. Untuk fleksibilitas kueri atau pemindaian yang lebih baik, Anda dapat membuat hingga lima indeks sekunder lokal per tabel.
Misalkan sebuah aplikasi perlu menemukan semua utas yang telah diposting dalam tiga bulan terakhir di forum tertentu. Tanpa indeks sekunder lokal, aplikasi harus `Scan` seluruh tabel `Thread` dan membuang postingan apa pun yang tidak berada dalam periode waktu yang ditentukan. Dengan indeks sekunder lokal, operasi `Query` dapat menggunakan `LastPostDateTime` sebagai kunci urutan dan menemukan data dengan cepat.
Diagram berikut menunjukkan indeks sekunder lokal bernama `LastPostIndex`. Perhatikan bahwa kunci partisi sama dengan tabel `Thread`, tetapi kunci urutannya adalah `LastPostDateTime`.
![\[LastPostIndex tabel yang berisi daftar nama forum, subjek, dan waktu posting terakhir.\]](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/LSI_02.png)
Setiap indeks sekunder lokal harus memenuhi syarat berikut:
+ Kunci partisi sama dengan tabel dasarnya.
+ Kunci urutan terdiri dari satu atribut skalar.
+ Kunci urutan tabel dasar diproyeksikan ke dalam indeks, tempat kunci tersebut berfungsi sebagai atribut non-kunci.
Dalam contoh ini, kunci partisi adalah `ForumName` dan kunci urutan indeks sekunder lokal adalah `LastPostDateTime`. Selain itu, nilai kunci urutan dari tabel dasar (dalam contoh ini, `Subject`) diproyeksikan ke dalam indeks, tetapi bukan merupakan bagian dari kunci indeks. Jika aplikasi membutuhkan daftar yang didasarkan pada `ForumName` dan `LastPostDateTime`, aplikasi dapat mengeluarkan permintaan `Query` terhadap `LastPostIndex`. Hasil kueri diurutkan menurut `LastPostDateTime`, dan dapat dikembalikan dalam urutan menaik atau menurun. Kueri juga dapat menerapkan syarat kunci, seperti hanya mengembalikan item yang memiliki `LastPostDateTime` dalam rentang waktu tertentu.
Setiap indeks sekunder lokal otomatis berisi kunci partisi dan kunci urutan dari tabel dasarnya; Anda secara opsional dapat memproyeksikan atribut non-kunci ke dalam indeks. Saat Anda mengkueri indeks, DynamoDB dapat mengambil atribut yang diproyeksikan ini secara efisien. Saat Anda mengkueri indeks sekunder lokal, kueri juga dapat mengambil atribut yang *tidak* diproyeksikan ke dalam indeks. DynamoDB otomatis mengambil atribut ini dari tabel dasar, tetapi dengan latensi lebih besar dan dengan biaya throughput yang disediakan lebih tinggi.
Untuk indeks sekunder lokal apa pun, Anda dapat menyimpan hingga 10 GB data per nilai kunci partisi yang berbeda. Angka ini mencakup semua item dalam tabel dasar, ditambah semua item dalam indeks, yang memiliki nilai kunci partisi yang sama. Untuk informasi selengkapnya, lihat [Kumpulan item dalam Indeks Sekunder Lokal](#LSI.ItemCollections).
## Proyeksi atribut
Dengan `LastPostIndex`, sebuah aplikasi dapat menggunakan `ForumName` dan `LastPostDateTime` sebagai kriteria kueri. Namun, untuk mengambil atribut tambahan apa pun, DynamoDB harus melakukan operasi baca tambahan terhadap tabel `Thread`. Pembacaan tambahan ini dikenal sebagai *pengambilan*, dan pembacaan tersebut dapat meningkatkan jumlah total throughput yang disediakan yang diperlukan untuk kueri.
Misalkan Anda ingin mengisi halaman web dengan daftar semua utas di “S3" dan jumlah balasan untuk setiap utas, diurutkan berdasarkan balasan terakhir yang date/time dimulai dengan balasan terbaru. Untuk mengisi daftar ini, Anda memerlukan atribut berikut:
+ `Subject`
+ `Replies`
+ `LastPostDateTime`
Cara paling efisien untuk mengkueri data ini dan untuk menghindari operasi pengambilan adalah dengan memproyeksikan atribut `Replies` dari tabel ke dalam indeks sekunder lokal, seperti yang ditunjukkan dalam diagram ini.
![\[LastPostIndex tabel yang berisi daftar nama forum, waktu posting terakhir, subjek, dan balasan.\]](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/LSI_03.png)
*Proyeksi* adalah kumpulan atribut yang disalin dari tabel ke indeks sekunder. Kunci partisi dan kunci urutan tabel selalu diproyeksikan ke dalam indeks; Anda dapat memproyeksikan atribut lain untuk mendukung persyaratan kueri aplikasi Anda. Saat Anda mengkueri indeks, Amazon DynamoDB dapat mengakses atribut apa pun dalam proyeksi seolah-olah atribut tersebut berada dalam tabelnya sendiri.
Saat membuat indeks sekunder, Anda perlu menentukan atribut yang akan diproyeksikan ke dalam indeks. DynamoDB menyediakan tiga opsi berbeda untuk ini:
+ *KEYS\$1ONLY* – Setiap item dalam indeks hanya terdiri dari kunci partisi tabel dan nilai kunci urutan, ditambah nilai kunci indeks. Opsi `KEYS_ONLY` menghasilkan indeks sekunder sekecil mungkin.
+ *INCLUDE* – Selain atribut yang dijelaskan dalam `KEYS_ONLY`, indeks sekunder akan menyertakan atribut non-kunci lain yang Anda tentukan.
+ *ALL* – Indeks sekunder menyertakan semua atribut dari tabel sumber. Karena semua data tabel diduplikasi dalam indeks, proyeksi `ALL` menghasilkan indeks sekunder sebesar yang mungkin.
Pada diagram sebelumnya, atribut non-kunci `Replies` diproyeksikan ke dalam `LastPostIndex`. Aplikasi dapat meminta `LastPostIndex` sebagai ganti dari tabel `Thread` lengkap untuk mengisi halaman web dengan `Subject`, `Replies`, dan `LastPostDateTime`. Jika ada atribut non-kunci lain yang diminta, DynamoDB perlu mengambil atribut tersebut dari tabel `Thread`.
Dari sudut pandang aplikasi, pengambilan atribut tambahan dari tabel dasar dilakukan secara otomatis dan transparan, jadi tidak perlu menulis ulang logika aplikasi apa pun. Namun, pengambilan tersebut dapat sangat mengurangi keuntungan performa menggunakan indeks sekunder lokal.
Saat memilih atribut untuk diproyeksikan ke dalam indeks sekunder lokal, Anda harus mempertimbangkan tradeoff antara biaya throughput yang disediakan dan biaya penyimpanan:
+ Jika Anda hanya perlu mengakses beberapa atribut dengan latensi serendah mungkin, pertimbangkan untuk hanya memproyeksikan atribut tersebut ke dalam indeks sekunder lokal. Semakin kecil indeks, semakin sedikit biaya penyimpanannya, dan semakin sedikit pula biaya tulis Anda. Jika ada atribut yang terkadang perlu Anda ambil, biaya untuk throughput yang disediakan mungkin lebih besar daripada biaya jangka panjang untuk menyimpan atribut tersebut.
+ Jika aplikasi Anda sering mengakses beberapa atribut non-kunci, sebaiknya Anda memproyeksikan atribut tersebut ke dalam indeks sekunder lokal. Biaya penyimpanan tambahan untuk indeks sekunder lokal mengimbangi biaya melakukan pemindaian tabel yang sering dilakukan.
+ Jika sering mengakses sebagian besar atribut non-kunci, Anda dapat memproyeksikan atribut ini—atau bahkan seluruh tabel dasar— ke dalam indeks sekunder lokal. Ini memberi Anda fleksibilitas maksimum dan penggunaan persediaan throughput terendah, karena pengambilan tidak diperlukan. Namun, biaya penyimpanan Anda akan meningkat, atau bahkan dua kali lipat jika Anda memproyeksikan semua atribut.
+ Jika aplikasi Anda jarang mengkueri tabel, tetapi harus melakukan banyak penulisan atau pembaruan terhadap data dalam tabel, pertimbangkan untuk memproyeksikan *KEYS\$1ONLY*. Indeks sekunder lokal akan berukuran minimal, tetapi akan tetap tersedia jika diperlukan untuk aktivitas kueri.
## Membuat Indeks Sekunder Lokal
Untuk membuat satu atau beberapa indeks sekunder lokal pada tabel, gunakan parameter `LocalSecondaryIndexes` operasi `CreateTable`. Indeks sekunder lokal pada tabel dibuat saat tabel dibuat. Saat Anda menghapus tabel, indeks sekunder lokal apa pun di tabel itu juga akan dihapus.
Anda harus menentukan satu atribut non-kunci untuk berfungsi sebagai kunci urutan indeks sekunder lokal. Atribut yang Anda pilih harus berupa skalar `String`, `Number`, atau `Binary`. Jenis skalar, jenis dokumen, dan jenis kumpulan lain tidak diperbolehkan. Untuk daftar lengkap jenis data, lihat [Jenis Data](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes).
**penting**
Untuk tabel dengan indeks sekunder lokal, ada batas ukuran 10 GB per nilai kunci partisi. Tabel dengan indeks sekunder lokal dapat menyimpan berapa pun jumlah item, asalkan ukuran total untuk nilai kunci satu partisi tidak melebihi 10 GB. Untuk informasi selengkapnya, lihat [Batas ukuran kumpulan item](#LSI.ItemCollections.SizeLimit).
Anda dapat memproyeksikan atribut jenis data apa pun ke dalam indeks sekunder lokal. Ini termasuk skalar, dokumen, dan kumpulan. Untuk daftar lengkap jenis data, lihat [Jenis Data](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes).
## Membaca data dari Indeks Sekunder Lokal
Anda dapat mengambil item dari indeks sekunder lokal menggunakan operasi `Query` dan `Scan`. Operasi `GetItem` dan `BatchGetItem` tidak dapat digunakan pada indeks sekunder lokal.
### Mengkueri Indeks Sekunder Lokal
Dalam tabel DynamoDB, nilai kunci partisi gabungan dan nilai kunci urutan untuk setiap item harus unik. Namun, dalam indeks sekunder lokal, nilai kunci urutan tidak perlu unik untuk nilai kunci partisi yang diberikan. Jika ada beberapa item dalam indeks sekunder lokal yang memiliki nilai kunci urutan yang sama, operasi `Query` mengembalikan semua item yang memiliki nilai kunci partisi yang sama. Sebagai respons, item yang cocok tidak dikembalikan dalam urutan tertentu.
Anda dapat mengkueri indeks sekunder lokal menggunakan bacaan akhir konsisten atau bacaan sangat konsisten. Untuk menentukan jenis konsistensi yang Anda inginkan, gunakan parameter `ConsistentRead` operasi `Query`. Bacaan sangat konsisten dari indeks sekunder lokal selalu mengembalikan nilai terbaru yang diperbarui. Jika kueri perlu mengambil atribut tambahan dari tabel dasar, atribut tersebut akan konsisten dengan indeks.
**Example**
Pertimbangkan data berikut yang dikembalikan dari `Query` yang meminta data dari utas diskusi di forum tertentu.
```
{
"TableName": "Thread",
"IndexName": "LastPostIndex",
"ConsistentRead": false,
"ProjectionExpression": "Subject, LastPostDateTime, Replies, Tags",
"KeyConditionExpression":
"ForumName = :v_forum and LastPostDateTime between :v_start and :v_end",
"ExpressionAttributeValues": {
":v_start": {"S": "2015-08-31T00:00:00.000Z"},
":v_end": {"S": "2015-11-31T00:00:00.000Z"},
":v_forum": {"S": "EC2"}
}
}
```
Dalam kueri ini:
+ DynamoDB mengakses `LastPostIndex`, menggunakan kunci partisi `ForumName` untuk menemukan item indeks untuk "EC2". Semua item indeks dengan kunci ini disimpan berdekatan satu sama lain untuk pengambilan cepat.
+ Dalam forum ini, DynamoDB menggunakan indeks untuk mencari kunci yang cocok dengan syarat `LastPostDateTime` yang ditentukan.
+ Karena atribut `Replies` diproyeksikan ke dalam indeks, DynamoDB dapat mengambil atribut ini tanpa menggunakan throughput tambahan yang disediakan.
+ Atribut `Tags` tidak diproyeksikan ke dalam indeks, jadi DynamoDB harus mengakses tabel `Thread` dan mengambil atribut ini.
+ Hasilnya ditampilkan, diurutkan berdasarkan `LastPostDateTime`. Entri indeks diurutkan menurut nilai kunci partisi dan kemudian menurut nilai kunci urutan, dan `Query` mengembalikannya sesuai urutan penyimpanannya. (Anda dapat menggunakan parameter `ScanIndexForward` untuk mengembalikan hasil dalam urutan menurun.)
Karena atribut `Tags` tidak diproyeksikan ke indeks sekunder lokal, DynamoDB harus menggunakan unit kapasitas baca tambahan untuk mengambil atribut ini dari tabel dasar. Jika sering menjalankan kueri ini, Anda harus memproyeksikan `Tags` ke `LastPostIndex` untuk menghindari pengambilan dari tabel dasar. Namun, jika Anda hanya perlu mengakses `Tags` sesekali, biaya penyimpanan tambahan untuk memproyeksikan `Tags` ke dalam indeks mungkin tidak bermanfaat.
### Memindai Indeks Sekunder Lokal
Anda dapat menggunakan `Scan` untuk mengambil semua data dari indeks sekunder lokal. Anda harus memberikan nama tabel dasar dan nama indeks dalam permintaan. Dengan `Scan`, DynamoDB membaca semua data dalam indeks dan mengembalikannya ke aplikasi. Anda juga dapat meminta agar hanya sebagian data yang dikembalikan, dan data yang tersisa harus dibuang. Untuk melakukannya, gunakan parameter `FilterExpression` API `Scan`. Untuk informasi selengkapnya, lihat [Ekspresi filter untuk pemindaian](Scan.md#Scan.FilterExpression).
## Penulisan item dan Indeks Sekunder Lokal
DynamoDB otomatis membuat semua indeks sekunder lokal tersinkronisasi dengan tabel dasar masing-masing. Aplikasi tidak pernah menulis langsung ke indeks. Namun, Anda harus memahami implikasi dari cara DynamoDB mempertahankan indeks ini.
Saat membuat indeks sekunder lokal, Anda menentukan atribut untuk dijadikan sebagai kunci urutan untuk indeks. Anda juga menentukan jenis data untuk atribut tersebut. Artinya, setiap kali Anda menulis item ke tabel dasar, jika item tersebut mendefinisikan atribut kunci indeks, jenisnya harus cocok dengan jenis data skema kunci indeks. Dalam kasus `LastPostIndex`, kunci urutan `LastPostDateTime` dalam indeks didefinisikan sebagai jenis data `String`. Jika Anda mencoba menambahkan item ke tabel `Thread` dan menentukan jenis data yang berbeda untuk `LastPostDateTime` (seperti `Number`), DynamoDB mengembalikan `ValidationException` karena jenis data tidak cocok.
Tidak ada persyaratan untuk one-to-one hubungan antara item dalam tabel dasar dan item dalam indeks sekunder lokal. Bahkan, perilaku ini dapat menguntungkan untuk banyak aplikasi.
Tabel dengan banyak indeks sekunder lokal menimbulkan biaya lebih tinggi untuk aktivitas tulis dibandingkan tabel dengan lebih sedikit indeks. Untuk informasi selengkapnya, lihat [Pertimbangan throughput yang disediakan untuk Indeks Sekunder Lokal](#LSI.ThroughputConsiderations).
**penting**
Untuk tabel dengan indeks sekunder lokal, ada batas ukuran 10 GB per nilai kunci partisi. Tabel dengan indeks sekunder lokal dapat menyimpan berapa pun jumlah item, asalkan ukuran total untuk nilai kunci satu partisi tidak melebihi 10 GB. Untuk informasi selengkapnya, lihat [Batas ukuran kumpulan item](#LSI.ItemCollections.SizeLimit).
## Pertimbangan throughput yang disediakan untuk Indeks Sekunder Lokal
Saat membuat tabel di DynamoDB, Anda menyediakan unit kapasitas baca dan tulis untuk beban kerja tabel yang diharapkan. Beban kerja tersebut mencakup aktivitas baca dan tulis pada indeks sekunder lokal tabel.
Untuk melihat tarif saat ini untuk kapasitas throughput yang disediakan, lihat [Harga Amazon DynamoDB](https://aws.amazon.com/dynamodb/pricing).
### Unit kapasitas baca
Saat Anda mengkueri indeks sekunder lokal, jumlah unit kapasitas baca yang digunakan bergantung pada cara data diakses.
Seperti kueri tabel, kueri indeks dapat menggunakan bacaan akhir konsisten atau bacaan sangat konsisten, tergantung pada nilai `ConsistentRead`. Satu bacaan sangat konsisten menghabiskan satu unit kapasitas baca; bacaan akhir konsisten hanya menghabiskan setengahnya. Jadi, dengan memilih bacaan akhir konsisten, Anda dapat mengurangi biaya unit kapasitas baca Anda.
Untuk kueri indeks yang hanya meminta kunci indeks dan atribut yang diproyeksikan, DynamoDB menghitung aktivitas baca yang disediakan dengan cara yang sama seperti kueri terhadap tabel. Satu-satunya hal yang membedakan adalah penghitungan didasarkan pada ukuran entri indeks, bukan ukuran item dalam tabel dasar. Jumlah unit kapasitas baca adalah jumlah dari semua ukuran atribut yang diproyeksikan di semua item yang dikembalikan; hasilnya kemudian dibulatkan ke batas 4 KB berikutnya. Untuk informasi selengkapnya tentang cara DynamoDB menghitung penggunaan throughput yang disediakan, lihat [DynamoDB menyediakan mode kapasitas](provisioned-capacity-mode.md).
Untuk kueri indeks yang membaca atribut yang tidak diproyeksikan ke indeks sekunder lokal, DynamoDB perlu mengambil atribut tersebut dari tabel dasar, selain membaca atribut yang diproyeksikan dari indeks. Pengambilan ini terjadi saat Anda menyertakan atribut yang tidak diproyeksikan dalam parameter `Select` atau `ProjectionExpression` operasi `Query`. Pengambilan menyebabkan latensi tambahan dalam respons kueri, dan juga menimbulkan biaya throughput yang disediakan lebih tinggi: Selain pembacaan dari indeks sekunder lokal yang dijelaskan sebelumnya, Anda dikenakan biaya untuk unit kapasitas baca untuk setiap item tabel dasar yang diambil. Biaya ini untuk pembacaan setiap item dari tabel, bukan hanya atribut yang diminta.
Ukuran maksimum hasil yang dikembalikan oleh operasi `Query` adalah 1 MB. Ini termasuk ukuran semua nama dan nilai atribut di semua item yang dikembalikan. Namun, jika Kueri terhadap indeks sekunder lokal menyebabkan DynamoDB mengambil atribut item dari tabel dasar, ukuran maksimum data dalam hasil mungkin lebih rendah. Dalam hal ini, ukuran hasil adalah jumlah dari:
+ Ukuran item yang cocok dalam indeks, dibulatkan ke atas hingga 4 KB berikutnya.
+ Ukuran setiap item yang cocok di tabel dasar, dengan setiap item dibulatkan satu per satu ke 4 KB berikutnya.
Menggunakan rumus ini, ukuran maksimum hasil yang dikembalikan oleh operasi Kueri masih 1 MB.
Misalnya, pertimbangkan tabel tempat ukuran setiap item adalah 300 byte. Ada indeks sekunder lokal di tabel itu, tetapi hanya 200 byte dari setiap item yang diproyeksikan ke dalam indeks. Sekarang anggaplah Anda `Query` indeks ini, bahwa kueri memerlukan pengambilan tabel untuk setiap item, dan kueri mengembalikan 4 item. DynamoDB merangkum berikut ini:
+ Ukuran item yang cocok dalam indeks: 200 byte × 4 item = 800 byte; ini kemudian dibulatkan menjadi 4 KB.
+ Ukuran setiap item yang cocok di tabel dasar: (300 byte, dibulatkan hingga 4 KB) × 4 item = 16 KB.
Oleh karena itu, ukuran total data dalam hasil adalah 20 KB.
### Unit kapasitas tulis
Saat item dalam tabel ditambahkan, diperbarui, atau dihapus, memperbarui indeks sekunder lokal akan menggunakan unit kapasitas tulis yang disediakan untuk tabel tersebut. Total biaya throughput yang disediakan untuk penulisan adalah jumlah unit kapasitas tulis yang digunakan dengan menulis ke tabel dan yang digunakan dengan memperbarui indeks sekunder lokal.
Biaya tulis item ke indeks sekunder lokal tergantung pada beberapa faktor:
+ Jika Anda menulis item baru ke tabel yang menentukan atribut yang diindeks, atau Anda memperbarui item yang ada untuk menentukan atribut terindeks yang sebelumnya tidak ditentukan, satu operasi tulis diperlukan untuk memasukkan item ke dalam indeks.
+ Jika pembaruan pada tabel mengubah nilai atribut kunci yang diindeks (dari A menjadi B), diperlukan dua penulisan: satu untuk menghapus item sebelumnya dari indeks dan satu lagi untuk memasukkan item baru ke dalam indeks.
+ Jika suatu item ada dalam indeks, tetapi penulisan ke tabel menyebabkan atribut yang diindeks terhapus, satu penulisan diperlukan untuk menghapus proyeksi item lama dari indeks.
+ Jika item tidak ada dalam indeks sebelum atau setelah item diperbarui, tidak ada biaya penulisan tambahan untuk indeks tersebut.
Semua faktor ini mengasumsikan bahwa ukuran setiap item dalam indeks kurang dari atau sama dengan ukuran item 1 KB untuk menghitung unit kapasitas tulis. Entri indeks yang lebih besar memerlukan unit kapasitas tulis tambahan. Anda dapat meminimalkan biaya penulisan dengan mempertimbangkan atribut yang perlu dikembalikan oleh kueri dan hanya memproyeksikan atribut tersebut ke dalam indeks.
## Pertimbangan penyimpanan untuk Indeks Sekunder Lokal
Saat aplikasi menulis item ke tabel, DynamoDB otomatis menyalin subset atribut yang benar ke indeks sekunder lokal tempat atribut tersebut akan muncul. AWS Akun Anda dikenakan biaya untuk penyimpanan item di tabel dasar dan juga untuk penyimpanan atribut dalam indeks sekunder lokal apa pun di tabel itu.
Jumlah ruang yang digunakan oleh item indeks adalah jumlah dari berikut ini:
+ Ukuran kunci primer tabel dasar dalam byte (kunci partisi dan kunci urutan)
+ Ukuran atribut kunci indeks dalam byte
+ Ukuran atribut yang diproyeksikan dalam byte (jika ada)
+ 100 byte dari overhead per item indeks
Untuk memperkirakan kebutuhan penyimpanan indeks sekunder lokal, Anda dapat memperkirakan ukuran rata-rata item dalam indeks lalu mengalikannya dengan jumlah item di index.
Jika tabel berisi item dengan atribut tertentu tidak ditentukan, tetapi atribut tersebut didefinisikan sebagai kunci urutan indeks, maka DynamoDB tidak menulis data apa pun untuk item tersebut ke indeks.
## Kumpulan item dalam Indeks Sekunder Lokal
**catatan**
Bagian ini hanya berkaitan dengan tabel yang memiliki indeks sekunder lokal.
Di DynamoDB, *kumpulan item* adalah grup item yang memiliki nilai kunci partisi yang sama dalam tabel dan semua indeks sekunder lokalnya. Dalam contoh yang digunakan di seluruh bagian ini, kunci partisi untuk tabel `Thread` adalah `ForumName`, dan kunci partisi untuk `LastPostIndex` juga `ForumName`. Semua item tabel dan indeks dengan `ForumName` yang sama adalah bagian dari kumpulan item yang sama. Misalnya, di tabel `Thread` dan indeks sekunder lokal `LastPostIndex`, terdapat kumpulan item untuk forum `EC2` dan kumpulan item yang berbeda untuk forum `RDS`.
Diagram berikut menunjukkan kumpulan item untuk forum `S3`.
![\[Koleksi item DynamoDB dengan tabel dan item Indeks Sekunder Lokal yang memiliki nilai kunci partisi yang sama. S3\]](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/LSI_04.png)
Dalam diagram ini, kumpulan item terdiri dari semua item di `Thread` dan `LastPostIndex` dengan nilai kunci partisi `ForumName`-nya adalah "S3". Jika terdapat indeks sekunder lokal lainnya di tabel, item apa pun dalam indeks tersebut dengan `ForumName` yang sama dengan "S3" juga akan menjadi bagian dari kumpulan item.
Anda dapat menggunakan salah satu operasi berikut di DynamoDB untuk menampilkan informasi tentang kumpulan item:
+ `BatchWriteItem`
+ `DeleteItem`
+ `PutItem`
+ `UpdateItem`
+ `TransactWriteItems`
Masing-masing operasi ini mendukung parameter `ReturnItemCollectionMetrics`. Jika mengatur parameter ini ke `SIZE`, Anda dapat melihat informasi tentang ukuran setiap kumpulan item dalam indeks.
**Example**
Berikut ini adalah contoh dari output operasi `UpdateItem` pada tabel `Thread`, dengan `ReturnItemCollectionMetrics` diatur ke `SIZE`. Item yang diperbarui memiliki nilai `ForumName` "EC2", jadi outputnya mencakup informasi tentang kumpulan item tersebut.
```
{
ItemCollectionMetrics: {
ItemCollectionKey: {
ForumName: "EC2"
},
SizeEstimateRangeGB: [0.0, 1.0]
}
}
```
Objek `SizeEstimateRangeGB` menunjukkan bahwa ukuran kumpulan item ini antara 0 dan 1 GB. DynamoDB memperbarui perkiraan ukuran ini secara berkala, sehingga jumlahnya mungkin berbeda saat item diubah lagi.
### Batas ukuran kumpulan item
Ukuran maksimum kumpulan item apa pun untuk tabel yang memiliki satu atau beberapa indeks sekunder lokal adalah 10 GB. Ini tidak berlaku untuk kumpulan item dalam tabel tanpa indeks sekunder lokal, dan juga tidak berlaku untuk kumpulan item dalam indeks sekunder global. Hanya tabel yang memiliki satu atau beberapa indeks sekunder lokal yang terpengaruh.
Jika koleksi item melebihi batas 10 GB, DynamoDB dapat mengembalikan`ItemCollectionSizeLimitExceededException`, dan Anda mungkin tidak dapat menambahkan lebih banyak item ke koleksi item atau menambah ukuran item yang ada dalam koleksi item. (Operasi baca dan tulis yang mengecilkan ukuran kumpulan item masih diperbolehkan.) Anda masih dapat menambahkan item ke kumpulan item lain.
Untuk mengurangi ukuran kumpulan item, Anda dapat melakukan salah satu berikut ini:
+ Hapus item yang tidak diperlukan dengan nilai kunci partisi terkait. Jika Anda menghapus item ini dari tabel dasar, DynamoDB juga menghapus entri indeks yang memiliki nilai kunci partisi yang sama.
+ Perbarui item dengan menghapus atribut atau dengan mengurangi ukuran atribut. Jika atribut ini diproyeksikan ke indeks sekunder lokal, DynamoDB juga mengurangi ukuran entri indeks terkait.
+ Buat tabel baru dengan kunci partisi dan kunci urutan yang sama, lalu pindahkan item dari tabel lama ke tabel baru. Ini mungkin merupakan pendekatan yang tepat jika tabel memiliki data historis yang jarang diakses. Anda juga dapat mempertimbangkan untuk mengarsipkan data historis ini ke Amazon Simple Storage Service (Amazon S3).
Ketika ukuran total kumpulan item turun di bawah 10 GB, Anda dapat menambahkan item dengan nilai kunci partisi yang sama sekali lagi.
Sebagai praktik terbaik, sebaiknya Anda melengkapi aplikasi Anda untuk memantau ukuran kumpulan item Anda. Salah satu cara untuk melakukannya adalah dengan mengatur parameter `ReturnItemCollectionMetrics` ke `SIZE` setiap kali Anda menggunakan `BatchWriteItem`, `DeleteItem`, `PutItem`, atau `UpdateItem`. Aplikasi Anda akan memeriksa objek `ReturnItemCollectionMetrics` di output dan mencatat pesan kesalahan setiap kali kumpulan item melebihi batas yang ditentukan pengguna (8 GB, misalnya). Menetapkan batas kurang dari 10 GB akan memberi sistem peringatan dini sehingga Anda mengetahui bahwa kumpulan item mendekati batas, dan Anda dapat melakukan tindakan terhadap hal tersebut.
### Kumpulan dan partisi item
Di tabel dengan satu atau beberapa indeks sekunder lokal, masing-masing kumpulan item disimpan dalam satu partisi. Ukuran total kumpulan item tersebut terbatas pada kemampuan partisi itu: 10 GB. Untuk aplikasi yang model datanya menyertakan kumpulan item yang ukurannya tidak dibatasi, atau jika Anda memperkirakan beberapa kumpulan item akan bertambah melebihi 10 GB di masa mendatang, Anda sebaiknya mempertimbangkan untuk menggunakan indeks sekunder global.
Anda harus merancang aplikasi Anda sehingga data tabel didistribusikan secara merata ke seluruh nilai kunci partisi yang berbeda. Untuk tabel dengan indeks sekunder lokal, aplikasi Anda tidak boleh membuat "hot spot" aktivitas baca dan tulis dalam satu kumpulan item pada satu partisi.
# Menggunakan Indeks Sekunder Lokal: Java
Anda dapat menggunakan AWS SDK untuk Java Document API untuk membuat tabel Amazon DynamoDB dengan satu atau beberapa indeks sekunder lokal, menjelaskan indeks pada tabel, dan melakukan kueri menggunakan indeks.
Berikut ini adalah langkah-langkah umum untuk operasi tabel menggunakan AWS SDK untuk Java Document API.
1. Buat instans dari kelas `DynamoDB`.
1. Berikan parameter wajib dan opsional untuk operasi dengan membuat objek permintaan yang sesuai.
1. Panggil metode sesuai yang ditentukan oleh klien yang Anda buat pada langkah sebelumnya.
**Topics**
+ [Membuat tabel dengan Indeks Sekunder Lokal](#LSIJavaDocumentAPI.CreateTableWithIndex)
+ [Mendeskripsikan tabel dengan Indeks Sekunder Lokal](#LSIJavaDocumentAPI.DescribeTableWithIndex)
+ [Mengkueri Indeks Sekunder Lokal](#LSIJavaDocumentAPI.QueryAnIndex)
+ [Contoh: Indeks Sekunder Lokal menggunakan API dokumen Java](LSIJavaDocumentAPI.Example.md)
## Membuat tabel dengan Indeks Sekunder Lokal
Indeks sekunder lokal harus dibuat pada saat Anda membuat tabel. Untuk melakukannya, gunakan metode `createTable` dan berikan spesifikasi Anda untuk satu atau beberapa indeks sekunder lokal. Contoh kode Java berikut membuat tabel untuk menyimpan informasi tentang lagu dalam koleksi musik. Kunci partisinya adalah `Artist` dan kunci urutannya adalah `SongTitle`. Indeks sekunder, `AlbumTitleIndex`, memfasilitasi kueri berdasarkan judul album.
Berikut adalah langkah-langkah untuk membuat tabel dengan indeks sekunder lokal, menggunakan API dokumen DynamoDB.
1. Buat instans dari kelas `DynamoDB`.
1. Buat instans dari kelas `CreateTableRequest` untuk memberikan informasi permintaan.
Anda harus memberikan nama tabel, kunci primernya, dan nilai throughput yang ditentukan. Untuk indeks sekunder lokal, Anda harus memberikan nama indeks, nama dan jenis data untuk kunci urutan indeks, skema kunci untuk indeks, dan proyeksi atribut.
1. Panggil metode `createTable` dengan menentukan objek permintaan sebagai parameter.
Contoh kode Java berikut mendemonstrasikan langkah sebelumnya. Kode ini membuat tabel (`Music`) dengan indeks sekunder pada atribut `AlbumTitle`. Kunci urutan dan kunci partisi tabel, ditambah kunci urutan indeks, adalah satu-satunya atribut yang diproyeksikan ke dalam indeks.
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
CreateTableRequest createTableRequest = new CreateTableRequest().withTableName(tableName);
//ProvisionedThroughput
createTableRequest.setProvisionedThroughput(new ProvisionedThroughput().withReadCapacityUnits((long)5).withWriteCapacityUnits((long)5));
//AttributeDefinitions
ArrayList attributeDefinitions= new ArrayList();
attributeDefinitions.add(new AttributeDefinition().withAttributeName("Artist").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("SongTitle").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("AlbumTitle").withAttributeType("S"));
createTableRequest.setAttributeDefinitions(attributeDefinitions);
//KeySchema
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement().withAttributeName("Artist").withKeyType(KeyType.HASH)); //Partition key
tableKeySchema.add(new KeySchemaElement().withAttributeName("SongTitle").withKeyType(KeyType.RANGE)); //Sort key
createTableRequest.setKeySchema(tableKeySchema);
ArrayList indexKeySchema = new ArrayList();
indexKeySchema.add(new KeySchemaElement().withAttributeName("Artist").withKeyType(KeyType.HASH)); //Partition key
indexKeySchema.add(new KeySchemaElement().withAttributeName("AlbumTitle").withKeyType(KeyType.RANGE)); //Sort key
Projection projection = new Projection().withProjectionType(ProjectionType.INCLUDE);
ArrayList nonKeyAttributes = new ArrayList();
nonKeyAttributes.add("Genre");
nonKeyAttributes.add("Year");
projection.setNonKeyAttributes(nonKeyAttributes);
LocalSecondaryIndex localSecondaryIndex = new LocalSecondaryIndex()
.withIndexName("AlbumTitleIndex").withKeySchema(indexKeySchema).withProjection(projection);
ArrayList localSecondaryIndexes = new ArrayList();
localSecondaryIndexes.add(localSecondaryIndex);
createTableRequest.setLocalSecondaryIndexes(localSecondaryIndexes);
Table table = dynamoDB.createTable(createTableRequest);
System.out.println(table.getDescription());
```
Anda harus menunggu hingga DynamoDB membuat tabel dan menetapkan status tabel menjadi `ACTIVE`. Setelah itu, Anda bisa mulai memasukkan item data ke dalam tabel.
## Mendeskripsikan tabel dengan Indeks Sekunder Lokal
Untuk mendapatkan informasi tentang indeks sekunder lokal pada tabel, gunakan metode `describeTable`. Untuk setiap indeks, Anda dapat mengakses namanya, skema kunci, dan atribut yang diproyeksikan.
Berikut ini adalah langkah-langkah untuk mengakses informasi indeks sekunder lokal suatu tabel menggunakan API Dokumen AWS SDK untuk Java .
1. Buat instans dari kelas `DynamoDB`.
1. Buat instans dari kelas `Table`. Anda harus memberikan nama tabel.
1. Panggil metode `describeTable` pada objek `Table`.
Contoh kode Java berikut mendemonstrasikan langkah sebelumnya.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
Table table = dynamoDB.getTable(tableName);
TableDescription tableDescription = table.describe();
List localSecondaryIndexes
= tableDescription.getLocalSecondaryIndexes();
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
Iterator lsiIter = localSecondaryIndexes.iterator();
while (lsiIter.hasNext()) {
LocalSecondaryIndexDescription lsiDescription = lsiIter.next();
System.out.println("Info for index " + lsiDescription.getIndexName() + ":");
Iterator kseIter = lsiDescription.getKeySchema().iterator();
while (kseIter.hasNext()) {
KeySchemaElement kse = kseIter.next();
System.out.printf("\t%s: %s\n", kse.getAttributeName(), kse.getKeyType());
}
Projection projection = lsiDescription.getProjection();
System.out.println("\tThe projection type is: " + projection.getProjectionType());
if (projection.getProjectionType().toString().equals("INCLUDE")) {
System.out.println("\t\tThe non-key projected attributes are: " + projection.getNonKeyAttributes());
}
}
```
## Mengkueri Indeks Sekunder Lokal
Anda dapat menggunakan operasi `Query` pada indeks sekunder lokal dengan cara yang hampir sama seperti Anda `Query` tabel. Anda harus menentukan nama indeks, kriteria kueri untuk kunci urutan indeks, dan atribut yang ingin Anda kembalikan. Dalam contoh ini, indeks adalah `AlbumTitleIndex` dan kunci urutan indeks adalah `AlbumTitle`.
Satu-satunya atribut yang dikembalikan adalah atribut yang telah diproyeksikan ke dalam indeks. Anda dapat memodifikasi kueri ini untuk memilih atribut non-kunci juga, tetapi ini akan memerlukan aktivitas pengambilan tabel yang relatif mahal. Untuk informasi selengkapnya tentang pengambilan tabel, lihat [Proyeksi atribut](LSI.md#LSI.Projections).
Berikut ini adalah langkah-langkah untuk query indeks sekunder lokal menggunakan AWS SDK untuk Java Document API.
1. Buat instans dari kelas `DynamoDB`.
1. Buat instans dari kelas `Table`. Anda harus memberikan nama tabel.
1. Buat instans dari kelas `Index`. Anda harus memberikan nama indeks.
1. Panggil metode `query` dari kelas `Index`.
Contoh kode Java berikut mendemonstrasikan langkah sebelumnya.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
Table table = dynamoDB.getTable(tableName);
Index index = table.getIndex("AlbumTitleIndex");
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("Artist = :v_artist and AlbumTitle = :v_title")
.withValueMap(new ValueMap()
.withString(":v_artist", "Acme Band")
.withString(":v_title", "Songs About Life"));
ItemCollection items = index.query(spec);
Iterator
- itemsIter = items.iterator();
while (itemsIter.hasNext()) {
Item item = itemsIter.next();
System.out.println(item.toJSONPretty());
}
```
### Bacaan yang konsisten pada Indeks Sekunder Lokal
Tidak seperti indeks sekunder global, yang hanya mendukung pembacaan yang konsisten pada akhirnya, indeks sekunder lokal mendukung pembacaan yang konsisten dan sangat konsisten. Bacaan sangat konsisten dari indeks sekunder lokal selalu mengembalikan nilai terbaru yang diperbarui. Jika kueri perlu mengambil atribut tambahan dari tabel dasar, atribut yang diambil tersebut juga konsisten sehubungan dengan indeks.
Secara default, `Query` menggunakan pembacaan yang konsisten pada akhirnya. Untuk meminta pembacaan yang sangat konsisten, atur `ConsistentRead` ke `true` dalam`QuerySpec`. Contoh kueri berikut `AlbumTitleIndex` menggunakan pembacaan yang sangat konsisten:
**Example**
```
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("Artist = :v_artist and AlbumTitle = :v_title")
.withValueMap(new ValueMap()
.withString(":v_artist", "Acme Band")
.withString(":v_title", "Songs About Life"))
.withConsistentRead(true);
```
**catatan**
Pembacaan yang sangat konsisten mengkonsumsi satu unit kapasitas baca per 4 KB data yang dikembalikan (dibulatkan ke atas), sedangkan pembacaan yang konsisten pada akhirnya mengkonsumsi setengahnya. Misalnya, pembacaan yang sangat konsisten yang mengembalikan 9 KB data mengkonsumsi 3 unit kapasitas baca (9 KB/ 4 KB = 2,25, dibulatkan ke 3), sedangkan kueri yang sama menggunakan pembacaan yang konsisten pada akhirnya mengkonsumsi 1,5 unit kapasitas baca. Jika aplikasi Anda dapat mentolerir membaca data yang mungkin sedikit basi, gunakan pembacaan yang konsisten pada akhirnya untuk mengurangi penggunaan kapasitas baca Anda. Untuk informasi selengkapnya, lihat [Unit kapasitas baca](LSI.md#LSI.ThroughputConsiderations.Reads).
# Contoh: Indeks Sekunder Lokal menggunakan API dokumen Java
Contoh kode Java berikut menunjukkan cara menggunakan indeks sekunder lokal di Amazon DynamoDB. Contoh membuat tabel bernama `CustomerOrders` dengan kunci partisi `CustomerId` dan kunci urutan `OrderId`. Ada dua indeks sekunder lokal di tabel ini:
+ `OrderCreationDateIndex` — Kunci urutannya adalah `OrderCreationDate`, dan atribut berikut diproyeksikan ke dalam indeks:
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex` — Kunci urutannya adalah `IsOpen`, dan semua atribut tabel diproyeksikan ke dalam indeks.
Setelah tabel `CustomerOrders` dibuat, program memuat tabel dengan data yang mewakili pesanan pelanggan. Kemudian mengkueri data menggunakan indeks sekunder lokal. Terakhir, program menghapus tabel `CustomerOrders`.
Untuk step-by-step instruksi untuk menguji sampel berikut, lihat[Contoh kode Java](CodeSamples.Java.md).
**Example**
```
package com.example.dynamodb;
import software.amazon.awssdk.core.waiters.WaiterResponse;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.*;
import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter;
import java.util.HashMap;
import java.util.Map;
public class DocumentAPILocalSecondaryIndexExample {
static DynamoDbClient client = DynamoDbClient.create();
public static String tableName = "CustomerOrders";
public static void main(String[] args) {
createTable();
loadData();
query(null);
query("IsOpenIndex");
query("OrderCreationDateIndex");
deleteTable(tableName);
}
public static void createTable() {
CreateTableRequest request = CreateTableRequest.builder()
.tableName(tableName)
.provisionedThroughput(ProvisionedThroughput.builder()
.readCapacityUnits(1L)
.writeCapacityUnits(1L)
.build())
.attributeDefinitions(
AttributeDefinition.builder().attributeName("CustomerId").attributeType(ScalarAttributeType.S).build(),
AttributeDefinition.builder().attributeName("OrderId").attributeType(ScalarAttributeType.N).build(),
AttributeDefinition.builder().attributeName("OrderCreationDate").attributeType(ScalarAttributeType.N).build(),
AttributeDefinition.builder().attributeName("IsOpen").attributeType(ScalarAttributeType.N).build())
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("OrderId").keyType(KeyType.RANGE).build())
.localSecondaryIndexes(
LocalSecondaryIndex.builder()
.indexName("OrderCreationDateIndex")
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("OrderCreationDate").keyType(KeyType.RANGE).build())
.projection(Projection.builder()
.projectionType(ProjectionType.INCLUDE)
.nonKeyAttributes("ProductCategory", "ProductName")
.build())
.build(),
LocalSecondaryIndex.builder()
.indexName("IsOpenIndex")
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("IsOpen").keyType(KeyType.RANGE).build())
.projection(Projection.builder()
.projectionType(ProjectionType.ALL)
.build())
.build())
.build();
System.out.println("Creating table " + tableName + "...");
client.createTable(request);
try (DynamoDbWaiter waiter = client.waiter()) {
WaiterResponse response = waiter.waitUntilTableExists(r -> r.tableName(tableName));
response.matched().response().ifPresent(System.out::println);
}
}
public static void query(String indexName) {
System.out.println("\n***********************************************************\n");
System.out.println("Querying table " + tableName + "...");
if ("IsOpenIndex".equals(indexName)) {
System.out.println("\nUsing index: '" + indexName + "': Bob's orders that are open.");
System.out.println("Only a user-specified list of attributes are returned\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
values.put(":v_isopen", AttributeValue.builder().n("1").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName(indexName)
.keyConditionExpression("CustomerId = :v_custid and IsOpen = :v_isopen")
.expressionAttributeValues(values)
.projectionExpression("OrderCreationDate, ProductCategory, ProductName, OrderStatus")
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
} else if ("OrderCreationDateIndex".equals(indexName)) {
System.out.println("\nUsing index: '" + indexName + "': Bob's orders that were placed after 01/31/2015.");
System.out.println("Only the projected attributes are returned\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
values.put(":v_orddate", AttributeValue.builder().n("20150131").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName(indexName)
.keyConditionExpression("CustomerId = :v_custid and OrderCreationDate >= :v_orddate")
.expressionAttributeValues(values)
.select(Select.ALL_PROJECTED_ATTRIBUTES)
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
} else {
System.out.println("\nNo index: All of Bob's orders, by OrderId:\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.keyConditionExpression("CustomerId = :v_custid")
.expressionAttributeValues(values)
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
}
}
public static void deleteTable(String tableName) {
System.out.println("Deleting table " + tableName + "...");
client.deleteTable(DeleteTableRequest.builder().tableName(tableName).build());
try (DynamoDbWaiter waiter = client.waiter()) {
waiter.waitUntilTableNotExists(r -> r.tableName(tableName));
}
}
public static void loadData() {
System.out.println("Loading data into table " + tableName + "...");
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("1").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150101").build(),
"ProductCategory", AttributeValue.builder().s("Book").build(),
"ProductName", AttributeValue.builder().s("The Great Outdoors").build(),
"OrderStatus", AttributeValue.builder().s("PACKING ITEMS").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("2").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150221").build(),
"ProductCategory", AttributeValue.builder().s("Bike").build(),
"ProductName", AttributeValue.builder().s("Super Mountain").build(),
"OrderStatus", AttributeValue.builder().s("ORDER RECEIVED").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("3").build(),
"OrderCreationDate", AttributeValue.builder().n("20150304").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("A Quiet Interlude").build(),
"OrderStatus", AttributeValue.builder().s("IN TRANSIT").build(),
"ShipmentTrackingId", AttributeValue.builder().s("176493").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150111").build(),
"ProductCategory", AttributeValue.builder().s("Movie").build(),
"ProductName", AttributeValue.builder().s("Calm Before The Storm").build(),
"OrderStatus", AttributeValue.builder().s("SHIPPING DELAY").build(),
"ShipmentTrackingId", AttributeValue.builder().s("859323").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("2").build(),
"OrderCreationDate", AttributeValue.builder().n("20150124").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("E-Z Listening").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("756943").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("3").build(),
"OrderCreationDate", AttributeValue.builder().n("20150221").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("Symphony 9").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("645193").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("4").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150222").build(),
"ProductCategory", AttributeValue.builder().s("Hardware").build(),
"ProductName", AttributeValue.builder().s("Extra Heavy Hammer").build(),
"OrderStatus", AttributeValue.builder().s("PACKING ITEMS").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("5").build(),
"OrderCreationDate", AttributeValue.builder().n("20150309").build(),
"ProductCategory", AttributeValue.builder().s("Book").build(),
"ProductName", AttributeValue.builder().s("How To Cook").build(),
"OrderStatus", AttributeValue.builder().s("IN TRANSIT").build(),
"ShipmentTrackingId", AttributeValue.builder().s("440185").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("6").build(),
"OrderCreationDate", AttributeValue.builder().n("20150318").build(),
"ProductCategory", AttributeValue.builder().s("Luggage").build(),
"ProductName", AttributeValue.builder().s("Really Big Suitcase").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("893927").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("7").build(),
"OrderCreationDate", AttributeValue.builder().n("20150324").build(),
"ProductCategory", AttributeValue.builder().s("Golf").build(),
"ProductName", AttributeValue.builder().s("PGA Pro II").build(),
"OrderStatus", AttributeValue.builder().s("OUT FOR DELIVERY").build(),
"ShipmentTrackingId", AttributeValue.builder().s("383283").build()));
}
private static void putItem(Map item) {
client.putItem(PutItemRequest.builder().tableName(tableName).item(item).build());
}
}
```
# Menggunakan Indeks Sekunder Lokal: .NET
**Topics**
+ [Membuat tabel dengan Indeks Sekunder Lokal](#LSILowLevelDotNet.CreateTableWithIndex)
+ [Mendeskripsikan tabel dengan Indeks Sekunder Lokal](#LSILowLevelDotNet.DescribeTableWithIndex)
+ [Mengkueri Indeks Sekunder Lokal](#LSILowLevelDotNet.QueryAnIndex)
+ [Contoh: Indeks Sekunder Lokal menggunakan API tingkat AWS SDK untuk .NET rendah](LSILowLevelDotNet.Example.md)
Anda dapat menggunakan API AWS SDK untuk .NET tingkat rendah untuk membuat tabel Amazon DynamoDB dengan satu atau beberapa indeks sekunder lokal, menjelaskan indeks pada tabel, dan melakukan kueri menggunakan indeks. Operasi ini dipetakan ke tindakan DynamoDB API tingkat rendah yang sesuai. Untuk informasi selengkapnya, lihat [Contoh kode .NET](CodeSamples.DotNet.md).
Berikut ini adalah langkah-langkah umum untuk operasi tabel menggunakan API tingkat rendah .NET.
1. Buat instans dari kelas `AmazonDynamoDBClient`.
1. Berikan parameter wajib dan opsional untuk operasi dengan membuat objek permintaan yang sesuai.
Misalnya, buat objek `CreateTableRequest` untuk membuat tabel dan objek `QueryRequest` untuk mengkueri tabel atau indeks.
1. Jalankan metode sesuai yang ditentukan oleh klien yang Anda buat pada langkah sebelumnya.
## Membuat tabel dengan Indeks Sekunder Lokal
Indeks sekunder lokal harus dibuat pada saat Anda membuat tabel. Untuk melakukannya, gunakan `CreateTable` dan berikan spesifikasi Anda untuk satu atau beberapa indeks sekunder lokal. Contoh kode C\$1 berikut membuat tabel untuk menyimpan informasi tentang lagu dalam koleksi musik. Kunci partisinya adalah `Artist` dan kunci urutannya adalah `SongTitle`. Indeks sekunder, `AlbumTitleIndex`, memfasilitasi kueri berdasarkan judul album.
Berikut ini adalah langkah-langkah untuk membuat tabel dengan indeks sekunder lokal, menggunakan API tingkat rendah .NET.
1. Buat instans dari kelas `AmazonDynamoDBClient`.
1. Buat instans dari kelas `CreateTableRequest` untuk memberikan informasi permintaan.
Anda harus memberikan nama tabel, kunci primernya, dan nilai throughput yang ditentukan. Untuk indeks sekunder lokal, Anda harus memberikan nama indeks, nama dan jenis data kunci urutan indeks, skema kunci untuk indeks, dan proyeksi atribut.
1. Jalankan metode `CreateTable` dengan menentukan objek permintaan sebagai parameter.
Contoh kode \$1C berikut mendemonstrasikan langkah sebelumnya. Kode ini membuat tabel (`Music`) dengan indeks sekunder pada atribut `AlbumTitle`. Kunci urutan dan kunci partisi tabel, ditambah kunci urutan indeks, adalah satu-satunya atribut yang diproyeksikan ke dalam indeks.
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "Music";
CreateTableRequest createTableRequest = new CreateTableRequest()
{
TableName = tableName
};
//ProvisionedThroughput
createTableRequest.ProvisionedThroughput = new ProvisionedThroughput()
{
ReadCapacityUnits = (long)5,
WriteCapacityUnits = (long)5
};
//AttributeDefinitions
List attributeDefinitions = new List();
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "Artist",
AttributeType = "S"
});
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "SongTitle",
AttributeType = "S"
});
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "AlbumTitle",
AttributeType = "S"
});
createTableRequest.AttributeDefinitions = attributeDefinitions;
//KeySchema
List tableKeySchema = new List();
tableKeySchema.Add(new KeySchemaElement() { AttributeName = "Artist", KeyType = "HASH" }); //Partition key
tableKeySchema.Add(new KeySchemaElement() { AttributeName = "SongTitle", KeyType = "RANGE" }); //Sort key
createTableRequest.KeySchema = tableKeySchema;
List indexKeySchema = new List();
indexKeySchema.Add(new KeySchemaElement() { AttributeName = "Artist", KeyType = "HASH" }); //Partition key
indexKeySchema.Add(new KeySchemaElement() { AttributeName = "AlbumTitle", KeyType = "RANGE" }); //Sort key
Projection projection = new Projection() { ProjectionType = "INCLUDE" };
List nonKeyAttributes = new List();
nonKeyAttributes.Add("Genre");
nonKeyAttributes.Add("Year");
projection.NonKeyAttributes = nonKeyAttributes;
LocalSecondaryIndex localSecondaryIndex = new LocalSecondaryIndex()
{
IndexName = "AlbumTitleIndex",
KeySchema = indexKeySchema,
Projection = projection
};
List localSecondaryIndexes = new List();
localSecondaryIndexes.Add(localSecondaryIndex);
createTableRequest.LocalSecondaryIndexes = localSecondaryIndexes;
CreateTableResponse result = client.CreateTable(createTableRequest);
Console.WriteLine(result.CreateTableResult.TableDescription.TableName);
Console.WriteLine(result.CreateTableResult.TableDescription.TableStatus);
```
Anda harus menunggu hingga DynamoDB membuat tabel dan menetapkan status tabel menjadi `ACTIVE`. Setelah itu, Anda bisa mulai memasukkan item data ke dalam tabel.
## Mendeskripsikan tabel dengan Indeks Sekunder Lokal
Untuk mendapatkan informasi tentang indeks sekunder lokal pada tabel, gunakan API `DescribeTable`. Untuk setiap indeks, Anda dapat mengakses namanya, skema kunci, dan atribut yang diproyeksikan.
Berikut ini adalah langkah-langkah untuk mengakses informasi indeks sekunder lokal suatu tabel menggunakan API tingkat rendah .NET.
1. Buat instans dari kelas `AmazonDynamoDBClient`.
1. Buat instans dari kelas `DescribeTableRequest` untuk memberikan informasi permintaan. Anda harus memberikan nama tabel.
1. Jalankan metode `describeTable` dengan menentukan objek permintaan sebagai parameter.
Contoh kode \$1C berikut mendemonstrasikan langkah sebelumnya.
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "Music";
DescribeTableResponse response = client.DescribeTable(new DescribeTableRequest() { TableName = tableName });
List localSecondaryIndexes =
response.DescribeTableResult.Table.LocalSecondaryIndexes;
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
foreach (LocalSecondaryIndexDescription lsiDescription in localSecondaryIndexes)
{
Console.WriteLine("Info for index " + lsiDescription.IndexName + ":");
foreach (KeySchemaElement kse in lsiDescription.KeySchema)
{
Console.WriteLine("\t" + kse.AttributeName + ": key type is " + kse.KeyType);
}
Projection projection = lsiDescription.Projection;
Console.WriteLine("\tThe projection type is: " + projection.ProjectionType);
if (projection.ProjectionType.ToString().Equals("INCLUDE"))
{
Console.WriteLine("\t\tThe non-key projected attributes are:");
foreach (String s in projection.NonKeyAttributes)
{
Console.WriteLine("\t\t" + s);
}
}
}
```
## Mengkueri Indeks Sekunder Lokal
Anda dapat menggunakan `Query` pada indeks sekunder lokal, sama seperti Anda `Query` tabel. Anda harus menentukan nama indeks, kriteria kueri untuk kunci urutan indeks, dan atribut yang ingin Anda kembalikan. Dalam contoh ini, indeks adalah `AlbumTitleIndex`, dan kunci urutan indeks adalah `AlbumTitle`.
Satu-satunya atribut yang dikembalikan adalah atribut yang telah diproyeksikan ke dalam indeks. Anda dapat memodifikasi kueri ini untuk memilih atribut non-kunci juga, tetapi ini akan memerlukan aktivitas pengambilan tabel yang relatif mahal. Untuk informasi selengkapnya tentang pengambilan tabel, lihat [Proyeksi atribut](LSI.md#LSI.Projections)
Berikut ini adalah langkah-langkah untuk mengkueri indeks sekunder lokal menggunakan API tingkat rendah .NET.
1. Buat instans dari kelas `AmazonDynamoDBClient`.
1. Buat instans dari kelas `QueryRequest` untuk memberikan informasi permintaan.
1. Jalankan metode `query` dengan menentukan objek permintaan sebagai parameter.
Contoh kode \$1C berikut mendemonstrasikan langkah sebelumnya.
**Example**
```
QueryRequest queryRequest = new QueryRequest
{
TableName = "Music",
IndexName = "AlbumTitleIndex",
Select = "ALL_ATTRIBUTES",
ScanIndexForward = true,
KeyConditionExpression = "Artist = :v_artist and AlbumTitle = :v_title",
ExpressionAttributeValues = new Dictionary()
{
{":v_artist",new AttributeValue {S = "Acme Band"}},
{":v_title",new AttributeValue {S = "Songs About Life"}}
},
};
QueryResponse response = client.Query(queryRequest);
foreach (var attribs in response.Items)
{
foreach (var attrib in attribs)
{
Console.WriteLine(attrib.Key + " ---> " + attrib.Value.S);
}
Console.WriteLine();
}
```
# Contoh: Indeks Sekunder Lokal menggunakan API tingkat AWS SDK untuk .NET rendah
Contoh kode C\$1 berikut menunjukkan cara menggunakan indeks sekunder lokal di Amazon DynamoDB. Contoh membuat tabel bernama `CustomerOrders` dengan kunci partisi `CustomerId` dan kunci urutan `OrderId`. Ada dua indeks sekunder lokal di tabel ini:
+ `OrderCreationDateIndex` — Kunci urutannya adalah `OrderCreationDate`, dan atribut berikut diproyeksikan ke dalam indeks:
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex` — Kunci urutannya adalah `IsOpen`, dan semua atribut tabel diproyeksikan ke dalam indeks.
Setelah tabel `CustomerOrders` dibuat, program memuat tabel dengan data yang mewakili pesanan pelanggan. Kemudian mengkueri data menggunakan indeks sekunder lokal. Terakhir, program menghapus tabel `CustomerOrders`.
Untuk step-by-step instruksi untuk menguji contoh berikut, lihat[Contoh kode .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using System.Linq;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelLocalSecondaryIndexExample
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
private static string tableName = "CustomerOrders";
static void Main(string[] args)
{
try
{
CreateTable();
LoadData();
Query(null);
Query("IsOpenIndex");
Query("OrderCreationDateIndex");
DeleteTable(tableName);
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
catch (AmazonDynamoDBException e) { Console.WriteLine(e.Message); }
catch (AmazonServiceException e) { Console.WriteLine(e.Message); }
catch (Exception e) { Console.WriteLine(e.Message); }
}
private static void CreateTable()
{
var createTableRequest =
new CreateTableRequest()
{
TableName = tableName,
ProvisionedThroughput =
new ProvisionedThroughput()
{
ReadCapacityUnits = (long)1,
WriteCapacityUnits = (long)1
}
};
var attributeDefinitions = new List()
{
// Attribute definitions for table primary key
{ new AttributeDefinition() {
AttributeName = "CustomerId", AttributeType = "S"
} },
{ new AttributeDefinition() {
AttributeName = "OrderId", AttributeType = "N"
} },
// Attribute definitions for index primary key
{ new AttributeDefinition() {
AttributeName = "OrderCreationDate", AttributeType = "N"
} },
{ new AttributeDefinition() {
AttributeName = "IsOpen", AttributeType = "N"
}}
};
createTableRequest.AttributeDefinitions = attributeDefinitions;
// Key schema for table
var tableKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
} }, //Partition key
{ new KeySchemaElement() {
AttributeName = "OrderId", KeyType = "RANGE"
} } //Sort key
};
createTableRequest.KeySchema = tableKeySchema;
var localSecondaryIndexes = new List();
// OrderCreationDateIndex
LocalSecondaryIndex orderCreationDateIndex = new LocalSecondaryIndex()
{
IndexName = "OrderCreationDateIndex"
};
// Key schema for OrderCreationDateIndex
var indexKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
} }, //Partition key
{ new KeySchemaElement() {
AttributeName = "OrderCreationDate", KeyType = "RANGE"
} } //Sort key
};
orderCreationDateIndex.KeySchema = indexKeySchema;
// Projection (with list of projected attributes) for
// OrderCreationDateIndex
var projection = new Projection()
{
ProjectionType = "INCLUDE"
};
var nonKeyAttributes = new List()
{
"ProductCategory",
"ProductName"
};
projection.NonKeyAttributes = nonKeyAttributes;
orderCreationDateIndex.Projection = projection;
localSecondaryIndexes.Add(orderCreationDateIndex);
// IsOpenIndex
LocalSecondaryIndex isOpenIndex
= new LocalSecondaryIndex()
{
IndexName = "IsOpenIndex"
};
// Key schema for IsOpenIndex
indexKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
}}, //Partition key
{ new KeySchemaElement() {
AttributeName = "IsOpen", KeyType = "RANGE"
}} //Sort key
};
// Projection (all attributes) for IsOpenIndex
projection = new Projection()
{
ProjectionType = "ALL"
};
isOpenIndex.KeySchema = indexKeySchema;
isOpenIndex.Projection = projection;
localSecondaryIndexes.Add(isOpenIndex);
// Add index definitions to CreateTable request
createTableRequest.LocalSecondaryIndexes = localSecondaryIndexes;
Console.WriteLine("Creating table " + tableName + "...");
client.CreateTable(createTableRequest);
WaitUntilTableReady(tableName);
}
public static void Query(string indexName)
{
Console.WriteLine("\n***********************************************************\n");
Console.WriteLine("Querying table " + tableName + "...");
QueryRequest queryRequest = new QueryRequest()
{
TableName = tableName,
ConsistentRead = true,
ScanIndexForward = true,
ReturnConsumedCapacity = "TOTAL"
};
String keyConditionExpression = "CustomerId = :v_customerId";
Dictionary expressionAttributeValues = new Dictionary {
{":v_customerId", new AttributeValue {
S = "bob@example.com"
}}
};
if (indexName == "IsOpenIndex")
{
Console.WriteLine("\nUsing index: '" + indexName
+ "': Bob's orders that are open.");
Console.WriteLine("Only a user-specified list of attributes are returned\n");
queryRequest.IndexName = indexName;
keyConditionExpression += " and IsOpen = :v_isOpen";
expressionAttributeValues.Add(":v_isOpen", new AttributeValue
{
N = "1"
});
// ProjectionExpression
queryRequest.ProjectionExpression = "OrderCreationDate, ProductCategory, ProductName, OrderStatus";
}
else if (indexName == "OrderCreationDateIndex")
{
Console.WriteLine("\nUsing index: '" + indexName
+ "': Bob's orders that were placed after 01/31/2013.");
Console.WriteLine("Only the projected attributes are returned\n");
queryRequest.IndexName = indexName;
keyConditionExpression += " and OrderCreationDate > :v_Date";
expressionAttributeValues.Add(":v_Date", new AttributeValue
{
N = "20130131"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else
{
Console.WriteLine("\nNo index: All of Bob's orders, by OrderId:\n");
}
queryRequest.KeyConditionExpression = keyConditionExpression;
queryRequest.ExpressionAttributeValues = expressionAttributeValues;
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
if (attr == "OrderId" || attr == "IsOpen"
|| attr == "OrderCreationDate")
{
Console.WriteLine(attr + "---> " + currentItem[attr].N);
}
else
{
Console.WriteLine(attr + "---> " + currentItem[attr].S);
}
}
Console.WriteLine();
}
Console.WriteLine("\nConsumed capacity: " + result.ConsumedCapacity.CapacityUnits + "\n");
}
private static void DeleteTable(string tableName)
{
Console.WriteLine("Deleting table " + tableName + "...");
client.DeleteTable(new DeleteTableRequest()
{
TableName = tableName
});
WaitForTableToBeDeleted(tableName);
}
public static void LoadData()
{
Console.WriteLine("Loading data into table " + tableName + "...");
Dictionary item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "1"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130101"
};
item["ProductCategory"] = new AttributeValue
{
S = "Book"
};
item["ProductName"] = new AttributeValue
{
S = "The Great Outdoors"
};
item["OrderStatus"] = new AttributeValue
{
S = "PACKING ITEMS"
};
/* no ShipmentTrackingId attribute */
PutItemRequest putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "2"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130221"
};
item["ProductCategory"] = new AttributeValue
{
S = "Bike"
};
item["ProductName"] = new AttributeValue
{
S = "Super Mountain"
};
item["OrderStatus"] = new AttributeValue
{
S = "ORDER RECEIVED"
};
/* no ShipmentTrackingId attribute */
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "3"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130304"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "A Quiet Interlude"
};
item["OrderStatus"] = new AttributeValue
{
S = "IN TRANSIT"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "176493"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "1"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130111"
};
item["ProductCategory"] = new AttributeValue
{
S = "Movie"
};
item["ProductName"] = new AttributeValue
{
S = "Calm Before The Storm"
};
item["OrderStatus"] = new AttributeValue
{
S = "SHIPPING DELAY"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "859323"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "2"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130124"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "E-Z Listening"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "756943"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "3"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130221"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "Symphony 9"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "645193"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "4"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130222"
};
item["ProductCategory"] = new AttributeValue
{
S = "Hardware"
};
item["ProductName"] = new AttributeValue
{
S = "Extra Heavy Hammer"
};
item["OrderStatus"] = new AttributeValue
{
S = "PACKING ITEMS"
};
/* no ShipmentTrackingId attribute */
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "5"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130309"
};
item["ProductCategory"] = new AttributeValue
{
S = "Book"
};
item["ProductName"] = new AttributeValue
{
S = "How To Cook"
};
item["OrderStatus"] = new AttributeValue
{
S = "IN TRANSIT"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "440185"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "6"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130318"
};
item["ProductCategory"] = new AttributeValue
{
S = "Luggage"
};
item["ProductName"] = new AttributeValue
{
S = "Really Big Suitcase"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "893927"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "7"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130324"
};
item["ProductCategory"] = new AttributeValue
{
S = "Golf"
};
item["ProductName"] = new AttributeValue
{
S = "PGA Pro II"
};
item["OrderStatus"] = new AttributeValue
{
S = "OUT FOR DELIVERY"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "383283"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
}
private static void WaitUntilTableReady(string tableName)
{
string status = null;
// Let us wait until table is created. Call DescribeTable.
do
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
status = res.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found. So we handle the potential exception.
}
} while (status != "ACTIVE");
}
private static void WaitForTableToBeDeleted(string tableName)
{
bool tablePresent = true;
while (tablePresent)
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
}
catch (ResourceNotFoundException)
{
tablePresent = false;
}
}
}
}
}
```
# Bekerja dengan Indeks Sekunder Lokal di DynamoDB AWS CLI
Anda dapat menggunakan AWS CLI untuk membuat tabel Amazon DynamoDB dengan satu atau beberapa Indeks Sekunder Lokal, menjelaskan indeks pada tabel, dan melakukan kueri menggunakan indeks.
**Topics**
+ [Membuat tabel dengan Indeks Sekunder Lokal](#LCICli.CreateTableWithIndex)
+ [Mendeskripsikan tabel dengan Indeks Sekunder Lokal](#LCICli.DescribeTableWithIndex)
+ [Mengkueri Indeks Sekunder Lokal](#LCICli.QueryAnIndex)
## Membuat tabel dengan Indeks Sekunder Lokal
Indeks Sekunder Lokal harus dibuat pada saat Anda membuat tabel. Untuk melakukannya, gunakan parameter `create-table` dan berikan spesifikasi Anda untuk satu atau beberapa Indeks Sekunder Lokal. Contoh berikut membuat tabel (`Music`) untuk menyimpan informasi tentang lagu dalam koleksi musik. Kunci partisinya adalah `Artist` dan kunci urutannya adalah `SongTitle`. Indeks sekunder, `AlbumTitleIndex` pada atribut `AlbumTitle` memfasilitasi kueri berdasarkan judul album.
```
aws dynamodb create-table \
--table-name Music \
--attribute-definitions AttributeName=Artist,AttributeType=S AttributeName=SongTitle,AttributeType=S \
AttributeName=AlbumTitle,AttributeType=S \
--key-schema AttributeName=Artist,KeyType=HASH AttributeName=SongTitle,KeyType=RANGE \
--provisioned-throughput \
ReadCapacityUnits=10,WriteCapacityUnits=5 \
--local-secondary-indexes \
"[{\"IndexName\": \"AlbumTitleIndex\",
\"KeySchema\":[{\"AttributeName\":\"Artist\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"AlbumTitle\",\"KeyType\":\"RANGE\"}],
\"Projection\":{\"ProjectionType\":\"INCLUDE\", \"NonKeyAttributes\":[\"Genre\", \"Year\"]}}]"
```
Anda harus menunggu hingga DynamoDB membuat tabel dan menetapkan status tabel menjadi `ACTIVE`. Setelah itu, Anda bisa mulai memasukkan item data ke dalam tabel. Anda dapat menggunakan [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) untuk menentukan status pembuatan tabel.
## Mendeskripsikan tabel dengan Indeks Sekunder Lokal
Untuk mendapatkan informasi tentang indeks sekunder lokal pada tabel, gunakan parameter `describe-table`. Untuk setiap indeks, Anda dapat mengakses namanya, skema kunci, dan atribut yang diproyeksikan.
```
aws dynamodb describe-table --table-name Music
```
## Mengkueri Indeks Sekunder Lokal
Anda dapat menggunakan operasi `query` pada Indeks Sekunder Lokal dengan cara yang hampir sama seperti Anda `query` tabel. Anda harus menentukan nama indeks, kriteria kueri untuk kunci urutan indeks, dan atribut yang ingin Anda kembalikan. Dalam contoh ini, indeks adalah `AlbumTitleIndex` dan kunci urutan indeks adalah `AlbumTitle`.
Satu-satunya atribut yang dikembalikan adalah atribut yang telah diproyeksikan ke dalam indeks. Anda dapat memodifikasi kueri ini untuk memilih atribut non-kunci juga, tetapi ini akan memerlukan aktivitas pengambilan tabel yang relatif mahal. Untuk informasi selengkapnya tentang pengambilan tabel, lihat [Proyeksi atribut](LSI.md#LSI.Projections).
```
aws dynamodb query \
--table-name Music \
--index-name AlbumTitleIndex \
--key-condition-expression "Artist = :v_artist and AlbumTitle = :v_title" \
--expression-attribute-values '{":v_artist":{"S":"Acme Band"},":v_title":{"S":"Songs About Life"} }'
```
# Mengelola alur kerja kompleks dengan DynamoDB Transactions
Transaksi Amazon DynamoDB menyederhanakan pengalaman pengembang dalam membuat terkoordinasi all-or-nothing, perubahan ke beberapa item baik di dalam maupun di seluruh tabel. Transaksi memberikan atomisitas, konsistensi, isolasi, dan daya tahan (ACID) di DynamoDB, yang memungkinkan Anda menjaga kebenaran data dalam aplikasi Anda dengan lebih mudah.
Anda dapat menggunakan DynamoDB transaksional read and APIs write untuk mengelola alur kerja bisnis kompleks yang memerlukan penambahan, pembaruan, atau penghapusan beberapa item sebagai operasi tunggal. all-or-nothing Misalnya, developer video game dapat memastikan bahwa profil pemain diperbarui dengan benar saat mereka bertukar item dalam game atau melakukan pembelian dalam game.
Dengan transaksi API tulis, Anda dapat mengelompokkan beberapa tindakan `Put`, `Update`, `Delete`, dan `ConditionCheck`. Anda kemudian dapat mengirimkan tindakan sebagai operasi `TransactWriteItems` tunggal yang baik berhasil atau gagal sebagai unit. Hal yang sama berlaku untuk beberapa tindakan `Get`, yang dapat Anda kelompokkan dan kirimkan sebagai operasi `TransactGetItems` tunggal.
Tidak ada biaya tambahan untuk mengaktifkan transaksi untuk tabel DynamoDB Anda. Anda hanya membayar untuk baca atau tulis yang merupakan bagian dari transaksi Anda. DynamoDB melakukan dua baca atau tulis mendasar dari setiap item dalam transaksi: satu untuk mempersiapkan transaksi dan satu untuk melakukan transaksi. Kedua read/write operasi yang mendasari ini terlihat di CloudWatch metrik Amazon Anda.
Untuk memulai transaksi DynamoDB, unduh SDK AWS terbaru atau (). AWS Command Line Interface AWS CLI Kemudian ikuti [Contoh DynamoDB transactions](transaction-example.md).
Bagian berikut memberikan gambaran rinci tentang transaksi APIs dan bagaimana Anda dapat menggunakannya di DynamoDB.
**Topics**
+ [Cara kerjanya](transaction-apis.md)
+ [Menggunakan IAM dengan transactions](transaction-apis-iam.md)
+ [Contoh kode](transaction-example.md)
# Amazon DynamoDB Transactions: Cara kerjanya
Dengan transaksi Amazon DynamoDB, Anda dapat mengelompokkan beberapa tindakan bersama-sama dan mengirimkannya sebagai satu atau all-or-nothing `TransactWriteItems` operasi. `TransactGetItems` Bagian berikut menjelaskan operasi API, manajemen kapasitas, praktik terbaik, dan detail lainnya tentang menggunakan operasi transaksional di DynamoDB.
**Topics**
+ [TransactWriteItems API](#transaction-apis-txwriteitems)
+ [TransactGetItems API](#transaction-apis-txgetitems)
+ [Tingkat isolasi untuk DynamoDB transactions](#transaction-isolation)
+ [Penanganan konflik transaksi di DynamoDB](#transaction-conflict-handling)
+ [Menggunakan transaksional di APIs DynamoDB Accelerator (DAX)](#transaction-apis-dax)
+ [Manajemen kapasitas untuk transaksi](#transaction-capacity-handling)
+ [Praktik terbaik untuk transactions](#transaction-best-practices)
+ [Menggunakan transaksional APIs dengan tabel global](#transaction-integration)
+ [Transaksi DynamoDB AWSLabs vs. perpustakaan klien transaksi](#transaction-vs-library)
## TransactWriteItems API
`TransactWriteItems`adalah operasi penulisan sinkron dan idempoten yang mengelompokkan hingga 100 tindakan penulisan dalam satu operasi. all-or-nothing Tindakan ini dapat menargetkan hingga 100 item berbeda dalam satu atau lebih tabel DynamoDB dalam akun AWS yang sama dan di Wilayah yang sama. Ukuran agregat item dalam transaksi tidak dapat melebihi 4 MB. Tindakan tersebut diselesaikan secara atomik, sehingga semuanya berhasil atau tidak satu pun yang berhasil.
**catatan**
Operasi `TransactWriteItems` berbeda dari operasi `BatchWriteItem` dalam hal semua tindakan yang di dalamnya harus berhasil diselesaikan, atau tidak ada perubahan yang dibuat sama sekali. Dengan operasi `BatchWriteItem`, mungkin bahwa hanya beberapa tindakan dalam batch yang berhasil sementara yang lain tidak.
Transaksi tidak dapat dilakukan dengan menggunakan indeks.
Anda tidak dapat menargetkan item yang sama dengan beberapa operasi dalam transaksi yang sama. Misalnya, Anda tidak dapat melakukan `ConditionCheck` dan juga tindakan `Update` pada item yang sama dalam transaksi yang sama.
Anda dapat menambahkan jenis tindakan berikut pada transaksi:
+ `Put` — Memulai operasi `PutItem` untuk membuat item baru atau mengganti item lama dengan item baru, kondisional atau tanpa menentukan syarat apa pun.
+ `Update` — Memulai operasi `UpdateItem` untuk mengedit atribut item yang ada atau menambahkan item baru ke tabel jika belum ada. Gunakan tindakan ini untuk menambah, menghapus, atau memperbarui atribut pada item yang ada secara dengan syarat maupun tanpa syarat.
+ `Delete` — Memulai operasi `DeleteItem` untuk menghapus satu item dalam tabel yang diidentifikasi oleh kunci primernya.
+ `ConditionCheck` — Memeriksa bahwa item ada atau periksa kondisi atribut tertentu dari item.
Ketika transaksi selesai di DynamoDB, perubahannya mulai menyebar ke indeks sekunder global GSIs (), aliran, dan cadangan. Propagasi ini terjadi secara bertahap: catatan aliran dari transaksi yang sama mungkin muncul pada waktu yang berbeda dan dapat disisipkan dengan catatan dari transaksi lain. Konsumen streaming tidak boleh menganggap atomisitas transaksi atau jaminan pemesanan.
Untuk memastikan snapshot atom dari item yang dimodifikasi dalam transaksi, gunakan TransactGetItems operasi untuk membaca semua item yang relevan bersama-sama. Operasi ini memberikan tampilan data yang konsisten, memastikan Anda melihat semua perubahan dari transaksi yang diselesaikan atau tidak sama sekali.
Karena propagasi tidak langsung, jika tabel dipulihkan dari backup ([RestoreTableFromBackup](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_RestoreTableFromBackup.html)) atau diekspor ke titik waktu ([ExportTableToPointInTime](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_ExportTableToPointInTime.html)) pertengahan propagasi, itu hanya dapat berisi beberapa perubahan yang dibuat selama transaksi baru-baru ini.
### Idempotensi
Anda dapat menyertakan token klien ketika Anda membuat panggilan `TransactWriteItems` untuk memastikan bahwa permintaan tersebut *idempoten*. Menjadikan transaksi Anda idempoten membantu mencegah kesalahan aplikasi jika operasi yang sama diajukan beberapa kali karena waktu habis koneksi atau masalah konektivitas lainnya.
Jika panggilan `TransactWriteItems` asli berhasil, panggilan `TransactWriteItems` berikutnya dengan token klien yang sama berhasil kembali tanpa membuat perubahan apa pun. Jika parameter `ReturnConsumedCapacity` diatur, panggilan `TransactWriteItems` awal mengembalikan jumlah unit kapasitas tulis yang dikonsumsi dalam membuat perubahan. Panggilan `TransactWriteItems` selanjutnya dengan token klien yang sama mengembalikan jumlah unit kapasitas baca yang dikonsumsi dalam membaca item.
**Poin penting tentang idempotensi**
+ Token klien berlaku selama 10 menit setelah permintaan yang menggunakannya selesai. Setelah 10 menit, setiap permintaan yang menggunakan token klien yang sama diperlakukan sebagai permintaan baru. Anda tidak boleh menggunakan kembali token klien yang sama untuk permintaan yang sama setelah 10 menit.
+ Jika Anda mengulangi permintaan dengan token klien yang sama dalam jendela idempotensi 10 menit tetapi mengubah beberapa parameter permintaan lainnya, DynamoDB mengembalikan pengecualian `IdempotentParameterMismatch`.
### Penanganan kesalahan untuk penulisan
Transaksi tulis tidak berhasil dalam situasi berikut:
+ Ketika syarat di salah satu ekspresisyarat tidak terpenuhi.
+ Ketika kesalahan validasi transaksi terjadi karena lebih dari satu tindakan dalam operasi `TransactWriteItems` yang sama menargetkan item yang sama.
+ Saat permintaan `TransactWriteItems` bertentangan dengan operasi `TransactWriteItems` yang sedang berlangsung pada satu atau lebih item dalam permintaan `TransactWriteItems`. Dalam kasus ini, permintaan gagal dengan `TransactionCanceledException`.
+ Ketika ada kapasitas yang ditetapkan tidak mencukupi untuk penyelesaian transaksi.
+ Ketika ukuran item menjadi terlalu besar (lebih besar dari 400 KB), atau indeks sekunder lokal (LSI) menjadi terlalu besar, atau kesalahan validasi serupa terjadi karena perubahan yang dilakukan oleh transaksi.
+ Ketika ada kesalahan pengguna, seperti format data yang tidak valid.
Untuk informasi selengkapnya tentang bagaimana pertentangan dengan operasi `TransactWriteItems` ditangani, lihat [Penanganan konflik transaksi di DynamoDB](#transaction-conflict-handling).
## TransactGetItems API
`TransactGetItems` adalah operasi baca sinkron yang mengelompokkan hingga 100 tindakan `Get` menjadi satu. Tindakan ini dapat menargetkan hingga 100 item berbeda dalam satu atau lebih tabel DynamoDB dalam akun dan Wilayah yang AWS sama. Ukuran agregat item dalam transaksi tidak dapat melebihi 4 MB.
Tindakan `Get` dilakukan secara atom sehingga semuanya berhasil atau semuanya gagal:
+ `Get` — Memulai operasi `GetItem` untuk mengambil satu set atribut untuk item dengan kunci primer yang diberikan. Jika tidak ditemukan item yang cocok, `Get` tidak mengembalikan data apa pun.
### Penanganan kesalahan untuk pembacaan
Transaksi baca tidak berhasil dalam situasi berikut:
+ Saat permintaan `TransactGetItems` bertentangan dengan operasi `TransactWriteItems` yang sedang berlangsung pada satu atau lebih item dalam permintaan `TransactGetItems`. Dalam kasus ini, permintaan gagal dengan `TransactionCanceledException`.
+ Ketika ada kapasitas yang ditetapkan tidak mencukupi untuk penyelesaian transaksi.
+ Ketika ada kesalahan pengguna, seperti format data yang tidak valid.
Untuk informasi selengkapnya tentang bagaimana pertentangan dengan operasi `TransactGetItems` ditangani, lihat [Penanganan konflik transaksi di DynamoDB](#transaction-conflict-handling).
## Tingkat isolasi untuk DynamoDB transactions
Tingkat isolasi operasi transaksional (`TransactWriteItems` atau `TransactGetItems`) dan operasi lainnya adalah sebagai berikut.
### DAPAT DISERIALKAN
Isolasi yang *dapat diserialkan* memastikan bahwa hasil dari beberapa operasi bersamaan sama seperti jika tidak ada operasi dimulai hingga operasi sebelumnya telah selesai.
Ada isolasi serialisasi antara jenis operasi berikut:
+ Antara operasi transaksional dan operasi tulis standar (`PutItem`, `UpdateItem`, atau `DeleteItem`).
+ Antara operasi transaksional dan operasi baca standar (`GetItem`).
+ Antara operasi `TransactWriteItems` dan operasi `TransactGetItems`.
Meskipun ada isolasi serialisasi antara operasi transaksional, dan setiap standar individu menulis dalam suatu `BatchWriteItem` operasi, tidak ada isolasi serial antara transaksi dan operasi sebagai satu unit. `BatchWriteItem`
Demikian pula, tingkat isolasi antara operasi transaksional dan individu `GetItems` dalam operasi `BatchGetItem` dapat diserialisasikan. Tetapi tahap isolasi antara transaksi dan operasi `BatchGetItem` sebagai unit adalah *read-committed*.
Permintaan `GetItem` tunggal dapat diserialisasikan sehubungan dengan permintaan `TransactWriteItems` dalam salah satu dari dua cara, baik sebelum atau setelah permintaan `TransactWriteItems`. Beberapa permintaan `GetItem`, terhadap kunci dalam permintaan `TransactWriteItems` bersamaan dapat dijalankan dalam urutan apa pun, dan karena itu hasilnya *read-committed*.
Misalnya, jika permintaan `GetItem` untuk item A dan item B dijalankan bersamaan dengan permintaan `TransactWriteItems` yang memodifikasi item A dan item B, ada empat kemungkinan:
+ Kedua permintaan `GetItem` dijalankan sebelum permintaan `TransactWriteItems`.
+ Kedua permintaan `GetItem` dijalankan setelah permintaan `TransactWriteItems`.
+ Permintaan `GetItem` untuk item A dijalankan sebelum permintaan `TransactWriteItems`. Untuk item B, `GetItem` dijalankan setelah `TransactWriteItems`.
+ Permintaan `GetItem` untuk item B dijalankan sebelum permintaan `TransactWriteItems`. Untuk item A, `GetItem` dijalankan setelah `TransactWriteItems`.
Anda harus menggunakan `TransactGetItems` jika Anda lebih suka tingkat isolasi serializable untuk beberapa permintaan. `GetItem`
Jika pembacaan non-transaksional dilakukan pada beberapa item yang merupakan bagian dari permintaan penulisan transaksi yang sama dalam penerbangan, Anda mungkin dapat membaca status baru dari beberapa item dan status lama item lainnya. Anda akan dapat membaca status baru dari semua item yang merupakan bagian dari permintaan tulis transaksi hanya ketika respons berhasil diterima untuk penulisan transaksional, yang menunjukkan bahwa transaksi telah selesai.
Setelah transaksi berhasil diselesaikan dan respons diterima, operasi baca yang *konsisten* selanjutnya mungkin masih mengembalikan status lama untuk waktu yang singkat karena model konsistensi DynamoDB akhirnya. Untuk menjamin membaca sebagian besar up-to-date data segera setelah transaksi, Anda harus menggunakan pembacaan yang [*sangat konsisten*](HowItWorks.ReadConsistency.md#HowItWorks.ReadConsistency.Strongly) dengan menyetel `ConsistentRead` ke true.
### READ-COMMITTED
Isolasi *read-commit* memastikan bahwa operasi baca selalu mengembalikan komitmen untuk suatu item - pembacaan tidak akan pernah menampilkan tampilan ke item yang mewakili keadaan dari penulisan transaksional yang pada akhirnya tidak berhasil. Isolasi komitmen baca tidak mencegah modifikasi item segera setelah operasi baca.
Tingkat isolasi read-committed antara operasi transaksional dan operasi baca yang melibatkan beberapa baca standar (`BatchGetItem`, `Query`, atau `Scan`). Jika transaksional tulis memperbarui item di tengah operasi `BatchGetItem`, `Query`, atau `Scan`, bagian selanjutnya dari operasi baca mengembalikan nilai berkomitmen baru (dengan `ConsistentRead)` atau mungkin nilai berkomitmen sebelumnya (bacaan akhir konsisten).
### Ringkasan operasi
Untuk meringkas, tabel berikut menunjukkan tingkat isolasi antara operasi transaksi (`TransactWriteItems` atau `TransactGetItems`) dan operasi lainnya.
| Operasi | Tingkat Isolasi |
| --- | --- |
| `DeleteItem` | *Dapat diserialkan* |
| `PutItem` | *Dapat diserialkan* |
| `UpdateItem` | *Dapat diserialkan* |
| `GetItem` | *Dapat diserialkan* |
| `BatchGetItem` | *Read-committed*\$1 |
| `BatchWriteItem` | *Tidak Dapat Diserialkan*\$1 |
| `Query` | *Read-committed* |
| `Scan` | *Read-committed* |
| Operasi transaksional lainnya | *Dapat diserialkan* |
Tingkat yang ditandai dengan tanda bintang (\$1) berlaku untuk operasi sebagai sebuah unit. Namun, tindakan individu dalam operasi tersebut memiliki tingkat isolasi yang *dapat diserialkan*.
## Penanganan konflik transaksi di DynamoDB
Konflik transaksional dapat terjadi selama permintaan tingkat item bersamaan pada item dalam transaksi. Konflik transaksi dapat terjadi dalam skenario berikut:
+ Permintaan `PutItem`, `UpdateItem`, atau `DeleteItem` untuk item yang bertentangan dengan permintaan `TransactWriteItems` yang sedang berlangsung yang mencakup item yang sama.
+ Item dalam permintaan `TransactWriteItems` adalah bagian dari permintaan `TransactWriteItems` lain yang sedang berlangsung.
+ Item dalam permintaan `TransactGetItems` adalah bagian dari permintaan `TransactWriteItems`, `BatchWriteItem`, `PutItem`, `UpdateItem`, atau `DeleteItem` yang sedang berlangsung.
**catatan**
Saat permintaan `PutItem`, `UpdateItem`, atau `DeleteItem` ditolak, permintaan gagal dengan `TransactionConflictException`.
Jika ada permintaan tingkat item dalam `TransactWriteItems` atau `TransactGetItems` ditolak, permintaan gagal dengan `TransactionCanceledException`. Jika permintaan itu gagal, AWS SDKs jangan coba lagi permintaan tersebut.
Jika Anda menggunakan AWS SDK untuk Java, pengecualian berisi daftar [CancellationReasons](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CancellationReason.html), diurutkan sesuai dengan daftar item dalam parameter `TransactItems` permintaan. Untuk bahasa lain, representasi string daftar disertakan dalam pesan kesalahan pengecualian.
Jika operasi `TransactWriteItems` atau `TransactGetItems` yang sedang berlangsung bertentangan dengan permintaan `GetItem` bersamaan, kedua operasi dapat berhasil.
[TransactionConflict CloudWatch Metrik](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/metrics-dimensions.html) ditambahkan untuk setiap permintaan tingkat item yang gagal.
## Menggunakan transaksional di APIs DynamoDB Accelerator (DAX)
`TransactWriteItems` dan `TransactGetItems` keduanya didukung di DynamoDB Accelerator (DAX) dengan tingkat isolasi yang sama seperti di DynamoDB.
`TransactWriteItems` menulis melalui DAX. DAX menyampaikan panggilan `TransactWriteItems` ke DynamoDB dan mengembalikan respons. Untuk mempopulasi cache setelah menulis, DAX memanggil `TransactGetItems` di latar belakang untuk setiap item dalam operasi `TransactWriteItems`, yang mengonsumsi unit kapasitas baca tambahan. (Untuk informasi selengkapnya, lihat [Manajemen kapasitas untuk transaksi](#transaction-capacity-handling).) Fungsionalitas ini memungkinkan Anda untuk menjaga logika aplikasi Anda sederhana dan menggunakan DAX untuk kedua operasi transaksional dan nontransaksional.
Panggilan `TransactGetItems` disampaikan melalui DAX tanpa item di-cache secara lokal. Ini adalah perilaku yang sama dengan pembacaan yang sangat konsisten APIs di DAX.
## Manajemen kapasitas untuk transaksi
Tidak ada biaya tambahan untuk mengaktifkan transaksi untuk tabel DynamoDB Anda. Anda hanya membayar untuk baca atau tulis yang merupakan bagian dari transaksi Anda. DynamoDB melakukan dua baca atau tulis mendasar dari setiap item dalam transaksi: satu untuk mempersiapkan transaksi dan satu untuk melakukan transaksi. Dua read/write operasi yang mendasarinya terlihat di CloudWatch metrik Amazon Anda.
Rencanakan untuk membaca dan menulis tambahan yang diperlukan oleh transaksional APIs ketika Anda menyediakan kapasitas ke tabel Anda. Misalnya, anggaplah aplikasi Anda menjalankan satu transaksi per detik, dan setiap transaksi menulis tiga item 500-byte dalam tabel Anda. Setiap item membutuhkan dua unit kapasitas tulis (WCUs): satu untuk mempersiapkan transaksi dan satu untuk melakukan transaksi. Oleh karena itu, Anda perlu menyediakan enam WCUs ke meja.
Jika Anda menggunakan DynamoDB Accelerator (DAX) pada contoh sebelumnya, Anda juga akan menggunakan dua unit kapasitas baca RCUs () untuk setiap item dalam panggilan. `TransactWriteItems` Jadi, Anda perlu memberikan enam tambahan RCUs ke tabel.
Demikian pula, jika aplikasi Anda menjalankan satu transaksi baca per detik, dan setiap transaksi membaca tiga item 500 byte dalam tabel Anda, Anda perlu menyediakan enam unit kapasitas baca (RCUs) ke tabel. Membaca setiap item membutuhkan dua RCUs: satu untuk mempersiapkan transaksi dan satu untuk melakukan transaksi.
Selain itu, perilaku SDK default adalah untuk mencoba lagi transaksi dalam kasus pengecualian `TransactionInProgressException`. Rencanakan unit kapasitas baca tambahan (RCUs) yang dikonsumsi oleh percobaan ulang ini. Hal yang sama juga berlaku jika Anda mencoba ulang transaksi dalam kode Anda sendiri menggunakan `ClientRequestToken`.
## Praktik terbaik untuk transactions
Pertimbangkan praktik yang disarankan berikut saat menggunakan DynamoDB Transactions.
+ Aktifkan penskalaan otomatis pada tabel Anda, atau pastikan bahwa Anda telah menyediakan kapasitas throughput yang cukup untuk melakukan dua operasi baca atau tulis untuk setiap item dalam transaksi Anda.
+ Jika Anda tidak menggunakan SDK yang AWS disediakan, sertakan `ClientRequestToken` atribut saat Anda melakukan `TransactWriteItems` panggilan untuk memastikan bahwa permintaan tersebut idempoten.
+ Jangan mengelompokkan operasi bersama-sama dalam sebuah transaksi jika tidak diperlukan. Misalnya, jika satu transaksi dengan 10 operasi dapat dipecah menjadi beberapa transaksi tanpa mengurangi kebenaran aplikasi, sebaiknya pisahkan transaksi tersebut. Transaksi yang lebih sederhana meningkatkan throughput dan lebih mungkin untuk berhasil.
+ Beberapa transaksi memperbarui item yang sama secara bersamaan dapat menyebabkan konflik yang membatalkan transaksi. Kami merekomendasikan praktik terbaik DynamoDB berikut untuk pemodelan data untuk meminimalkan konflik tersebut.
+ Jika satu set atribut sering diperbarui di beberapa item sebagai bagian dari transaksi tunggal, pertimbangkan pengelompokan atribut menjadi satu item untuk mengurangi lingkup transaksi.
+ Hindari penggunaan transaksi untuk menyerap data secara massal. Untuk tulis massal, lebih baik menggunakan `BatchWriteItem`.
## Menggunakan transaksional APIs dengan tabel global
Operasi transaksional memberikan jaminan atomisitas, konsistensi, isolasi, dan daya tahan (ACID) hanya di AWS Wilayah tempat API tulis dipanggil. Transaksi tidak didukung di seluruh Wilayah dalam tabel global. Misalnya, Anda memiliki tabel global dengan replika di Wilayah AS Timur (Ohio) dan AS Barat (Oregon) dan Anda melakukan operasi `TransactWriteItems` di Wilayah AS Timur (Virginia Utara). Anda dapat mengamati transaksi yang diselesaikan sebagian di Wilayah Barat AS (Oregon) saat perubahan direplikasi. Perubahan direplikasi ke Wilayah lain hanya setelah dilakukan di Wilayah sumber.
## Transaksi DynamoDB AWSLabs vs. perpustakaan klien transaksi
Transaksi DynamoDB menyediakan penggantian yang lebih hemat biaya, kuat, dan berkinerja untuk pustaka klien transaksi. [AWSLabs](https://github.com/awslabs) Kami menyarankan agar Anda memperbarui aplikasi Anda untuk menggunakan transaksi asli, sisi server. APIs
# Menggunakan IAM dengan DynamoDB transactions
Anda dapat menggunakan AWS Identity and Access Management (IAM) untuk membatasi tindakan yang dapat dilakukan operasi transaksional di Amazon DynamoDB. Untuk informasi selengkapnya tentang menggunakan kebijakan IAM dalam DynamoDB, lihat [Kebijakan berbasis identitas untuk DynamoDB](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies).
Izin untuk tindakan `Put`, `Update`, `Delete`, dan `Get` diatur oleh izin yang digunakan untuk operasi `PutItem`, `UpdateItem`, `DeleteItem`, dan `GetItem` yang mendasarinya. Untuk tindakan `ConditionCheck`, Anda dapat menggunakan izin `dynamodb:ConditionCheckItem` dalam kebijakan IAM.
Berikut ini adalah contoh kebijakan IAM yang dapat Anda gunakan untuk mengonfigurasi DynamoDB transactions.
## Contoh 1: Mengizinkan operasi transaksional
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
]
}
]
}
```
------
## Contoh 2: Hanya mengizinkan operasi transaksional
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
],
"Condition": {
"ForAnyValue:StringEquals": {
"dynamodb:EnclosingOperation": [
"TransactWriteItems",
"TransactGetItems"
]
}
}
}
]
}
```
------
## Contoh 3: Mengizinkan baca dan tulis nontransaksional, dan memblokir baca dan tulis transaksional
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
],
"Condition": {
"ForAnyValue:StringEquals": {
"dynamodb:EnclosingOperation": [
"TransactWriteItems",
"TransactGetItems"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:PutItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:UpdateItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
]
}
]
}
```
------
## Contoh 4: Mencegah informasi dikembalikan pada ConditionCheck kegagalan
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": "arn:aws:dynamodb:*:*:table/table01",
"Condition": {
"StringEqualsIfExists": {
"dynamodb:ReturnValues": "NONE"
}
}
}
]
}
```
------
# Contoh DynamoDB transactions
Sebagai contoh situasi di mana Amazon DynamoDB transactions dapat berguna, pertimbangkan contoh aplikasi Java untuk marketplace online ini.
Aplikasi ini memiliki tiga tabel DynamoDB di backend:
+ `Customers` — Tabel ini menyimpan detail tentang pelanggan marketplace. Kunci primernya adalah pengidentifikasi unik `CustomerId`.
+ `ProductCatalog` — Tabel ini menyimpan detail seperti harga dan ketersediaan produk yang dijual di marketplace. Kunci primernya adalah pengidentifikasi unik `ProductId`.
+ `Orders` — Tabel ini menyimpan detail pesanan dari marketplace. Kunci primernya adalah pengidentifikasi unik `OrderId`.
## Membuat pesanan
Potongan kode berikut menggambarkan cara menggunakan DynamoDB transaction untuk mengoordinasikan beberapa langkah yang diperlukan untuk membuat dan memproses pesanan. Menggunakan satu all-or-nothing operasi memastikan bahwa jika ada bagian dari transaksi yang gagal, tidak ada tindakan dalam transaksi yang dijalankan dan tidak ada perubahan yang dilakukan.
Dalam contoh ini, Anda menyiapkan pesanan dari pelanggan yang `customerId` adalah `09e8e9c8-ec48`. Anda kemudian menjalankannya sebagai satu transaksi menggunakan alur kerja pemrosesan pesanan sederhana berikut:
1. Tentukan apakah ID pelanggan valid.
1. Pastikan produk `IN_STOCK`, dan perbarui status produk menjadi `SOLD`.
1. Pastikan pesanan belum ada, lalu buat pesanan.
### Memvalidasi pelanggan
Pertama, tentukan tindakan untuk memverifikasi bahwa pelanggan dengan `customerId` sama dengan `09e8e9c8-ec48` ada di tabel pelanggan.
```
final String CUSTOMER_TABLE_NAME = "Customers";
final String CUSTOMER_PARTITION_KEY = "CustomerId";
final String customerId = "09e8e9c8-ec48";
final HashMap customerItemKey = new HashMap<>();
customerItemKey.put(CUSTOMER_PARTITION_KEY, new AttributeValue(customerId));
ConditionCheck checkCustomerValid = new ConditionCheck()
.withTableName(CUSTOMER_TABLE_NAME)
.withKey(customerItemKey)
.withConditionExpression("attribute_exists(" + CUSTOMER_PARTITION_KEY + ")");
```
### Memperbarui status produk
Selanjutnya, tentukan tindakan untuk memperbarui status produk menjadi `SOLD` jika kondisi status produk saat ini diatur ke `IN_STOCK` `true`. Mengatur parameter `ReturnValuesOnConditionCheckFailure` akan mengembalikan item jika atribut status produk item tidak sama dengan `IN_STOCK`.
```
final String PRODUCT_TABLE_NAME = "ProductCatalog";
final String PRODUCT_PARTITION_KEY = "ProductId";
HashMap productItemKey = new HashMap<>();
productItemKey.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
Map expressionAttributeValues = new HashMap<>();
expressionAttributeValues.put(":new_status", new AttributeValue("SOLD"));
expressionAttributeValues.put(":expected_status", new AttributeValue("IN_STOCK"));
Update markItemSold = new Update()
.withTableName(PRODUCT_TABLE_NAME)
.withKey(productItemKey)
.withUpdateExpression("SET ProductStatus = :new_status")
.withExpressionAttributeValues(expressionAttributeValues)
.withConditionExpression("ProductStatus = :expected_status")
.withReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD);
```
### Membuat pesanan
Terakhir, buat pesanan selama pesanan dengan `OrderId` tersebut belum ada.
```
final String ORDER_PARTITION_KEY = "OrderId";
final String ORDER_TABLE_NAME = "Orders";
HashMap orderItem = new HashMap<>();
orderItem.put(ORDER_PARTITION_KEY, new AttributeValue(orderId));
orderItem.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
orderItem.put(CUSTOMER_PARTITION_KEY, new AttributeValue(customerId));
orderItem.put("OrderStatus", new AttributeValue("CONFIRMED"));
orderItem.put("OrderTotal", new AttributeValue("100"));
Put createOrder = new Put()
.withTableName(ORDER_TABLE_NAME)
.withItem(orderItem)
.withReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD)
.withConditionExpression("attribute_not_exists(" + ORDER_PARTITION_KEY + ")");
```
### Menjalankan transaksi
Contoh berikut menggambarkan bagaimana menjalankan tindakan yang didefinisikan sebelumnya sebagai all-or-nothing operasi tunggal.
```
Collection actions = Arrays.asList(
new TransactWriteItem().withConditionCheck(checkCustomerValid),
new TransactWriteItem().withUpdate(markItemSold),
new TransactWriteItem().withPut(createOrder));
TransactWriteItemsRequest placeOrderTransaction = new TransactWriteItemsRequest()
.withTransactItems(actions)
.withReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL);
// Run the transaction and process the result.
try {
client.transactWriteItems(placeOrderTransaction);
System.out.println("Transaction Successful");
} catch (ResourceNotFoundException rnf) {
System.err.println("One of the table involved in the transaction is not found" + rnf.getMessage());
} catch (InternalServerErrorException ise) {
System.err.println("Internal Server Error" + ise.getMessage());
} catch (TransactionCanceledException tce) {
System.out.println("Transaction Canceled " + tce.getMessage());
}
```
## Membaca detail pesanan
Contoh berikut menunjukkan cara membaca pesanan yang telah selesai secara transaksional di seluruh tabel `Orders` dan `ProductCatalog`.
```
HashMap productItemKey = new HashMap<>();
productItemKey.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
HashMap orderKey = new HashMap<>();
orderKey.put(ORDER_PARTITION_KEY, new AttributeValue(orderId));
Get readProductSold = new Get()
.withTableName(PRODUCT_TABLE_NAME)
.withKey(productItemKey);
Get readCreatedOrder = new Get()
.withTableName(ORDER_TABLE_NAME)
.withKey(orderKey);
Collection getActions = Arrays.asList(
new TransactGetItem().withGet(readProductSold),
new TransactGetItem().withGet(readCreatedOrder));
TransactGetItemsRequest readCompletedOrder = new TransactGetItemsRequest()
.withTransactItems(getActions)
.withReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL);
// Run the transaction and process the result.
try {
TransactGetItemsResult result = client.transactGetItems(readCompletedOrder);
System.out.println(result.getResponses());
} catch (ResourceNotFoundException rnf) {
System.err.println("One of the table involved in the transaction is not found" + rnf.getMessage());
} catch (InternalServerErrorException ise) {
System.err.println("Internal Server Error" + ise.getMessage());
} catch (TransactionCanceledException tce) {
System.err.println("Transaction Canceled" + tce.getMessage());
}
```
# Tangkapan data perubahan dengan Amazon DynamoDB
Banyak aplikasi mendapatkan manfaat dari menangkap perubahan ke item yang disimpan dalam tabel DynamoDB pada titik waktu ketika perubahan terjadi. Berikut adalah beberapa contoh kasus penggunaan:
+ Sebuah aplikasi seluler populer memodifikasi data dalam tabel DynamoDB, pada tingkat ribuan pembaruan per detik. Aplikasi lain menangkap dan menyimpan data tentang pembaruan ini, menyediakan metrik near-real-time penggunaan untuk aplikasi seluler.
+ Sebuah aplikasi keuangan memodifikasi data pasar saham dalam tabel DynamoDB. Berbagai aplikasi yang berjalan secara paralel melacak perubahan ini secara real time, menghitung value-at-risk, dan secara otomatis menyeimbangkan portofolio berdasarkan pergerakan harga saham.
+ Sensor dalam kendaraan transportasi dan peralatan industri mengirim data ke meja DynamoDB. Aplikasi yang berbeda memantau kinerja dan mengirim pesan peringatan ketika masalah terdeteksi, memprediksi potensi cacat dengan menerapkan algoritma machine learning, dan mengompres serta mengarsip data ke Amazon Simple Storage Service (Amazon S3).
+ Sebuah aplikasi secara otomatis mengirimkan pemberitahuan ke perangkat seluler dari semua teman dalam grup segera setelah satu teman mengunggah gambar baru.
+ Seorang pelanggan baru menambahkan data ke tabel DynamoDB. Acara ini memanggil aplikasi lain yang mengirimkan email selamat datang ke pelanggan baru.
DynamoDB mendukung streaming catatan tangkapan data perubahan tingkat item yang dalam hampir waktu nyata. Anda dapat membangun aplikasi yang mengkonsumsi stream ini dan mengambil tindakan berdasarkan isinya.
**catatan**
Menambahkan tag ke DynamoDB Streams dan [menggunakan kontrol akses berbasis atribut (ABAC)](access-control-resource-based.md) dengan DynamoDB Streams tidak didukung.
Video berikut akan memberi Anda tampilan pengantar tentang konsep pengambilan data perubahan.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/VVv_-mZ5Ge8)
**Topics**
+ [Opsi streaming untuk tangkapan data perubahan](#streamsmain.choose)
+ [Menggunakan Kinesis Data Streams untuk menangkap perubahan pada DynamoDB](kds.md)
+ [Tangkapan data perubahan DynamoDB Streams](Streams.md)
## Opsi streaming untuk tangkapan data perubahan
DynamoDB menawarkan dua model streaming untuk penangkapan data perubahan: Kinesis Data Streams untuk DynamoDB dan DynamoDB Streams.
Untuk membantu Anda memilih solusi yang tepat untuk aplikasi Anda, tabel berikut merangkum fitur dari setiap model streaming.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/streamsmain.html)
Anda dapat mengaktifkan kedua model streaming pada tabel DynamoDB yang sama.
Video berikut berbicara lebih banyak tentang perbedaan antara dua opsi tersebut.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/UgG17Wh2y0g)
# Menggunakan Kinesis Data Streams untuk menangkap perubahan pada DynamoDB
Gunakan Amazon Kinesis Data Streams untuk menangkap perubahan pada Amazon DynamoDB.
Kinesis Data Streams menangkap modifikasi tingkat item di tabel DynamoDB apa pun dan mereplikasikannya ke [Kinesis data stream.](https://docs.aws.amazon.com/streams/latest/dev/introduction.html) Aplikasi Anda dapat mengakses stream ini dan melihat perubahan tingkat item dalam hampir waktu nyata. Anda dapat terus menangkap dan menyimpan data berukuran terabyte per jam. Anda dapat memanfaatkan waktu retensi data yang lebih lama—dan dengan kemampuan fan-out yang ditingkatkan, Anda dapat menjangkau dua atau lebih aplikasi hilir secara bersamaan. Manfaat lainnya termasuk audit tambahan dan transparansi keamanan.
Kinesis Data Streams juga memberi Anda akses [ke Amazon Data [Firehose dan Amazon](https://docs.aws.amazon.com/kinesisanalytics/latest/dev/what-is.html) Managed](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) Service untuk Apache Flink. Layanan ini dapat membantu Anda membangun aplikasi yang mendukung dasbor real-time, menghasilkan peringatan, menerapkan penetapan harga dan periklanan dinamis, serta menerapkan analitik data dan algoritma machine learning yang canggih.
**catatan**
[Menggunakan aliran data Kinesis untuk DynamoDB tunduk pada harga Kinesis Data Streams untuk aliran data dan [harga DynamoDB untuk tabel sumber](https://aws.amazon.com/kinesis/data-streams/pricing/).](https://aws.amazon.com/dynamodb/pricing/)
Untuk mengaktifkan Kinesis streaming pada tabel DynamoDB menggunakan konsol, atau Java SDK AWS CLI, lihat. [Memulai Kinesis Data Streams untuk Amazon DynamoDB](kds_gettingstarted.md)
**Topics**
+ [Cara kerja Kinesis Data Streams dengan DynamoDB](#kds_howitworks)
+ [Memulai Kinesis Data Streams untuk Amazon DynamoDB](kds_gettingstarted.md)
+ [Menggunakan pecahan dan metrik dengan DynamoDB Streams dan Kinesis Data Streams](kds_using-shards-and-metrics.md)
+ [Menggunakan kebijakan IAM untuk Amazon Kinesis Data Streams dan Amazon DynamoDB](kds_iam.md)
## Cara kerja Kinesis Data Streams dengan DynamoDB
Ketika aliran data Kinesis diaktifkan untuk tabel DynamoDB, tabel mengirimkan rekaman data yang mencatat perubahan apa pun pada data tabel tersebut. Catatan data ini meliputi:
+ Waktu spesifik item mana pun baru saja dibuat, diperbarui, atau dihapus
+ Kunci utama item itu
+ Cuplikan catatan sebelum modifikasi
+ Cuplikan catatan setelah modifikasi
Catatan data ini diambil dan dipublikasikan hampir secara waktu nyata. Setelah ditulis ke aliran data Kinesis, data tersebut dapat dibaca seperti catatan lainnya. Anda dapat menggunakan Kinesis Client Library, menggunakan AWS Lambda, memanggil Kinesis Data Streams API, dan menggunakan layanan terhubung lainnya. Untuk informasi selengkapnya, lihat [Membaca Data dari Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html) dalam Panduan Developer Amazon Kinesis Data Streams.
Perubahan pada data ini juga ditangkap secara asinkron. Kinesis tidak memiliki dampak kinerja pada tabel asal streamingnya. Catatan aliran yang disimpan dalam aliran data Kinesis Anda juga dienkripsi saat tidak digunakan. Untuk informasi selengkapnya, lihat [Perlindungan Data di Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/server-side-encryption.html).
Catatan aliran data Kinesis mungkin muncul dalam urutan yang berbeda dari saat perubahan item terjadi. Notifikasi item yang sama mungkin juga muncul lebih dari satu kali di aliran. Anda dapat memeriksa `ApproximateCreationDateTime` atribut untuk mengidentifikasi urutan modifikasi item terjadi, dan untuk mengidentifikasi catatan duplikat.
Saat Anda mengaktifkan aliran data Kinesis sebagai tujuan streaming tabel DynamoDB, Anda dapat mengonfigurasi presisi `ApproximateCreationDateTime` nilai dalam milidetik atau mikrodetik. Secara default, `ApproximateCreationDateTime` menunjukkan waktu perubahan dalam milidetik. Selain itu, Anda dapat mengubah nilai ini di tujuan streaming aktif. Setelah pembaruan seperti itu, catatan aliran yang ditulis ke Kinesis akan memiliki `ApproximateCreationDateTime` nilai presisi yang diinginkan.
Nilai biner yang ditulis ke DynamoDB harus dikodekan dalam [format berenkode base64](HowItWorks.NamingRulesDataTypes.md) . Namun, ketika catatan data ditulis ke aliran data Kinesis, nilai biner yang dikodekan ini dikodekan dengan pengodean base64 untuk kedua kalinya. Saat membaca catatan ini dari aliran data Kinesis, untuk mengambil nilai biner mentah, aplikasi harus mendekode nilai ini dua kali.
DynamoDB mengenakan biaya untuk penggunaan Kinesis Data Streams dalam unit pengambilan data perubahan. Perubahan 1 KB per item dihitung sebagai satu unit pengambilan data perubahan. KB perubahan di setiap item dihitung berdasarkan gambar "sebelum" dan "sesudah" yang lebih besar dari item yang ditulis ke aliran, menggunakan logika yang sama dengan [konsumsi unit kapasitas untuk operasi tulis](read-write-operations.md#write-operation-consumption). Mirip dengan bagaimana mode DynamoDB [sesuai permintaan](capacity-mode.md#capacity-mode-on-demand) bekerja, Anda tidak perlu menyediakan throughput kapasitas untuk unit penangkapan data perubahan.
### Mengaktifkan aliran data Kinesis untuk tabel DynamoDB Anda
Anda dapat mengaktifkan atau menonaktifkan streaming ke Kinesis dari tabel DynamoDB yang ada dengan menggunakan, AWS SDK Konsol Manajemen AWS, atau (). AWS Command Line Interface AWS CLI
+ Anda hanya dapat mengalirkan data dari DynamoDB ke Kinesis Data Streams di AWS akun dan Wilayah yang sama dengan tabel Anda. AWS
+ Anda hanya dapat melakukan streaming data dari tabel DynamoDB ke satu Kinesis data stream.
### Membuat perubahan pada tujuan Kinesis Data Streams pada tabel DynamoDB
Secara default, semua catatan aliran data Kinesis menyertakan atribut`ApproximateCreationDateTime`. Atribut ini mewakili stempel waktu dalam milidetik dari perkiraan waktu ketika setiap rekaman dibuat. Anda dapat mengubah presisi nilai-nilai ini dengan menggunakan [https://console.aws.amazon.com/kinesis](https://console.aws.amazon.com/kinesis), SDK atau AWS CLI
# Memulai Kinesis Data Streams untuk Amazon DynamoDB
Bagian ini menjelaskan cara menggunakan Kinesis Data Streams untuk tabel Amazon DynamoDB dengan konsol Amazon AWS Command Line Interface AWS CLI DynamoDB, (), dan API.
## Membuat aliran data Amazon Kinesis yang aktif
Semua contoh ini menggunakan tabel `Music` DynamoDB yang dibuat sebagai bagian dari tutorial [Memulai dengan DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html).
Untuk mempelajari lebih lanjut tentang cara membangun konsumen dan menghubungkan aliran data Kinesis Anda ke layanan AWS lain, lihat [Membaca data dari Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html) dalam *panduan pengembang Amazon Kinesis Data Streams*.
**catatan**
Saat Anda pertama kali menggunakan serpihan KDS, sebaiknya atur serpihan Anda untuk ditingkatkan dan diturunkan skalanya sesuai dengan pola penggunaan. Setelah mengumpulkan lebih banyak data tentang pola penggunaan, Anda dapat menyesuaikan serpihan di aliran agar sesuai.
------
#### [ Console ]
1. Masuk ke Konsol Manajemen AWS dan buka konsol Kinesis di. [https://console.aws.amazon.com/kinesis/](https://console.aws.amazon.com/kinesis/)
1. Pilih **Buat aliran data** dan ikuti petunjuk untuk membuat stream yang disebut `samplestream`.
1. Buka konsol DynamoDB di. [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)
1. Di panel navigasi di sisi kiri konsol, pilih **Tabel**.
1. Pilih tabel **Musik**.
1. Pilih tab **Ekspor dan aliran**.
1. (Opsional) Di bawah **detail aliran data Amazon Kinesis**, Anda dapat mengubah presisi stempel waktu rekaman dari mikrodetik (default) menjadi milidetik.
1. Pilih **samplestream** dari daftar menurun.
1. Pilih tombol **Hidupkan**.
------
#### [ AWS CLI ]
1. Buat Kinesis Data Streams bernama `samplestream` dengan menggunakan [perintah create-stream](https://docs.aws.amazon.com/cli/latest/reference/kinesis/create-stream.html).
```
aws kinesis create-stream --stream-name samplestream --shard-count 3
```
Lihat [Pertimbangan manajemen pecahan untuk Kinesis Data Streams](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment) sebelum menetapkan jumlah serpihan untuk Kinesis data stream.
1. Periksa apakah stream Kinesis aktif dan siap digunakan dengan menggunakan [perintah describe-stream](https://docs.aws.amazon.com/cli/latest/reference/kinesis/describe-stream.html).
```
aws kinesis describe-stream --stream-name samplestream
```
1. Aktifkan Kinesis streaming pada tabel DynamoDB dengan menggunakan perintah `enable-kinesis-streaming-destination` DynamoDB. Ganti `stream-arn` nilai dengan yang ditampilkan `describe-stream` pada langkah sebelumnya. Secara opsional, aktifkan streaming dengan presisi nilai stempel waktu yang lebih granular (mikrodetik) yang dikembalikan pada setiap catatan.
Aktifkan streaming dengan presisi stempel waktu mikrodetik:
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
--enable-kinesis-streaming-configuration ApproximateCreationDateTimePrecision=MICROSECOND
```
Atau aktifkan streaming dengan presisi stempel waktu default (milidetik):
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
```
1. Periksa apakah streaming Kinesis aktif pada tabel DynamoDB dengan menggunakan perintah `describe-kinesis-streaming-destination` DynamoDB.
```
aws dynamodb describe-kinesis-streaming-destination --table-name Music
```
1. Menulis data ke Daftar Tabel DynamoDB dengan menggunakan perintah `put-item`, seperti yang dijelaskan dalam [Panduan Developer DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-2.html).
```
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "No One You Know"}, "SongTitle": {"S": "Call Me Today"}, "AlbumTitle": {"S": "Somewhat Famous"}, "Awards": {"N": "1"}}'
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "Acme Band"}, "SongTitle": {"S": "Happy Day"}, "AlbumTitle": {"S": "Songs About Life"}, "Awards": {"N": "10"} }'
```
1. Gunakan perintah CLI Kinesis [get-records](https://docs.aws.amazon.com/cli/latest/reference/kinesis/get-records.html) untuk mengambil konten stream Kinesis. Kemudian gunakan potongan kode berikut untuk melakukan deserialisasi konten stream.
```
/**
* Takes as input a Record fetched from Kinesis and does arbitrary processing as an example.
*/
public void processRecord(Record kinesisRecord) throws IOException {
ByteBuffer kdsRecordByteBuffer = kinesisRecord.getData();
JsonNode rootNode = OBJECT_MAPPER.readTree(kdsRecordByteBuffer.array());
JsonNode dynamoDBRecord = rootNode.get("dynamodb");
JsonNode oldItemImage = dynamoDBRecord.get("OldImage");
JsonNode newItemImage = dynamoDBRecord.get("NewImage");
Instant recordTimestamp = fetchTimestamp(dynamoDBRecord);
/**
* Say for example our record contains a String attribute named "stringName" and we want to fetch the value
* of this attribute from the new item image. The following code fetches this value.
*/
JsonNode attributeNode = newItemImage.get("stringName");
JsonNode attributeValueNode = attributeNode.get("S"); // Using DynamoDB "S" type attribute
String attributeValue = attributeValueNode.textValue();
System.out.println(attributeValue);
}
private Instant fetchTimestamp(JsonNode dynamoDBRecord) {
JsonNode timestampJson = dynamoDBRecord.get("ApproximateCreationDateTime");
JsonNode timestampPrecisionJson = dynamoDBRecord.get("ApproximateCreationDateTimePrecision");
if (timestampPrecisionJson != null && timestampPrecisionJson.equals("MICROSECOND")) {
return Instant.EPOCH.plus(timestampJson.longValue(), ChronoUnit.MICROS);
}
return Instant.ofEpochMilli(timestampJson.longValue());
}
```
------
#### [ Java ]
1. Ikuti petunjuk dalam panduan developer Kinesis Data Streams untuk [menciptakan](https://docs.aws.amazon.com/streams/latest/dev/kinesis-using-sdk-java-create-stream.html) Kinesis data stream bernama `samplestream` menggunakan Java.
Lihat [Pertimbangan manajemen pecahan untuk Kinesis Data Streams](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment) sebelum menetapkan jumlah serpihan untuk Kinesis data stream.
1. Gunakan cuplikan kode berikut untuk mengaktifkan Kinesis streaming pada tabel DynamoDB. Secara opsional, aktifkan streaming dengan presisi nilai stempel waktu yang lebih granular (mikrodetik) yang dikembalikan pada setiap catatan.
Aktifkan streaming dengan presisi stempel waktu mikrodetik:
```
EnableKinesisStreamingConfiguration enableKdsConfig = EnableKinesisStreamingConfiguration.builder()
.approximateCreationDateTimePrecision(ApproximateCreationDateTimePrecision.MICROSECOND)
.build();
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.enableKinesisStreamingConfiguration(enableKdsConfig)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
Atau aktifkan streaming dengan presisi stempel waktu default (milidetik):
```
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
1. Ikuti instruksi dalam panduan pengembang *Kinesis Data Streams* untuk [membaca](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html) dari aliran data yang dibuat.
1. Gunakan potongan kode berikut untuk melakukan deserialisasi konten stream
```
/**
* Takes as input a Record fetched from Kinesis and does arbitrary processing as an example.
*/
public void processRecord(Record kinesisRecord) throws IOException {
ByteBuffer kdsRecordByteBuffer = kinesisRecord.getData();
JsonNode rootNode = OBJECT_MAPPER.readTree(kdsRecordByteBuffer.array());
JsonNode dynamoDBRecord = rootNode.get("dynamodb");
JsonNode oldItemImage = dynamoDBRecord.get("OldImage");
JsonNode newItemImage = dynamoDBRecord.get("NewImage");
Instant recordTimestamp = fetchTimestamp(dynamoDBRecord);
/**
* Say for example our record contains a String attribute named "stringName" and we wanted to fetch the value
* of this attribute from the new item image, the below code would fetch this.
*/
JsonNode attributeNode = newItemImage.get("stringName");
JsonNode attributeValueNode = attributeNode.get("S"); // Using DynamoDB "S" type attribute
String attributeValue = attributeValueNode.textValue();
System.out.println(attributeValue);
}
private Instant fetchTimestamp(JsonNode dynamoDBRecord) {
JsonNode timestampJson = dynamoDBRecord.get("ApproximateCreationDateTime");
JsonNode timestampPrecisionJson = dynamoDBRecord.get("ApproximateCreationDateTimePrecision");
if (timestampPrecisionJson != null && timestampPrecisionJson.equals("MICROSECOND")) {
return Instant.EPOCH.plus(timestampJson.longValue(), ChronoUnit.MICROS);
}
return Instant.ofEpochMilli(timestampJson.longValue());
}
```
------
## Membuat perubahan pada aliran data Amazon Kinesis yang aktif
Bagian ini menjelaskan cara membuat perubahan pada Kinesis Data Streams aktif untuk penyiapan DynamoDB dengan menggunakan konsol, dan API. AWS CLI
**Konsol Manajemen AWS**
1. Buka konsol DynamoDB di [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)
1. Pergi ke meja Anda.
1. Pilih **Ekspor dan Aliran**.
**AWS CLI**
1. Hubungi `describe-kinesis-streaming-destination` untuk mengonfirmasi bahwa streaming tersebut`ACTIVE`.
1. Panggilan`UpdateKinesisStreamingDestination`, seperti dalam contoh ini:
```
aws dynamodb update-kinesis-streaming-destination --table-name enable_test_table --stream-arn arn:aws:kinesis:us-east-1:12345678901:stream/enable_test_stream --update-kinesis-streaming-configuration ApproximateCreationDateTimePrecision=MICROSECOND
```
1. Hubungi `describe-kinesis-streaming-destination` untuk mengonfirmasi bahwa streaming tersebut`UPDATING`.
1. Panggil `describe-kinesis-streaming-destination` secara berkala hingga status streaming `ACTIVE` kembali. Biasanya diperlukan waktu hingga 5 menit agar pembaruan presisi stempel waktu diterapkan. Setelah status ini diperbarui, itu menunjukkan bahwa pembaruan selesai dan nilai presisi baru akan diterapkan pada catatan masa depan.
1. Tulis ke meja menggunakan`putItem`.
1. Gunakan `get-records` perintah Kinesis untuk mendapatkan konten aliran.
1. Konfirmasikan bahwa penulisan memiliki presisi yang diinginkan. `ApproximateCreationDateTime`
**API Java**
1. Berikan cuplikan kode yang membuat `UpdateKinesisStreamingDestination` permintaan dan respons. `UpdateKinesisStreamingDestination`
1. Berikan cuplikan kode yang membuat `DescribeKinesisStreamingDestination` permintaan dan file. `DescribeKinesisStreamingDestination response`
1. Panggil `describe-kinesis-streaming-destination` secara berkala hingga status streaming `ACTIVE` kembali, menunjukkan bahwa pembaruan selesai dan nilai presisi baru akan diterapkan pada catatan masa depan.
1. Lakukan menulis ke meja.
1. Baca dari aliran dan deserialisasi konten streaming.
1. Konfirmasikan bahwa penulisan memiliki presisi yang diinginkan. `ApproximateCreationDateTime`
# Menggunakan pecahan dan metrik dengan DynamoDB Streams dan Kinesis Data Streams
## Pertimbangan manajemen pecahan untuk Kinesis Data Streams
Kinesis data strea, menghitung throughputnya dalam [pecahan](https://docs.aws.amazon.com/streams/latest/dev/key-concepts.html). Di Amazon Kinesis Data stream, Anda dapat memilih antara mode **sesuai permintaan** dan mode yang **disediakan** untuk aliran data Anda.
Sebaiknya gunakan mode sesuai permintaan untuk Kinesis Data Stream Anda jika beban kerja penulisan DynamoDB Anda sangat bervariasi dan tidak dapat diprediksi. Dengan mode on-demand, tidak ada perencanaan kapasitas yang diperlukan karena Kinesis Data Streams secara otomatis mengelola pecahan untuk menyediakan throughput yang diperlukan.
Untuk beban kerja yang dapat diprediksi, Anda dapat menggunakan mode yang disediakan untuk Kinesis Data Stream Anda. Dengan mode yang disediakan, Anda harus menentukan jumlah pecahan untuk aliran data untuk mengakomodasi catatan pengambilan data perubahan dari DynamoDB. Untuk menentukan jumlah pecahan yang dibutuhkan aliran data Kinesis untuk mendukung tabel DynamoDB Anda, Anda memerlukan nilai input berikut:
+ Ukuran rata-rata catatan tabel DynamoDB Anda dalam byte (`average_record_size_in_bytes`).
+ Jumlah maksimum operasi tulis yang tabel DynamoDB Anda akan melakukan per detik. Ini termasuk membuat, menghapus, dan memperbarui operasi yang dilakukan oleh aplikasi Anda, serta operasi yang dihasilkan secara otomatis seperti Time to Live generated delete operations (`write_throughput`).
+ Persentase operasi pembaruan dan penimpaan yang Anda lakukan pada tabel Anda, dibandingkan dengan membuat atau menghapus operasi (`percentage_of_updates`). Perlu diingat bahwa operasi pembaruan dan penimpaan mereplikasi gambar lama dan baru dari item yang dimodifikasi ke stream. Ini menghasilkan dua kali ukuran item DynamoDB.
Anda dapat menghitung jumlah pecahan (`number_of_shards`) yang dibutuhkan aliran data Kinesis Anda dengan menggunakan nilai input dalam rumus berikut:
```
number_of_shards = ceiling( max( ((write_throughput * (4+percentage_of_updates) * average_record_size_in_bytes) / 1024 / 1024), (write_throughput/1000)), 1)
```
Misalnya, Anda mungkin memiliki throughput maksimum 1040 operasi tulis per detik (`write_throughput`) dengan ukuran catatan rata-rata 800 byte (. `average_record_size_in_bytes)` Jika 25 persen dari operasi penulisan tersebut adalah operasi pembaruan (`percentage_of_updates`), maka Anda akan memerlukan dua pecahan (`number_of_shards`) untuk mengakomodasi throughput streaming DynamoDB Anda:
```
ceiling( max( ((1040 * (4+25/100) * 800)/ 1024 / 1024), (1040/1000)), 1).
```
Pertimbangkan hal berikut sebelum menggunakan rumus untuk menghitung jumlah pecahan yang diperlukan dengan mode yang disediakan untuk aliran data Kinesis:
+ Rumus ini membantu memperkirakan jumlah pecahan yang akan diperlukan untuk mengakomodasi catatan data perubahan DynamoDB Anda. Ini tidak mewakili jumlah total pecahan yang dibutuhkan dalam aliran data Kinesis Anda, seperti jumlah pecahan yang diperlukan untuk mendukung konsumen aliran data Kinesis tambahan.
+ Anda mungkin masih mengalami pengecualian throughput baca dan tulis dalam mode yang disediakan jika Anda tidak mengonfigurasi aliran data untuk menangani throughput puncak Anda. Dalam hal ini, Anda harus menskalakan aliran data Anda secara manual untuk mengakomodasi lalu lintas data Anda.
+ Rumus ini mempertimbangkan bloat tambahan yang dihasilkan oleh DynamoDB sebelum mengalirkan catatan data log perubahan ke Kinesis Data Stream.
Untuk mempelajari lebih lanjut tentang mode kapasitas pada Kinesis Data Stream lihat [Memilih Mode Kapasitas Aliran Data](https://docs.aws.amazon.com/streams/latest/dev/how-do-i-size-a-stream.html). Untuk mempelajari selengkapnya tentang perbedaan harga antara mode kapasitas yang berbeda, lihat harga [Amazon Kinesis Data Streams](https://aws.amazon.com/kinesis/data-streams/pricing/).
## Memantau pengambilan data perubahan dengan Kinesis Data Streams
DynamoDB menyediakan beberapa metrik CloudWatch Amazon untuk membantu Anda memantau replikasi pengambilan data perubahan ke Kinesis. Untuk daftar lengkap CloudWatch metrik, lihat[Dimensi dan Metrik DynamoDB](metrics-dimensions.md).
Untuk menentukan apakah streaming Anda memiliki kapasitas yang memadai, sebaiknya pantau item berikut selama pengaktifan streaming dan produksi:
+ `ThrottledPutRecordCount`: Jumlah catatan yang dibatasi oleh aliran data Kinesis Anda karena kapasitas aliran data Kinesis tidak mencukupi. Anda mungkin mengalami beberapa throttling selama puncak penggunaan yang luar biasa, namun `ThrottledPutRecordCount` harus tetap serendah mungkin. DynamoDB mencoba lagi mengirimkan catatan yang dibatasi ke aliran data Kinesis, namun hal ini mungkin mengakibatkan latensi replikasi yang lebih tinggi.
Jika Anda mengalami throttling yang berlebihan dan secara rutin, maka Anda mungkin perlu meningkatkan jumlah serpihan aliran Kinesis secara proporsional dengan throughput tulis yang diamati pada tabel Anda. Untuk mempelajari selengkapnya tentang menentukan ukuran Kinesis data stream, lihat [Menentukan Ukuran Awal Kinesis Data Stream](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-streams.html#how-do-i-size-a-stream).
+ `AgeOfOldestUnreplicatedRecord`: Waktu yang berlalu sejak perubahan tingkat item terlama yang belum direplikasi ke aliran data Kinesis muncul di tabel DynamoDB. Dalam operasi normal, `AgeOfOldestUnreplicatedRecord` harus dalam urutan milidetik. Jumlah ini bertambah berdasarkan upaya replikasi yang gagal karena pilihan konfigurasi yang dikontrol pelanggan.
Jika `AgeOfOldestUnreplicatedRecord` metrik melebihi 168 jam, replikasi perubahan tingkat item dari tabel DynamoDB ke aliran data Kinesis akan dinonaktifkan secara otomatis.
Contoh konfigurasi yang dikontrol pelanggan yang menyebabkan upaya replikasi gagal adalah kapasitas aliran data Kinesis yang kurang tersedia sehingga menyebabkan throttling berlebihan, atau pembaruan manual pada kebijakan akses aliran data Kinesis Anda yang mencegah DynamoDB menambahkan data ke aliran data Anda. Untuk menjaga metrik ini serendah mungkin, Anda mungkin perlu memastikan penyediaan kapasitas aliran data Kinesis yang tepat, dan memastikan bahwa izin DynamoDB tidak berubah.
+ `FailedToReplicateRecordCount`: Jumlah catatan yang gagal direplikasi DynamoDB ke Kinesis data stream Anda. Item tertentu yang lebih besar dari 34 KB mungkin bertambah besar ukurannya untuk mengubah catatan data yang lebih besar dari batas ukuran item 1 MB Kinesis Data Streams. Perluasan ukuran ini terjadi ketika item yang lebih besar dari 34 KB ini menyertakan sejumlah besar nilai atribut Boolean atau kosong. Nilai atribut Boolean dan kosong disimpan sebagai 1 byte di DynamoDB, namun diperluas hingga 5 byte saat diserialkan menggunakan JSON standar untuk replikasi Kinesis Data Streams. DynamoDB tidak dapat mereplikasi catatan perubahan tersebut ke aliran data Kinesis Anda. DynamoDB akan melewatkan catatan data perubahan ini, dan secara otomatis akan tetap melakukan replikasi atas catatan-catatan berikutnya.
Anda dapat membuat CloudWatch alarm Amazon yang mengirim pesan Amazon Simple Notification Service (Amazon SNS) untuk pemberitahuan ketika salah satu metrik sebelumnya melebihi ambang batas tertentu.
# Menggunakan kebijakan IAM untuk Amazon Kinesis Data Streams dan Amazon DynamoDB
Saat pertama kali Anda mengaktifkan Amazon Kinesis Data Streams untuk Amazon DynamoDB, DynamoDB secara otomatis membuat peran terkait layanan (IAM) untuk Anda. AWS Identity and Access Management Peran ini, `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication`, memungkinkan DynamoDB untuk mengelola replikasi perubahan tingkat item ke Kinesis Data Streams atas nama Anda. Jangan hapus peran tertaut layanan ini.
Untuk informasi selengkapnya tentang peran tertaut layanan, lihat [Menggunakan peran tertaut layanan](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) di *Panduan Pengguna IAM*.
**catatan**
DynamoDB tidak mendukung kondisi berbasis tag untuk kebijakan IAM.
Untuk mengaktifkan Amazon Kinesis Data Streams untuk Amazon DynamoDB, Anda harus memiliki izin berikut di tabel:
+ `dynamodb:EnableKinesisStreamingDestination`
+ `kinesis:ListStreams`
+ `kinesis:PutRecords`
+ `kinesis:DescribeStream`
Untuk menjelaskan Amazon Kinesis Data Streams untuk Amazon DynamoDB untuk tabel DynamoDB tertentu, Anda harus memiliki izin berikut pada tabel.
+ `dynamodb:DescribeKinesisStreamingDestination`
+ `kinesis:DescribeStreamSummary`
+ `kinesis:DescribeStream`
Untuk menonaktifkan Amazon Kinesis Data Streams untuk Amazon DynamoDB, Anda harus memiliki izin berikut pada tabel.
+ `dynamodb:DisableKinesisStreamingDestination`
Untuk memperbarui Amazon Kinesis Data Streams untuk Amazon DynamoDB, Anda harus memiliki izin berikut di atas tabel.
+ `dynamodb:UpdateKinesisStreamingDestination`
Contoh berikut menunjukkan cara menggunakan kebijakan IAM untuk memberikan izin untuk Amazon Kinesis Data Streams untuk Amazon DynamoDB.
## Contoh: Mengaktifkan Amazon Kinesis Data Streams untuk Amazon DynamoDB
Kebijakan IAM berikut memberikan izin untuk mengaktifkan Amazon Kinesis Data Streams untuk Amazon DynamoDB untuk tabel. `Music` Itu tidak memberikan izin untuk menonaktifkan, memperbarui atau menjelaskan Kinesis Data Streams untuk DynamoDB untuk tabel. `Music`
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/kinesisreplication.dynamodb.amazonaws.com/AWSServiceRoleForDynamoDBKinesisDataStreamsReplication",
"Condition": {
"StringLike": {
"iam:AWSServiceName": "kinesisreplication.dynamodb.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:EnableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## Contoh: Perbarui Amazon Kinesis Data Streams untuk Amazon DynamoDB
Kebijakan IAM berikut memberikan izin untuk memperbarui Amazon Kinesis Data Streams untuk Amazon DynamoDB untuk tabel. `Music` Itu tidak memberikan izin untuk mengaktifkan, menonaktifkan, atau menjelaskan Amazon Kinesis Data Streams untuk Amazon DynamoDB untuk tabel. `Music`
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:UpdateKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## Contoh: Menonaktifkan Amazon Kinesis Data Streams untuk Amazon DynamoDB
Kebijakan IAM berikut memberikan izin untuk menonaktifkan Amazon Kinesis Data Streams untuk Amazon DynamoDB untuk tabel. `Music` Itu tidak memberikan izin untuk mengaktifkan, memperbarui, atau menjelaskan Amazon Kinesis Data Streams untuk Amazon DynamoDB untuk tabel. `Music`
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## Contoh: Selektif menerapkan izin untuk Amazon Kinesis Data Streams untuk Amazon DynamoDB berdasarkan sumber daya
Kebijakan IAM berikut memberikan izin untuk mengaktifkan dan menjelaskan Amazon Kinesis Data Streams untuk Amazon DynamoDB untuk tabel, dan menolak izin untuk menonaktifkan Amazon Kinesis Data Streams `Music` untuk Amazon DynamoDB untuk tabel. `Orders`
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:EnableKinesisStreamingDestination",
"dynamodb:DescribeKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
},
{
"Effect": "Deny",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Orders"
}
]
}
```
------
## Menggunakan peran tertaut layanan untuk Kinesis Data Streams untuk DynamoDB
[Amazon Kinesis Data Streams untuk Amazon DynamoDB menggunakan peran terkait layanan ( AWS Identity and Access Management IAM).](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role) Peran tertaut layanan adalah jenis IAM role unik yang ditautkan langsung ke Kinesis Data Streams untuk DynamoDB. Peran terkait layanan telah ditentukan sebelumnya oleh Kinesis Data Streams untuk DynamoDB dan menyertakan semua izin yang diperlukan layanan untuk memanggil layanan lain atas nama Anda. AWS
Peran tertaut layanan membuat pengaturan Kinesis Data Streams untuk DynamoDB lebih mudah karena Anda tidak perlu menambahkan izin yang diperlukan secara manual. Kinesis Data Streams untuk DynamoDB menentukan izin peran terkait layanannya, dan kecuali ditentukan lain, hanya Kinesis Data Streams untuk DynamoDB yang dapat mengambil peran tersebut. Izin yang ditentukan mencakup kebijakan kepercayaan dan kebijakan izin, serta bahwa kebijakan izin tidak dapat dilampirkan ke entitas IAM lainnya.
Untuk informasi tentang layanan lain yang mendukung peran terkait layanan, lihat [Layanan AWS yang Berfungsi dengan IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) dan cari layanan yang memiliki **Ya** di kolom **Peran Terkait Layanan**. Pilih **Ya** dengan tautan untuk melihat dokumentasi peran terkait layanan untuk layanan tersebut.
### Izin peran tertaut layanan untuk Kinesis Data Streams untuk DynamoDB
Kinesis Data Streams untuk DynamoDB menggunakan peran terkait layanan bernama. **AWSServiceRoleForDynamoDBKinesisDataStreamsReplication** Tujuan dari peran tertaut layanan adalah untuk memungkinkan Amazon DynamoDB mengelola replikasi perubahan tingkat item pada Kinesis Data Streams, atas nama Anda.
Peran tertaut layanan `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` memercayai layanan berikut untuk mengambil peran tersebut:
+ `kinesisreplication.dynamodb.amazonaws.com`
Kebijakan izin peran memungkinkan Kinesis Data Streams for DynamoDB menyelesaikan tindakan berikut pada sumber daya yang ditentukan:
+ Tindakan: `Put records and describe` pada `Kinesis stream`
+ Tindakan: `Generate data keys` aktif `AWS KMS` untuk menempatkan data pada aliran Kinesis yang dienkripsi menggunakan kunci Buatan Pengguna. AWS KMS
Untuk isi dokumen kebijakan yang tepat, lihat [Dynamo DBKinesis ReplicationServiceRolePolicy](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/aws-service-role/DynamoDBKinesisReplicationServiceRolePolicy).
Anda harus mengonfigurasi izin untuk mengizinkan entitas IAM (seperti pengguna, grup, atau peran) untuk membuat, mengedit, atau menghapus peran terkait layanan. Untuk informasi selengkapnya, silakan lihat [Izin Peran Tertaut Layanan](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#service-linked-role-permissions) di *Panduan Pengguna IAM*.
### Membuat peran tertaut layanan untuk Kinesis Data Streams untuk DynamoDB
Anda tidak perlu membuat peran terkait layanan secara manual. Saat Anda mengaktifkan Kinesis Data Streams untuk Konsol Manajemen AWS DynamoDB di AWS CLI, atau AWS API, Kinesis Data Streams untuk DynamoDB akan membuat peran terkait layanan untuk Anda.
Jika Anda menghapus peran terkait layanan ini, dan ingin membuatnya lagi, Anda dapat mengulangi proses yang sama untuk membuat kembali peran tersebut di akun Anda. Saat Anda mengaktifkan Kinesis Data Streams untuk DynamoDB, Kinesis Data Streams untuk DynamoDB menciptakan peran terkait layanan untuk Anda lagi.
### Mengedit peran tertaut layanan untuk Kinesis Data Streams untuk DynamoDB
Kinesis Data Streams untuk DynamoDB tidak mengizinkan Anda mengedit peran tertaut layanan `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication`. Setelah membuat peran terkait layanan, Anda tidak dapat mengubah nama peran karena berbagai entitas mungkin mereferensikan peran tersebut. Namun, Anda dapat mengedit penjelasan peran menggunakan IAM. Untuk informasi selengkapnya, lihat [Mengedit Peran terkait Layanan](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#edit-service-linked-role) di *Panduan Pengguna IAM*.
### Menghapus peran tertaut layanan untuk Kinesis Data Streams untuk DynamoDB
Anda juga dapat menggunakan konsol IAM, AWS CLI atau AWS API untuk menghapus peran terkait layanan secara manual. Untuk melakukannya, Anda harus membersihkan sumber daya untuk peran tertaut layanan terlebih dahulu, lalu Anda dapat menghapusnya secara manual.
**catatan**
Jika layanan Kinesis Data Streams for DynamoDB menggunakan peran tersebut saat Anda mencoba menghapus sumber daya, maka penghapusan mungkin gagal. Jika hal itu terjadi, tunggu beberapa menit dan coba lagi.
**Untuk menghapus peran tertaut layanan secara manual menggunakan IAM**
Gunakan konsol IAM, the AWS CLI, atau AWS API untuk menghapus peran `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` terkait layanan. Untuk informasi selengkapnya, lihat [Menghapus Peran Terkait Layanan](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) di *Panduan Pengguna IAM*.
# Tangkapan data perubahan DynamoDB Streams
DynamoDB Streams menangkap urutan waktu modifikasi tingkat item di tabel DynamoDB mana pun dan menyimpan informasi ini dalam log hingga 24 jam. Aplikasi dapat mengakses log ini dan melihat item data seperti yang muncul sebelum dan setelah diubah, hampir secara waktu nyata.
Enkripsi saat istirahat mengenkripsi data dalam DynamoDB streams. Untuk informasi selengkapnya, lihat [Enkripsi DynamoDB saat diam](EncryptionAtRest.md).
*Streami DynamoDB* adalah aliran berurutan informasi tentang perubahan item dalam tabel DynamoDB. Saat Anda mengaktifkan aliran pada tabel, DynamoDB menangkap informasi tentang setiap modifikasi pada item data dalam tabel.
Setiap kali aplikasi membuat, memperbarui, atau menghapus item dalam tabel, DynamoDB Streams menulis rekaman aliran dengan atribut kunci primer dari item yang diubah. *Catatan stream* berisi informasi tentang modifikasi data pada satu item dalam tabel DynamoDB. Anda dapat mengonfigurasi aliran sehingga rekaman aliran menangkap informasi tambahan, seperti gambar "sebelum" dan "sesudah" dari item yang diubah.
DynamoDB Streams membantu memastikan hal berikut:
+ Setiap catatan stream muncul tepat sekali dalam stream.
+ Untuk setiap item yang diubah dalam tabel DynamoDB, catatan stream muncul dalam urutan yang sama seperti modifikasi aktual untuk item.
DynamoDB Streams menulis catatan aliran hampir secara real-time sehingga Anda dapat membangun aplikasi yang menggunakan aliran ini dan mengambil tindakan berdasarkan kontennya.
**Topics**
+ [Titik akhir untuk DynamoDB Streams](#Streams.Endpoints)
+ [Mengaktifkan aliran](#Streams.Enabling)
+ [Membaca dan memproses aliran](#Streams.Processing)
+ [DynamoDB Streams dan Waktu untuk Tayang](time-to-live-ttl-streams.md)
+ [Menggunakan adaptor DynamoDB Streams Kinesis untuk memproses catatan aliran](Streams.KCLAdapter.md)
+ [API tingkat rendah DynamoDB Streams: Contoh Java](Streams.LowLevel.Walkthrough.md)
+ [DynamoDB Streams dan pemicu AWS Lambda](Streams.Lambda.md)
+ [DynamoDB Streams dan Apache Flink](StreamsApacheFlink.xml.md)
## Titik akhir untuk DynamoDB Streams
AWS mempertahankan endpoint terpisah untuk DynamoDB dan DynamoDB Streams. Untuk bekerja dengan tabel dan indeks basis data, aplikasi Anda harus mengakses titik akhir DynamoDB. Untuk membaca dan memproses catatan DynamoDB Streams, aplikasi Anda harus mengakses titik akhir DynamoDB Streams di Wilayah yang sama.
DynamoDB Streams menawarkan dua set endpoint. File tersebut adalah:
+ **IPv4-only endpoint: Titik** akhir dengan konvensi `streams.dynamodb..amazonaws.com` penamaan.
+ **Dual-stack endpoint**: Endpoint baru yang kompatibel dengan keduanya IPv4 dan IPv6 dan mengikuti konvensi penamaan. `streams-dynamodb..api.aws`
**catatan**
Untuk daftar lengkap Wilayah dan titik akhir DynamoDB dan DynamoDB Streams, lihat [Wilayah dan titik akhir](https://docs.aws.amazon.com/general/latest/gr/rande.html) di *Referensi Umum AWS*.
AWS SDKs Menyediakan klien terpisah untuk DynamoDB dan DynamoDB Streams. Bergantung pada kebutuhan Anda, aplikasi Anda dapat mengakses titik akhir DynamoDB, titik akhir DynamoDB Streams, atau keduanya secara bersamaan. Untuk terhubung ke kedua titik akhir, aplikasi Anda harus membuat instance dua klien—satu untuk DynamoDB dan satu lagi untuk DynamoDB Streams.
## Mengaktifkan aliran
Anda dapat mengaktifkan aliran pada tabel baru saat Anda membuatnya menggunakan AWS CLI atau salah satu tabel AWS SDKs. Anda juga dapat mengaktifkan atau menonaktifkan aliran pada tabel yang sudah ada, atau mengubah pengaturan aliran. DynamoDB Streams beroperasi secara asinkron, sehingga tidak ada dampak kinerja pada tabel jika Anda mengaktifkan aliran.
Cara termudah untuk mengelola DynamoDB Streams adalah dengan menggunakan Konsol Manajemen AWS.
1. Masuk ke Konsol Manajemen AWS dan buka konsol DynamoDB di. [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)
1. Pada dasbor konsol DynamoDB, pilih **Tabel** dan pilih tabel yang ada.
1. Pilih tab **Ekspor dan aliran**.
1. **Di bagian detail **aliran DynamoDB**, pilih Aktifkan.**
1. Pada halaman Aliran **DynamoDB**, pilih informasi yang akan ditulis ke aliran setiap kali data dalam tabel diubah:
+ **Atribut kunci saja** — Hanya atribut kunci dari item yang dimodifikasi.
+ **Gambar baru** — Seluruh item, saat muncul setelah diubah.
+ **Gambar lama** — Seluruh item, saat muncul sebelum diubah.
+ **Gambar baru dan lama** — Baik gambar baru dan lama dari item.
Ketika pengaturan seperti yang Anda inginkan, pilih **Aktifkan aliran**.
1. (Opsional) Untuk menonaktifkan aliran yang ada, pilih **Matikan di bawah detail** aliran **DynamoDB**.
Anda juga dapat menggunakan operasi `CreateTable` atau `UpdateTable` API untuk mengaktifkan atau memodifikasi aliran. Parameter `StreamSpecification` menentukan bagaimana aliran dikonfigurasi:
+ `StreamEnabled` — Menentukan apakah stream diaktifkan (`true`) atau dinonaktifkan (`false`) untuk tabel.
+ `StreamViewType` — Menentukan informasi yang akan ditulis ke stream setiap kali data dalam tabel dimodifikasi:
+ `KEYS_ONLY` — Hanya atribut kunci dari item yang dimodifikasi.
+ `NEW_IMAGE` — Keseluruhan item, seperti yang muncul setelah diubah.
+ `OLD_IMAGE` — Keseluruhan item, seperti yang terlihat sebelum diubah.
+ `NEW_AND_OLD_IMAGES` — Baik gambar baru dan lama dari item.
Anda dapat mengaktifkan atau menonaktifkan stream kapan saja. Namun, Anda menerima `ValidationException` jika Anda mencoba untuk mengaktifkan stream pada tabel yang sudah memiliki stream. Anda juga menerima `ValidationException` jika Anda mencoba menonaktifkan aliran pada tabel yang tidak memiliki aliran.
Ketika Anda mengatur `StreamEnabled` ke `true`, DynamoDB menciptakan stream baru dengan deskriptor stream unik yang ditugaskan untuk itu. Jika Anda menonaktifkan dan kemudian mengaktifkan kembali stream pada tabel, stream baru dibuat dengan deskriptor stream yang berbeda.
Setiap stream diidentifikasi secara unik oleh Amazon Resource Name (ARN). Berikut ini adalah contoh ARN untuk stream pada tabel DynamoDB bernama `TestTable`.
```
arn:aws:dynamodb:us-west-2:111122223333:table/TestTable/stream/2015-05-11T21:21:33.291
```
Untuk menentukan deskriptor stream terbaru untuk tabel, terbitkan permintaan `DescribeTable` DynamoDB dan cari elemen `LatestStreamArn` dalam respons.
**catatan**
Hal ini tidak mungkin untuk mengedit `StreamViewType` setelah stream telah diatur. Jika Anda perlu melakukan perubahan pada stream setelah pengaturan, Anda harus menonaktifkan stream saat ini dan membuat yang baru.
## Membaca dan memproses aliran
Untuk membaca dan memproses aliran, aplikasi Anda harus terhubung ke titik akhir DynamoDB Streams dan menerbitkan permintaan API.
Stream terdiri dari *catatan aliran*. Setiap catatan stream mewakili modifikasi data tunggal dalam tabel DynamoDB di mana aliran berada. Setiap catatan stream ditugaskan nomor urut, mencerminkan urutan catatan diterbitkan ke aliran.
Rekaman streaming disusun ke dalam grup, atau *serpihan*. Setiap serpihan bertindak sebagai kontainer untuk beberapa catatan aliran, dan berisi informasi yang diperlukan untuk mengakses dan iterasi melalui catatan-catatan ini. Catatan stream dalam serpihan dihapus secara otomatis setelah 24 jam.
Serpihan bersifat fana: Mereka dibuat dan dihapus secara otomatis, sesuai kebutuhan. Setiap serpihan juga dapat dibagi menjadi beberapa serpihan baru; ini juga terjadi secara otomatis. (Pecahan induk juga mungkin hanya memiliki satu pecahan turunan.) Sebuah pecahan mungkin terpecah sebagai respons terhadap aktivitas tulis tingkat tinggi pada tabel induknya, sehingga aplikasi dapat memproses rekaman dari beberapa pecahan secara paralel.
Jika Anda menonaktifkan aliran, semua pecahan yang terbuka akan ditutup. Data dalam aliran akan terus dapat dibaca selama 24 jam.
Karena serpihan memiliki garis keturunan (induk dan turunan), aplikasi harus selalu memproses serpihan induk sebelum memproses serpihan anak. Hal ini membantu memastikan bahwa rekaman aliran juga diproses dalam urutan yang benar. (Jika Anda menggunakan DynamoDB Streams Kinesis Adapter, hal ini akan ditangani untuk Anda. Aplikasi Anda memproses pecahan dan catatan aliran dalam urutan yang benar. Secara otomatis menangani pecahan baru atau yang sudah habis masa berlakunya, selain pecahan yang terpecah saat aplikasi berjalan. Misalnya informasi lebih lanjut, lihat [Menggunakan adaptor DynamoDB Streams Kinesis untuk memproses catatan aliran](Streams.KCLAdapter.md).)
Diagram berikut menunjukkan hubungan antara aliran, serpihan dalam aliran, dan rekaman aliran dalam serpihan.
![\[Struktur DynamoDB Streams. Catatan aliran yang mewakili modifikasi data diatur ke dalam pecahan.\]](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/images/streams-terminology.png)
**catatan**
Jika Anda melakukan operasi `PutItem` atau `UpdateItem` yang tidak mengubah data dalam item, DynamoDB Streams *tidak* menulis catatan stream untuk operasi itu.
Untuk mengakses aliran dan memproses rekaman aliran di dalamnya, Anda harus melakukan hal berikut:
+ Tentukan ARN unik aliran yang ingin Anda akses.
+ Tentukan pecahan mana dalam aliran yang berisi rekaman aliran yang Anda minati.
+ Akses pecahan dan ambil rekaman aliran yang Anda inginkan.
**catatan**
Maksimum dua proses harus membaca dari pecahan aliran yang sama pada waktu yang sama. Memiliki lebih dari dua pembaca per shard dapat mengakibatkan throttling.
DynamoDB Streams API menyediakan tindakan berikut untuk digunakan oleh program aplikasi:
+ `[ListStreams](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_ListStreams.html)` — Mengembalikan daftar deskriptor stream untuk akun dan titik akhir saat ini. Anda secara opsional dapat meminta hanya deskriptor stream untuk nama tabel tertentu.
+ `[DescribeStream](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_DescribeStream.html)`— Mengembalikan informasi tentang aliran, termasuk status aliran saat ini, Nama Sumber Daya Amazon (ARN), komposisi pecahannya, dan tabel DynamoDB yang sesuai. Anda dapat menggunakan `ShardFilter` bidang ini secara opsional untuk mengambil pecahan anak yang ada yang terkait dengan pecahan induk.
+ `[GetShardIterator](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetShardIterator.html)` — Mengembalikan *iterator serpihan*, yang menggambarkan lokasi di dalam serpihan. Anda dapat meminta iterator yang menyediakan akses ke titik terlama, titik terbaru, atau titik tertentu dalam serpihan.
+ `[GetRecords](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetRecords.html)` - Mengembalikan catatan aliran dari dalam serpihan yang diberikan. Anda harus memberikan iterator serpihan yang dikembalikan dari permintaan `GetShardIterator`.
Untuk deskripsi lengkap operasi API ini, termasuk contoh permintaan dan tanggapan, lihat [Referensi API Amazon DynamoDB Streams](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Operations_Amazon_DynamoDB_Streams.html).
### Penemuan pecahan
Temukan pecahan baru di aliran DynamoDB Anda dengan dua metode canggih. Sebagai pengguna Amazon DynamoDB Streams, Anda memiliki dua cara efektif untuk melacak dan mengidentifikasi pecahan baru:
**Polling seluruh topologi aliran**
Gunakan `DescribeStream` API untuk melakukan polling streaming secara teratur. Ini mengembalikan semua pecahan dalam aliran, termasuk pecahan baru yang telah dibuat. Dengan membandingkan hasil dari waktu ke waktu, Anda dapat mendeteksi pecahan yang baru ditambahkan.
**Menemukan pecahan anak**
Gunakan `DescribeStream` API dengan `ShardFilter` parameter untuk menemukan subset pecahan. Dengan menentukan pecahan induk dalam permintaan, DynamoDB Streams akan mengembalikan pecahan turunan langsungnya. Pendekatan ini berguna ketika Anda hanya perlu melacak garis keturunan pecahan tanpa memindai seluruh aliran.
Aplikasi yang mengkonsumsi data dari DynamoDB Streams dapat secara efisien bertransisi dari membaca pecahan tertutup ke pecahan turunannya menggunakan parameter `ShardFilter` ini, menghindari panggilan berulang ke API untuk mengambil dan melintasi `DescribeStream` peta pecahan untuk semua pecahan tertutup dan terbuka. Ini membantu menemukan pecahan anak dengan cepat setelah pecahan induk ditutup, membuat aplikasi pemrosesan aliran Anda lebih responsif dan hemat biaya.
Kedua metode memberdayakan Anda untuk tetap berada di atas struktur DynamoDB Streams yang berkembang, memastikan Anda tidak pernah melewatkan pembaruan data penting atau modifikasi pecahan.
### Batas retensi data untuk DynamoDB Streams
Semua data dalam DynamoDB Streams tunduk pada masa hidup 24 jam. Anda dapat mengambil dan menganalisis 24 jam terakhir aktivitas untuk setiap tabel yang ditentukan. Namun, data yang lebih lama dari 24 jam rentan terhadap pemangkasan (penghapusan) setiap saat.
Jika Anda menonaktifkan stream pada tabel, data di stream terus dapat dibaca selama 24 jam. Setelah waktu ini, data kedaluwarsa dan catatan stream secara otomatis dihapus. Tidak ada mekanisme untuk menghapus stream yang ada secara manual. Anda harus menunggu hingga batas retensi berakhir (24 jam), dan semua catatan stream akan dihapus.
# DynamoDB Streams dan Waktu untuk Tayang
Anda dapat mencadangkan, atau memproses, item yang dihapus oleh [Waktu untuk Tayang](TTL.md) (TTL) dengan mengaktifkan Amazon DynamoDB Stream pada tabel dan memproses catatan stream dari item yang kedaluwarsa. Untuk informasi selengkapnya, lihat [Membaca dan memproses aliran](Streams.md#Streams.Processing).
Catatan stream berisi bidang identitas pengguna `Records[].userIdentity`.
Item yang dihapus oleh proses Waktu untuk Tayang setelah kedaluwarsa memiliki bidang berikut:
+ `Records[].userIdentity.type`
`"Service"`
+ `Records[