DynamoDB Query dengan AWS CLI

aws dynamodb query membaca satu partisi, secara opsional dipersempit oleh sort key (Query vs Scan membahas kapan itu pilihan yang tepat, dan key condition expression mendaftar setiap operator yang sah). Yang ditambahkan CLI di atasnya adalah lapisan paginasinya sendiri, dan itulah sumber sebagian besar kejutan pada perintah ini.

Kode

aws dynamodb query \
  --table-name 'Music' \
  --key-condition-expression '#hashKey = :hashKeyValue AND begins_with(#rangeKey, :rangeKeyValue)' \
  --expression-attribute-names '{"#hashKey":"Artist","#rangeKey":"SongTitle"}' \
  --expression-attribute-values '{":hashKeyValue":{"S":"Arturo Sandoval"},":rangeKeyValue":{"S":"C"}}'

Alias #hashKey/#rangeKey di-resolve menjadi Artist/SongTitle lewat --expression-attribute-names, dan itulah yang menjaga sebuah reserved word agar tidak merusak perintahnya. Tambahkan --no-scan-index-forward untuk urutan sort key menurun; menaik adalah default-nya.

Paginasi

Secara default CLI melakukan paginasi otomatis — ia mengikuti LastEvaluatedKey secara internal dan mencetak hasil gabungannya. Untuk memaginasi secara manual (misalnya untuk set hasil besar), kendalikan dengan:

aws dynamodb query \
  --table-name 'Music' \
  --key-condition-expression '#hashKey = :hashKeyValue' \
  --expression-attribute-names '{"#hashKey":"Artist"}' \
  --expression-attribute-values '{":hashKeyValue":{"S":"Arturo Sandoval"}}' \
  --page-size 100 \
  --max-items 50
# The output includes a "NextToken"; pass it back with --starting-token to continue.

Penjelasan

CLI menyembunyikan paginasinya, termasuk dari angka biayanya. Sebuah partisi diisi 30 item berukuran ~60 KB masing-masing, sekitar 1,8 MB dan karenanya dua halaman layanan, lalu query yang sama dijalankan dengan tiga cara memakai --return-consumed-capacity TOTAL:

default (auto-paginate)  Count: 30   CapacityUnits: 132.0   LastEvaluatedKey: null
--no-paginate            Count: 18   CapacityUnits: 132.0   LastEvaluatedKey: {…S017}
--max-items 3            Count: 18   items printed: 3       NextToken: eyJFeGNsdXNpdmVTdGFydEtleSI6…

Memaginasi dengan tangan menunjukkan biaya sebenarnya: halaman 1 berisi 18 item seharga 132,0 unit, halaman 2 berisi 12 item seharga 88,0, jadi query itu sesungguhnya menghabiskan 220,0 unit baca. Jalannya yang dipaginasi otomatis melakukan kedua panggilan, mengembalikan seluruh 30 item, dan melaporkan 132,0. CLI menggabungkan Items dan Count lintas halaman tetapi tidak ConsumedCapacity, jadi angka yang dicetak memandang query ini 40% lebih rendah dari kenyataan. Kalau Anda menakar kapasitas dari keluaran CLI, paginasilah secara manual atau Anda akan menakar untuk satu halaman saja.

--max-items adalah batas pencetakan. Ia bukan Limit. Jalan ketiga di atas mencetak tiga item dan tetap melaporkan Count: 18 serta ScannedCount: 18, karena halaman layanan yang ia pangkas berisi 18 item dan kira-kira 1 MB. Anda membayar semuanya. Parameter DynamoDB yang benar-benar membatasi pembacaan adalah Limit, dan CLI memaparkannya sebagai --page-size.

Jadi kedua flag itu mengerjakan tugas yang tak berkaitan. --page-size menjadi Limit milik API dan mengubah apa yang dibaca setiap panggilan layanan; --max-items hanya menentukan seberapa banyak hasil gabungan yang sampai ke terminal Anda, dan memancarkan sebuah NextToken untuk sisanya. Token itu adalah blob base64 dari pembukuan CLI sendiri, bukan LastEvaluatedKey milik DynamoDB, dan ia dimasukkan kembali lewat --starting-token.

