DynamoDB GSI がベーステーブル書き込みをスロットルする理由
テーブルに書き込みます。その書き込みがスループット例外で失敗しますが、その例外が名指しするのはテーブルではなく グローバルセカンダリインデックス です。テーブルにはキャパシティの余裕があります。
SQL から来ると、これは意味不明です。セカンダリインデックスが INSERT をブロックするはずがありません。ところが DynamoDB ではそれが起こり、その仕組みは GSI バックプレッシャーと呼ばれます。
なぜ DynamoDB の GSI はベーステーブルの書き込みをスロットルするのか?
ベーステーブルへの書き込みは、そのキーまたは射影された属性を変更するすべての GSI にも書き込みます。ある GSI が自分の分を吸収できないと、DynamoDB はインデックスが遅れをとらないよう、ベーステーブルの書き込みをスロットルします。
その結果、プロビジョニング不足の GSI や、カーディナリティの低い GSI キーが、ベーステーブルの書き込みレートに対するハードな上限になります。
- ベーステーブルが均等でも救われません。 GSI は自身のキーでパーティション分割されます。カーディナリティの低い GSI キー(
statusのような)は、ベーステーブルへの書き込みが完璧に分散していても ホットなインデックスパーティション を生みます。 - 例外は GSI を名指ししますが、拒否された書き込みはあなたのものです。 どの GSI の上限に当たったのかは、スロットリングの理由を読んで判断します。
- GSI のキャパシティか、分散する GSI キーで直します。 リトライだけでは、同じ上限に対してさらに書き込みを積み上げるだけです。
1 回の書き込みがどうインデックスに波及するか
ベーステーブルへの PutItem は、複数回の書き込みになりえます。DynamoDB は、アイテムの射影された属性を、影響を受ける各 GSI へ、結果整合モデルで非同期に複製します。
書き込みが GSI のキー属性を設定・変更・削除するか、GSI が射影する属性を変更するとき、その GSI は影響を受けます。どちらにも触れない書き込みはその GSI に何のコストもかけず、スパースインデックスに含まれないアイテムはそこに届くこともありません。
影響を受ける各 GSI は追随し続けなければならず、さもなければインデックスは操作のたびにテーブルからさらに乖離していきます。その乖離を止めるため、DynamoDB は バックプレッシャーをかけます。つまり、元の書き込みをスロットルします。
こうして GSI の書き込みキャパシティは、たとえ GSI に直接書き込むことは決してなくても、ベーステーブルの書き込みレートに対するハードな上限になります。
具体例: サポートチケットのテーブル
サポートチケットのテーブルを運用しているとします。ベースアイテムは次のとおりです。
| field | value | note |
|---|---|---|
| PK | "ACCOUNT#8841" | partition key |
| SK | "TICKET#2026-06-23#A7" | sort key |
| ticket_state | "PENDING" | |
| queue | "billing-eu" | |
| priority | 2 |
ベーステーブルの書き込みは健全です。ACCOUNT#... はカーディナリティが高いため、チケットの書き込みはベースパーティション全体に均等に分散します。ホットキーもなく、キャパシティにも余裕があります。
ここで「指定した状態のすべてのチケットを見せて」に答えるための GSI を追加します。
| field | value | note |
|---|---|---|
| GSI-PK | ticket_state | "OPEN" | "PENDING" | "SOLVED" | "CLOSED" |
| GSI-SK | SK |
取りうるパーティションキーの値は 4 つです。障害の発生中は、ほぼすべての新規チケットが
ticket_state = "OPEN" に入ります。それらの書き込みはすべて同じ GSI パーティションに当たります。
そのパーティションにはパーティションごとのスループット上限があり、あなたは今まさに書き込みの嵐すべてをそこに向けたのです。
ベーステーブルは問題ありません。OPEN の GSI パーティションが上限を超えているので、
DynamoDB はインデックスを守るために、ベーステーブルの PutItem をスロットルします。
下のホットキーへのトラフィックを上げて、カーディナリティの低いインデックスキーが書き込みを 1 つのパーティションに流し込み、書き込み 1,000 ユニットの上限を突破するまでの様子を見てください。
あなたを噛むフロー
バックプレッシャーの経路では、ベースの書き込みは分散し、インデックスの書き込みは集中します。
ホットな GSI パーティションが、それを供給したベーステーブルの書き込みを拒否します。
スロットリングの理由コードを読む
例外の ResourceArn は GSI を名指しし、そのスロットリングの理由が、どの上限が枯渇したかを教えてくれます。スロットルされている操作は依然としてテーブルへの書き込みです。
| モード | 例外 | 理由コード | 何が枯渇したか |
|---|---|---|---|
| プロビジョンド | ProvisionedThroughputExceededException | IndexWriteProvisionedThroughputExceeded | GSI のプロビジョンド書き込みキャパシティ |
| 両方 | ThrottlingException | IndexWriteKeyRangeThroughputExceeded | 単一のホットな GSI パーティション |
| オンデマンド | ThrottlingException | IndexWriteMaxOnDemandThroughputExceeded | GSI に設定されたオンデマンドの最大スループット |
| オンデマンド | ThrottlingException | IndexWriteAccountLimitExceeded | その GSI に対するテーブルレベルのスループットクォータ(デフォルトは毎秒 40,000 書き込みリクエストユニット) |
出典: Understanding GSI write throttling and back pressure。
KeyRange の理由は、上記のホットパーティションのケースを示す決め手です。GSI 全体のキャパシティは問題なさそうに見えても、1 つのキー範囲だけが飽和していることがあります。
修正方法
GSI に余裕を与える。 GSI はテーブルとは別に、独自の読み取り・書き込みキャパシティを持ちます(GSI と LSI を参照)。AWS は、GSI の書き込みキャパシティを少なくともテーブルと同じだけプロビジョニングすることを推奨しています。
UpdateTable でその場で引き上げます。プロビジョンドのテーブルでは次のとおりです。
aws dynamodb update-table --table-name Tickets \
--global-secondary-index-updates '[{"Update":{"IndexName":"tickets-by-state",
"ProvisionedThroughput":{"ReadCapacityUnits":100,"WriteCapacityUnits":2000}}}]'オンデマンドでは、代わりに同じ Update ブロックで "OnDemandThroughput":{"MaxWriteRequestUnits":N} を送ります。予見できるスパイク(ローンチや計画的な移行)に備えるなら、そこで GSI の
WarmThroughput を前もって設定しておくと、即座に受けられる書き込みレートが上がります。
IndexWriteAccountLimitExceeded の場合は、Service Quotas コンソールでテーブルレベルの書き込みスループットクォータの引き上げをリクエストします。デフォルトの 40,000 は調整可能です。
パーティションキーを直す。 キャパシティを上げても、単一パーティションの上限である毎秒約 1,000 書き込みユニットは上がらないので、カーディナリティの低いキーには再設計が必要です。
日付を織り込む(OPEN#2026-06-23)だけでは、負荷が日ごとに分散するにすぎません。
1 日続く障害は、やはり 1 つのキーに集中します。
代わりに書き込みシャーディングします。状態に 0 から N-1 のサフィックス(たとえばチケット id のハッシュを N で割った余り)を付け、N 個の並列 Query で状態を読み戻して
SK でマージします。書き込みシャーディングと、CloudWatch Contributor Insights によるホットキーの見つけ方はホットパーティションで扱っています。
2025 年 11 月以降、GSI のキーは最大 4 つのパーティションキー属性にまたがれるので、
ticket_state と数値の shard を、連結した OPEN#3 という文字列ではなく、型付きの
2 つのキー属性にできます。それでも各クエリが指定するシャードは 1 つです。
射影する属性を減らす。 GSI への書き込みごとに、射影された属性がコピーされます。
KEYS_ONLY や絞った INCLUDE の射影ならインデックスへの書き込みが小さくなり、GSI が保存しない属性の更新はその GSI に何のコストもかけません。
レポート用途だけなら GSI を捨てる。「状態ごとのチケット」がホットパスではなく、たまの管理用の問い合わせにすぎないなら、恒常的にホットなインデックスより、フィルタ付きの定期的なスキャンのほうが勝ることがあります。 Query と Scan と天秤にかけてください。
そのインデックスにクエリするとき、キー条件は次のようになります。 Expression Builder は、独自のプレースホルダー名と型付けされた値で、これと同等のものを生成してくれます。
KeyConditionExpression "#s = :state AND begins_with(SK, :prefix)"
ExpressionAttributeNames { "#s": "ticket_state" }
ExpressionAttributeValues { ":state": { "S": "OPEN" }, ":prefix": { "S": "TICKET#2026-06-23" } }
覚えておくべき罠
「インデックスは書き込みを少し遅くするだけ」というリレーショナルの直感は、ここでは通用しません。GSI の書き込みキャパシティは、テーブルの書き込みレートに上限をかけます。サイズを小さくしたり、まとまってしまうキーを選んだりすると、GSI はそれが支えるテーブルにバックプレッシャーをかけます。
GSI の理由別スロットルメトリクス(ディメンションは TableName と
GlobalSecondaryIndexName)を監視しましょう: WriteKeyRangeThroughputThrottleEvents、
WriteProvisionedThroughputThrottleEvents、
WriteMaxOnDemandThroughputThrottleEvents。
あわせて、同じディメンションで ConsumedWriteCapacityUnits と WriteThrottleEvents を、テーブルで WriteAccountLimitThrottleEvents を追跡します。
次の GSI スロットリングを防ぐガイド
- GSI と LSI: なぜ GSI が独自のキャパシティと異なるパーティションキーを持つのか。
- ホットパーティション: ホットキーを見つけ、シャーディングする。
- シングルテーブル設計: ホットなインデックスを増やさずに、 1 つの GSI をオーバーロードして多くのパターンをさばく。
- Query と Scan: インデックスがその書き込みコストに見合わないとき。
DynoTable を試して、テーブル上のあらゆる GSI(キースキーマ、射影、サイズ)を調べ、ローンチの前にインデックスへクエリしましょう。