Bir DynamoDB GSI neden base-table yazmalarını kısıtlar

Tablona yazıyorsun. Yazma bir throughput exception ile düşüyor — ama exception Global Secondary Index'i adlandırıyor, tabloyu değil. Tablonun boş kapasitesi var.

SQL'den geliyorsan bu saçma: ikincil bir indeks bir INSERT'i engelleyemez. DynamoDB'de engelleyebilir ve mekanizmanın adı GSI back-pressure.

Bir DynamoDB GSI neden base-table yazmalarını kısıtlar?

DynamoDB base-table yazmasını kısıtlar çünkü her yazma her GSI'ye de kopyalanır ve bir GSI partition'ı kendi payını ememezse DynamoDB indeksin kalıcı olarak geride kalmasını durdurmak için back-pressure uygular. Yani yetersiz provision edilmiş veya düşük kardinaliteli bir GSI anahtarı, base-table yazma hızın üzerinde sert bir tavan olur.

• Base table'a yazmak her GSI'ye de yazar. Bir GSI payını ememezse DynamoDB indeksin kalıcı geride kalmasını önlemek için base-table yazmasını kısıtlar. (AWS docs)
• Dengeli bir base table seni kurtarmaz. GSI kendi anahtarına göre partition'lanır. Düşük kardinaliteli bir GSI anahtarı (status gibi), base-table yazmaları mükemmel dağılsa bile bir sıcak indeks partition'ı yaratır.
• Exception kurban hakkında yalan söyler. ResourceArn GSI'yi gösterir; gerçekte kısıtlanan işlem tablona yazmandır.
• Çözüm kapasite veya anahtar tasarımıdır, retry döngüleri değil — GSI throughput'unu yükselt veya yayılan bir GSI partition key seç.

Tek bir yazma indekse nasıl dokunur

Base table üzerinde bir PutItem tek bir yazma değildir. DynamoDB öğenin project edilmiş attribute'larını her GSI'ye asenkron, nihai tutarlı bir modelle çoğaltır. Bir mantıksal yazma N fiziksel yazmaya yayılır — tablo artı her indeks.

Bu çoğaltma bedava değildir ve isteğe bağlı değildir. GSI ayak uydurmalıdır, yoksa indeks her işlemde tablodan daha fazla sapar.

Bu sapmayı durdurmak için DynamoDB back-pressure uygular: kaynak yazmayı kısıtlar ki indeks sınırsız bayatlamasın.

Yani GSI'nin yazma kapasitesi, GSI'ye hiç doğrudan yazmasan bile, base-table yazma hızın üzerinde sert bir tavandır.

İşlenmiş örnek: bir sipariş tablosu

Diyelim bir sipariş tablosu çalıştırıyorsun. Base öğe:

Base-table yazmaları sağlıklıdır. CUST#... yüksek kardinalitelidir, sipariş yazmaları base partition'lara eşit dağılır. Sıcak anahtar yok, bol kapasite.

Şimdi "verilen bir durumdaki her siparişi göster" diye yanıtlayan bir GSI ekliyorsun:

Dört olası partition-key değeri. Flash sale sırasında neredeyse her yeni sipariş order_state = "PENDING"'e düşer. Bu yazmaların hepsi aynı GSI partition'ına çarpar.

O partition'ın partition başına throughput limiti vardır ve tüm yazma fırtınanı ona nişan aldın.

Base table iyidir. PENDING GSI partition'ı yanıyordur. DynamoDB indeksi korumak için base-table PutItem'ını kısıtlar.

Seni ısıran akış

Back-pressure yolu — base yazma dengeli, indeks yazması yoğunlaşmış:

Sıcak bir GSI partition, onu besleyen base-table yazmasını reddeder.

Bağırsaklarına değil, exception'a bak

Exception tipi tam olarak hangi tavana çarptığını söyler. ResourceArn GSI'yi adlandırır; kısıtlanan op hâlâ tablo yazmasıdır.

Kaynak: Understanding GSI write throttling and back pressure.

KeyRange reason'ı yukarıdaki sıcak-partition durumunun ihbarıdır: genel GSI kapasitesi iyi görünebilirken bir key range doymuştur.

Nasıl düzeltilir

GSI'ye yer ver. En basit neden yetersiz provision etmektir. Bir GSI'nin tablodan tamamen ayrı kendi okuma ve yazma kapasitesi vardır — bak GSI vs LSI.

Tabloyu cömert provision edip GSI'yi ince bıraktıysan GSI'nin yazma kapasitesini (veya on-demand max'ını) yükselt.

Partition key'i düzelt. Kapasite düşük kardinaliteli bir anahtarı kurtarmaz — tek bir sıcak partition'ı provision ederek yenemezsin. Yayan bir GSI partition key seç.

Birleştir: shard küçük rastgele bir sonek olacak şekilde order_state#shard, veya tarihi kat (PENDING#2026-06-23). Yazmalar partition'lara yayılır ve hâlâ shard'ları sorgulayarak bir durumu Query edersin.

Daha az attribute project et. Her GSI yazması project edilmiş attribute'ları kopyalar. KEYS_ONLY veya sıkı bir INCLUDE projection, ALL'a göre daha küçük indeks yazmaları ve daha az baskı demektir. İndeksten asla okumayacağını project etme.

Yalnızca raporlama içinse GSI'yi düşür. "Duruma göre siparişler" ara sıra bir admin sorusuysa, sıcak yol değilse, periyodik filtreli bir scan kalıcı sıcak bir indeksten daha iyi olabilir — Query vs Scan karşısında tart.

O indeksi sorguladığında Expression Builder KeyConditionExpression'ı senin için yazar — örn. #s = :state AND begins_with(SK, :prefix) — adlar ve değerler doğru kaçırılmış:

KeyConditionExpression     "#s = :state AND begins_with(SK, :prefix)"
ExpressionAttributeNames   { "#s": "order_state" }
ExpressionAttributeValues  { ":state": { "S": "PENDING" }, ":prefix": { "S": "ORD#2026-06-23" } }

Hatırlanacak tuzak

İlişkisel içgüdü — "indeksler yazmaları yalnızca biraz yavaşlatır" — transfer olmaz. Bir DynamoDB GSI pasif bir yapı değil, bir throughput bağımlılığıdır. Onu küçük boyutlandır veya kümelenen bir anahtar seç; servis ettiği tabloya back-pressure uygular.

ConsumedWriteCapacityUnits ve WriteThrottleEvents'i yalnızca tablonun değil GSI boyutunda da izle ve sıcak anahtarları bulmak için Contributor Insights kullan.

Sonraki adımlar

• GSI vs LSI — bir GSI'nin neden kendi kapasitesi ve farklı bir partition key'i vardır.
• Single-table design — sıcak indeksleri çoğaltmadan birçok desene hizmet etmek için bir GSI'yi aşırı yüklemek.
• Query vs Scan — bir indeksin yazma maliyetine değmediği zamanlar.

Tablolarındaki her GSI'yi — key schema ve öğe sayıları — incelemek ve bir satış onları kırmızıya çevirmeden önce indekslerini sorgulamak için DynoTable'ı dene.