DynamoDB Query GSI di Python (boto3)

Mengkueri sebuah global secondary index adalah query biasa ditambah satu parameter: IndexName. Key condition kemudian menargetkan key index, bukan key tabel — di sini AlbumTitle-index memungkinkan kita mengambil lagu berdasarkan album, sebuah pola akses yang tidak bisa dilayani base table (Artist + SongTitle) tanpa scan.

Code

import boto3

client = boto3.client("dynamodb")

paginator = client.get_paginator("query")

items = []
for page in paginator.paginate(
    TableName="Music",
    IndexName="AlbumTitle-index",
    KeyConditionExpression="#hashKey = :hashKeyValue",
    ExpressionAttributeNames={"#hashKey": "AlbumTitle"},
    ExpressionAttributeValues={":hashKeyValue": {"S": "Danzon"}},
):
    items.extend(page["Items"])

print(f"Found {len(items)} songs on the album")

Penjelasan

IndexName — menyebut GSI yang dikueri (TableName tetap wajib). KeyConditionExpression menggunakan partition key index (dan sort key opsional) — AlbumTitle di sini — dengan operator yang sama seperti kueri tabel.
Hanya eventual consistency — GSI mereplikasi dari base table secara asinkron. Melewatkan ConsistentRead=True pada kueri GSI tidak meningkatkannya; ia memunculkan ValidationException. (Local secondary index mendukung strong consistency.)
Anda hanya mendapat atribut yang diproyeksikan — kueri GSI mengembalikan apa yang diproyeksikan index (ALL, KEYS_ONLY, atau atribut yang tercantum INCLUDE) dan tidak bisa mengambil sisanya dari base table. Butuh atribut yang tidak diproyeksikan? Tindak lanjuti dengan get_item pada key tabel, atau perlebar proyeksi.
Key tidak unik di GSI — banyak item bisa berbagi key index yang sama, dan item yang tidak memiliki atribut key index tidak akan muncul (itulah pola sparse-index).
Paginasi — client.get_paginator("query") mengikuti LastEvaluatedKey di setiap halaman persis seperti pada kueri tabel; setiap page membawa daftar Items.
Pada resource API, kueri yang sama adalah table.query(IndexName="AlbumTitle-index", KeyConditionExpression=Key("AlbumTitle").eq("Danzon")) dengan value Python native.

Lakukan secara visual

DynamoDB Expression Builder membangun key condition + map name/value untuk kueri index dan menyalin kode boto3 yang bisa dijalankan.

Untuk menelusuri index sebuah tabel dan menjalankan kueri GSI dari sebuah form — grid berpaginasi, copy-as-code — unduh DynoTable.

Contoh terkait

DynamoDB Query GSI di Node.js — kueri index yang sama dengan AWS SDK v3.
DynamoDB Query GSI dengan AWS CLI — kueri index yang sama dari shell.
DynamoDB Query di Python — mengkueri base table.
GSI vs. LSI — tipe index mana yang cocok dengan pola akses.
Mengapa GSI eventually consistent — lag replikasi dijelaskan.
"The table does not have the specified index" — nama index tidak cocok (nama GSI case-sensitive).
"Consistent reads are not supported on global secondary indexes" — mengapa flag consistent-read gagal pada GSI.

References

Terakhir diverifikasi 2026-07-13 terhadap dokumentasi resmi AWS yang ditautkan di atas.