Tidak ada --limit dan tidak ada --exclusive-start-key. Periksa aws dynamodb query help pada 2.36.9 dan tak satu pun muncul di sinopsisnya: CLI menghapus kedua parameter paginasi DynamoDB dan menggantinya dengan tiga miliknya sendiri. Jadi loop alaminya — ambil LastEvaluatedKey dari satu panggilan lalu suapkan ke panggilan berikutnya — tidak punya flag untuk disuapi. Jalan kembali ke API mentahnya adalah --cli-input-json, yang menerima request apa adanya:

--cli-input-json with "Limit": 5 and an "ExclusiveStartKey"
  → Count: 5   CapacityUnits: 37.0   LastEvaluatedKey: {"Artist":…,"SongTitle":"S007"}

Perhatikan bahwa ini juga mematikan paginator-nya: jalannya mengembalikan satu halaman dan sebuah LastEvaluatedKey sungguhan bahkan tanpa --no-paginate. Kalau Anda menulis loop shell atas partisi besar, --cli-input-json adalah bentuk yang jujur, dan --no-paginate adalah yang cepat.

--query berjalan setelah uangnya terlanjur keluar. Flag global --query adalah JMESPath yang diterapkan pada response di shell Anda. Expression JMESPath seperti Items[?Year > '2010'] tampak seperti filter padahal bukan: setiap item sudah dibaca, ditransfer, dan ditagih sebelum JMESPath melihatnya. --filter-expression setidaknya menghentikan data ditransfer, tetapi AWS menyatakannya secara eksplisit: ia "is applied after the items have already been read; the process of filtering does not consume any additional read capacity units" (diambil 2026-07-28). Itu berlaku dua arah, karena artinya filter juga tidak menguranginya. Satu-satunya cara membaca lebih sedikit adalah key condition yang lebih sempit atau sebuah index.

Satu halaman berukuran 1 MB, terlepas dari apa yang Anda minta. "A single Query operation will read up to the maximum number of items set (if using the Limit parameter) or a maximum of 1 MB of data" (diambil 2026-07-28). Partisi yang lebih lebar dari itu selalu dipaginasi, itulah sebabnya query 30 item di atas tak pernah berupa satu panggilan.

Melakukan query pada sebuah index butuh satu flag lagi. --index-name mengalihkan key condition ke key milik index tersebut; global secondary index juga menolak --consistent-read. Lihat Query sebuah GSI dengan AWS CLI.

Lakukan secara visual

Menyusun key condition, dua map placeholder, dan loop paginasi dengan benar dalam satu perintah adalah seluruh kesulitannya di sini. DynamoDB Query Builder gratis menyusun request-nya, termasuk index dan paginasinya, lalu memancarkannya sebagai perintah CLI yang bisa dijalankan.

Untuk menjalankan query pada tabel Anda sendiri — form key-condition, grid yang memaginasi sambil Anda menggulir, salin request-nya kembali sebagai perintah CLI — unduh DynoTable.

Panduan terkait

Query vs. Scan — mengapa query adalah default yang tepat.
Paginasi — LastEvaluatedKey, ExclusiveStartKey, dan mengapa Limit bukan ukuran halaman.
"Query condition missed key schema element" — key condition menyebut atribut yang salah atau melewatkan partition key.
"Query key condition not supported" — operator yang tidak bisa dipakai key condition, seperti contains atau kondisi sort key kedua.

Referensi

Diukur 2026-07-28 dengan aws-cli/2.36.9 terhadap DynamoDB Local (amazon/dynamodb-local) pada port 9000, atas sebuah partisi berisi 30 item berukuran ~60 KB masing-masing. Hitungan, token, dan pembacaan kapasitas di atas adalah keluaran yang ditangkap apa adanya. DynamoDB Local menghitung kapasitas dengan aturan pembulatan yang terdokumentasi; anggap angka absolutnya sebagai peragaan bentuknya saja, dan ukur tabel Anda sendiri terhadap layanan sebelum menakar kapasitas.