AWS CLI ile DynamoDB GSI Sorgulama

Bir global ikincil indeksi sorgulamak, sıradan bir aws dynamodb query artı tek bir bayraktır: --index-name. Anahtar koşulu o zaman tablonun değil indeksin anahtarlarını hedefler — burada AlbumTitle-index, temel tablonun (Artist + SongTitle) bir tarama olmadan karşılayamayacağı bir erişim deseni olan, şarkıları albüme göre getirmemizi sağlar.

Kod

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"}}'

Çıktı, DynamoDB JSON biçiminde eşleşen öğelerdir:

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

Açıklama

Bu sorgu için temel tabloya hiçbir şey faturalanmaz. --return-consumed-capacity INDEXES ekleyin; ayrım açıkça görünür:

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

Tabloya karşı sıfır, indekse karşı her şey. Bir GSI, kendi anahtar şeması, kendi bölümleri ve kendi kapasitesi olan ayrı bir tablodur ve onu okumak temel tabloya asla dokunmaz. Bir GSI'nin kendi kısıtlama hikâyesinin olmasının nedeni de budur: okumalar hiçbir zaman karşıya geçmese bile kısıtlanan bir GSI temel tablo yazmalarını kısıtlayabilir.

--consistent-read düşürülmez, reddedilir. GSI'ler eşzamansız olarak çoğaltılır ve bunu değiştiren bir bayrak yoktur:

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

Çıkış kodu 254. API referansı aynı şeyi önceden söylüyor: "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" (2026-07-28 tarihinde alındı). Yerel ikincil indeksler bunu kabul eder; bu da bir LSI seçmenin az sayıdaki gerçek nedeninden biridir. Gecikmenin kendisi GSI'ler neden nihai tutarlıdır sayfasında ele alınıyor.

İndeks anahtarı olmayan öğeler indekste hiç yer almaz. Aynı tabloda sayıldı: temel tabloda 35 öğe, AlbumTitle-index'te 32. Eksik olan üçünde hiç AlbumTitle özniteliği yok; bu, attribute_not_exists(AlbumTitle) üzerinde bir taramayla doğrulandı. Hiçbir şey hata vermedi, hiçbir şey uyarmadı. Bu, seyrek indeks desenidir; bayrak özniteliğini yalnızca indekslenmesini istediğiniz satırlar için yazdığınızda kasıtlı bir tasarım, indeksin tabloyu yansıttığını varsaydığınızda ise sessiz bir veri kaybı hatasıdır.

Yalnızca indeksin yansıttığı şeyi alırsınız. "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" (2026-07-28 tarihinde alındı). KEYS_ONLY ya da INCLUDE bir indekste bu, geri kalanı doldurmak için sonuç başına ikinci bir get-item demektir — yani kaçınmaya çalıştığınız N+1. Yansıtma, indeks oluşturulduğunda sabitlenir ve sonradan değiştirilemez; birini seçmeden önce indeks yansıtmaları sayfasına bakın.

İndeks anahtarları benzersiz değildir. Birçok öğe tek bir AlbumTitle'ı paylaşabilir; dolayısıyla bir GSI sorgusu, eşdeğer tablo sorgusunun tek bir öğe döndüreceği yerde bir koleksiyon döndürür. Tam da bu nedenle bir GSI'ye karşı get-item diye bir şey yoktur.

Sayfalama, herhangi bir tablo sorgusundaki gibi davranır, CLI'nin otomatik sayfalanmış bir sonuç için tek bir sayfanın ConsumedCapacity'sini bildirme alışkanlığı dahil. Bu, AWS CLI ile Query sayfasında ayrıntılı olarak ölçülüyor; bayraklar burada da aynıdır.

Görsel olarak yapın

Bir indeks sorgusunun bir tablo sorgusundan daha çok hareketli parçası vardır: doğru indeks, indeksin kendi anahtar adları ve ihtiyacınız olan öznitelikleri taşımayabilecek bir yansıtma. Ücretsiz DynamoDB Query Builder indeksi seçmenizi sağlar, anahtar koşulunu onun anahtarlarına karşı kurar ve CLI komutunu üretir.

Bir tablonun gerçekte hangi indekslere sahip olduğunu görmek ve onları kendi verinize karşı sorgulamak — yansıtmalar listelenmiş, kaydırdıkça sayfalayan bir ızgara, isteği bir CLI komutu olarak geri kopyalama — için DynoTable'ı indirin.

İlgili örnekler

• Node.js'te DynamoDB GSI Sorgulama — AWS SDK v3 ile aynı indeks sorgusu.
• Python'da DynamoDB GSI Sorgulama — boto3 ile aynı indeks sorgusu.
• GSI ile LSI karşılaştırması — erişim desenine hangi indeks türü uyar.
• "The table does not have the specified index" — indeks adı uyuşmuyor (GSI adları büyük/küçük harfe duyarlıdır).
• "Consistent reads are not supported on global secondary indexes" — tutarlı okuma bayrağı bir GSI'de neden başarısız olur.

Kaynaklar

• Query — Amazon DynamoDB API Reference
• query — AWS CLI Command Reference
• Using Global Secondary Indexes in DynamoDB — Amazon DynamoDB Developer Guide
• Using AWS CLI pagination options — AWS CLI User Guide

2026-07-28 tarihinde aws-cli/2.36.9 ile 9000 numaralı bağlantı noktasındaki DynamoDB Local'a (amazon/dynamodb-local) karşı, ALL yansıtan bir AlbumTitle-index'e sahip bir Music tablosunda yeniden üretildi. Hata metni, kapasite ayrımı ve öğe sayıları yakalanan çıktıdır.