Mendeteksi dan memperbaiki pelanggaran kunci indeks di DynamoDB - Amazon DynamoDB
Mengunduh dan menjalankan Detektor PelanggaranFile konfigurasi Detektor PelanggaranDeteksiKoreksi

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

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.

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.

  • -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 tempat 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.

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 muncul dalam CSV format. 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 CSV format. 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.

  • GSInilai kunci hash - Nilai kunci partisi dari indeks sekunder global.

  • GSIjenis pelanggaran kunci hash — Entah Type Violation atauSize Violation.

  • GSIdeskripsi pelanggaran kunci hash — Penyebab pelanggaran.

  • GSIhash key update Value (FORUSER) - Dalam mode koreksi, nilai yang disediakan pengguna baru untuk atribut.

  • GSIRange key value — Nilai kunci sortir dari indeks sekunder global.

  • GSIberbagai jenis pelanggaran kunci — Entah Type Violation atauSize Violation.

  • GSIdeskripsi pelanggaran kunci jangkauan — Penyebab pelanggaran.

  • GSIRange key update Value (FORUSER) - Dalam mode koreksi, nilai baru yang disediakan pengguna untuk atribut.

  • 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.