AWS CLI ile DynamoDB Query

aws dynamodb query tek bir bölümü okur, isteğe bağlı olarak sıralama anahtarıyla daraltılmış (Query ile Scan bunun ne zaman doğru tercih olduğunu, anahtar koşul ifadeleri ise her geçerli operatörü anlatır). CLI'ın üstüne eklediği şey kendi sayfalama katmanıdır ve bu komuttaki sürprizlerin çoğunun kaynağı odur.

Kod

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

#hashKey/#rangeKey takma adları --expression-attribute-names üzerinden Artist/SongTitle'a çözümlenir; komutu bir ayrılmış sözcüğün bozmasını engelleyen de budur. Azalan sıralama anahtarı sırası için --no-scan-index-forward ekleyin; varsayılan artandır.

Sayfalama

Varsayılan olarak CLI otomatik sayfalar — LastEvaluatedKey'i içeride izler ve birleştirilmiş sonucu yazdırır. Elle sayfalamak için (örneğin büyük sonuç kümelerinde) şunlarla denetleyin:

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.

Açıklama

CLI sayfalamayı saklar — maliyet rakamından da. Her biri ~60 KB olan 30 öğeyle bir bölüm dolduruldu, yaklaşık 1,8 MB ve dolayısıyla iki hizmet sayfası; sonra aynı sorgu --return-consumed-capacity TOTAL ile üç şekilde çalıştırıldı:

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…

Elle sayfalamak gerçek maliyeti gösterdi: 1. sayfa 132,0 birimde 18 öğe, 2. sayfa 88,0'de 12 öğe; yani sorgu gerçekte 220,0 okuma birimi tüketti. Otomatik sayfalanan çalıştırma her iki çağrıyı da yaptı, 30 öğenin tamamını döndürdü ve 132,0 bildirdi. CLI, Items ve Count'u sayfalar arasında birleştirir ama ConsumedCapacity'yi birleştirmez; dolayısıyla yazdırılan sayı bu sorguyu %40 eksik gösterir. Kapasiteyi CLI çıktısından boyutlandırıyorsanız elle sayfalayın, yoksa tek sayfaya göre boyutlandırırsınız.

--max-items bir yazdırma sınırıdır. Bir Limit değildir. Yukarıdaki üçüncü çalıştırma üç öğe yazdırdı ama yine Count: 18 ve ScannedCount: 18 bildirdi, çünkü kırptığı hizmet sayfası 18 öğe ve kabaca 1 MB'tı. Hepsinin parasını ödediniz. Okumayı gerçekten sınırlayan DynamoDB parametresi Limit'tir ve CLI onu --page-size olarak sunar.

Yani iki bayrak birbiriyle ilgisiz işler yapar. --page-size, API'nin Limit'i olur ve her hizmet çağrısının ne okuduğunu değiştirir; --max-items yalnızca birleştirilmiş sonucun ne kadarının terminalinize ulaşacağına karar verir ve gerisi için bir NextToken üretir. O belirteç, DynamoDB'nin LastEvaluatedKey'i değil, CLI'ın kendi defter tutmasının base64 yığınıdır ve geri --starting-token üzerinden girer.

--limit yok ve --exclusive-start-key yok. 2.36.9 üzerinde aws dynamodb query help'e bakın, ikisi de özette görünmez: CLI, DynamoDB'nin iki sayfalama parametresini de kaldırır ve yerine kendi üçünü koyar. Dolayısıyla doğal döngünün — bir çağrıdan LastEvaluatedKey'i alıp bir sonrakine vermek — onu vereceği bir bayrak yoktur. Ham API'ye dönüş yolu, isteği birebir alan --cli-input-json'dır:

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

Bunun sayfalayıcıyı da kapattığına dikkat edin: çalıştırma, --no-paginate olmadan bile tek bir sayfa ve gerçek bir LastEvaluatedKey döndürdü. Büyük bir bölüm üzerinde kabuk döngüsü yazıyorsanız dürüst biçim --cli-input-json, hızlı biçim ise --no-paginate'tir.

--query, para harcandıktan sonra çalışır. Genel --query bayrağı, yanıta kabuğunuzda uygulanan JMESPath'tir. Items[?Year > '2010'] gibi bir JMESPath ifadesi filtre gibi görünür ama değildir: JMESPath görmeden önce her öğe okundu, aktarıldı ve faturalandı. --filter-expression en azından verinin aktarılmasını durdurur, ama AWS açıkça şunu söyler: "is applied after the items have already been read; the process of filtering does not consume any additional read capacity units" (2026-07-28 tarihinde alındı). Bu iki tarafa da keser, çünkü filtrenin onları azaltmadığı anlamına da gelir. Daha az okumanın tek yolu daha dar bir anahtar koşulu ya da bir indekstir.

Bir sayfa 1 MB'tır, ne istediğinizden bağımsız olarak. "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" (2026-07-28 tarihinde alındı). Bundan geniş bir bölüm her zaman sayfalanır; yukarıdaki 30 öğelik sorgunun hiçbir zaman tek çağrı olmamasının nedeni de budur.

Bir indeksi sorgulamak bir bayrak daha ister. --index-name, anahtar koşulunu o indeksin anahtarlarına geçirir; global ikincil indeks ayrıca --consistent-read'i reddeder. Bkz. AWS CLI ile bir GSI'yı sorgulama.

Görsel olarak yapın

Anahtar koşulunu, iki yer tutucu haritasını ve sayfalama döngüsünü tek komutta doğru kurmak buradaki bütün zorluktur. Ücretsiz DynamoDB Query Builder isteği, indeks ve sayfalama dahil oluşturur ve çalıştırılabilir bir CLI komutu olarak verir.

Kendi tablolarınıza karşı sorgu çalıştırmak — anahtar koşulu formu, kaydırdıkça sayfalanan bir ızgara, isteği bir CLI komutu olarak geri kopyalama — için DynoTable'ı indirin.

İlgili kılavuzlar

Query ile Scan — query neden doğru varsayılandır.
Sayfalama — LastEvaluatedKey, ExclusiveStartKey ve Limit neden bir sayfa boyutu değildir.
"Query condition missed key schema element" — anahtar koşulu yanlış özniteliği adlandırıyor ya da bölüm anahtarını atlıyor.
"Query key condition not supported" — anahtar koşulunun kullanamayacağı bir operatör, contains ya da ikinci bir sıralama anahtarı koşulu gibi.

Kaynaklar

2026-07-28 tarihinde aws-cli/2.36.9 ile, 9000 numaralı porttaki DynamoDB Local'a (amazon/dynamodb-local) karşı, her biri ~60 KB olan 30 öğelik bir bölüm üzerinde ölçüldü. Yukarıdaki sayımlar, belirteçler ve kapasite okumaları birebir alınmıştır. DynamoDB Local kapasiteyi belgelenmiş yuvarlama kurallarıyla hesaplar; mutlak rakamları biçimin bir gösterimi sayın ve boyutlandırmadan önce kendi tablolarınızı hizmete karşı ölçün.