Query GSI DynamoDB dengan AWS CLI

Melakukan query pada global secondary index adalah aws dynamodb query biasa plus satu flag: --index-name. Kondisi key-nya lalu menyasar key milik index, bukan milik tabel — di sini AlbumTitle-index memungkinkan kita mengambil lagu berdasarkan album, sebuah pola akses yang tak bisa dilayani tabel dasar (Artist + SongTitle) tanpa scan.

Kode

aws dynamodb query \
  --table-name 'Music' \
  --index-name 'AlbumTitle-index' \
  --key-condition-expression '#hashKey = :hashKeyValue' \
  --expression-attribute-names '{"#hashKey":"AlbumTitle"}' \
  --expression-attribute-values '{":hashKeyValue":{"S":"Danzon"}}'

Keluarannya adalah item yang cocok dalam DynamoDB JSON:

{
    "Items": [
        {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, ...}
    ],
    "Count": 2,
    "ScannedCount": 2
}

Penjelasan

Tabel dasar sama sekali tidak ditagih untuk query ini. Tambahkan --return-consumed-capacity INDEXES dan pembagiannya jadi eksplisit:

"ConsumedCapacity": {
    "CapacityUnits": 132.0,
    "Table": {"CapacityUnits": 0.0},
    "GlobalSecondaryIndexes": {"AlbumTitle-index": {"CapacityUnits": 132.0}}
}

Nol terhadap tabel, semuanya terhadap index. GSI adalah tabel terpisah dengan key schema sendiri, partisi sendiri, dan kapasitas sendiri, dan membacanya tak pernah menyentuh tabel dasar. Itu juga sebabnya GSI punya kisah throttling-nya sendiri: GSI yang di-throttle bisa men-throttle penulisan tabel dasar meski pembacaannya tak pernah menyeberang.

--consistent-read ditolak, bukan diturunkan. GSI direplikasi secara asinkron dan tidak ada flag yang mengubahnya:

aws: [ERROR]: An error occurred (ValidationException) when calling the Query operation: Consistent reads are not supported on global secondary indexes

Kode keluar 254. Referensi API sudah menyebutkan hal yang sama di muka: "Strongly consistent reads are not supported on global secondary indexes. If you query a global secondary index with ConsistentRead set to true, you will receive a ValidationException" (diambil 2026-07-28). Local secondary index memang menerimanya, dan itu salah satu dari sedikit alasan nyata untuk memilih LSI. Jeda waktunya sendiri dibahas di mengapa GSI bersifat eventually consistent.

Item tanpa key index sekadar tidak ada di dalam index. Dihitung pada tabel yang sama: 35 item di tabel dasar, 32 di AlbumTitle-index. Tiga yang hilang itu sama sekali tidak punya atribut AlbumTitle, dikonfirmasi dengan scan pada attribute_not_exists(AlbumTitle). Tidak ada yang error dan tidak ada yang memperingatkan. Ini adalah pola sparse index, dan ia merupakan desain yang disengaja ketika Anda menulis atribut penandanya hanya untuk baris yang ingin Anda indeks, sekaligus bug kehilangan data yang senyap ketika Anda mengasumsikan index mencerminkan tabel.

Anda hanya mendapat apa yang diproyeksikan index. "If you query or scan a global secondary index, you can only request attributes that are projected into the index. Global secondary index queries cannot fetch attributes from the parent table" (diambil 2026-07-28). Pada index KEYS_ONLY atau INCLUDE itu berarti satu get-item tambahan per hasil untuk melengkapi sisanya, yang justru merupakan N+1 yang ingin Anda hindari. Proyeksinya dikunci saat index dibuat dan tidak bisa diubah setelahnya; lihat projeksi index sebelum Anda memilih.

Key index tidak unik. Banyak item bisa berbagi satu AlbumTitle, jadi query GSI mengembalikan sekumpulan hasil di tempat query tabel yang setara akan mengembalikan satu item. Tidak ada yang namanya get-item terhadap GSI, tepat karena alasan ini.

Paginasi berperilaku sama seperti pada query tabel mana pun, termasuk kebiasaan CLI melaporkan ConsumedCapacity satu halaman untuk hasil yang dipaginasi otomatis. Itu diukur secara rinci di Query dengan AWS CLI; flag-nya sama di sini.

Lakukan secara visual

Query index punya lebih banyak bagian bergerak daripada query tabel: index yang tepat, nama key milik index itu sendiri, dan proyeksi yang mungkin tidak membawa atribut yang Anda butuhkan. DynamoDB Query Builder gratis memungkinkan Anda memilih index-nya, membangun kondisi key terhadap key-nya, dan memancarkan perintah CLI-nya.

Untuk melihat index apa saja yang sebenarnya dimiliki sebuah tabel dan melakukan query terhadap data Anda sendiri — proyeksi terdaftar, grid yang memuat halaman sambil Anda menggulir, salin kembali permintaannya sebagai perintah CLI — unduh DynoTable.

Contoh terkait

Query GSI DynamoDB di Node.js — query index yang sama dengan AWS SDK v3.
Query GSI DynamoDB di Python — query index yang sama dengan boto3.
GSI vs. LSI — tipe index mana yang cocok untuk pola aksesnya.
"The table does not have the specified index" — nama index-nya tidak cocok (nama GSI bersifat case-sensitive).
"Consistent reads are not supported on global secondary indexes" — mengapa flag consistent-read gagal pada GSI.

Referensi

Direproduksi 2026-07-28 dengan aws-cli/2.36.9 terhadap DynamoDB Local (amazon/dynamodb-local) di port 9000, pada tabel Music dengan AlbumTitle-index yang memproyeksikan ALL. Teks error, pembagian kapasitas, dan jumlah item-nya adalah keluaran yang ditangkap.