上級読了 5 分

DynamoDB の GSI は内部的にどう保存されるか

は、あなたが選んだ属性の独自のコピーを独自のパーティションに保持し、DynamoDB はベーステーブルへの書き込みのたびに、そのコピーを非同期に更新します。

DynamoDB の GSI はどう保存されるのか?

AWS によれば、GSI のデータは "is stored separately from the data in its base table" であり、そのパーティションは "behave in much the same way as table partitions" です。

各エントリは GSI キー、ベーステーブルのキー、そして 属性を保持し、 DynamoDB はベースへの書き込みの後でインデックスを更新します。

SQL から来ると、インデックスは同じテーブル上の B ツリーで、同じトランザクション内で更新されるものです。GSI はその両方の前提を破ります。

  • GSI はそれ自身のテーブルのように動く。 そのパーティションは、ベーステーブルのではなく GSI のパーティションキーでキー付けされます。
  • 更新は非同期。 あなたの書き込みはまずベーステーブルにコミットされ、その後 DynamoDB がそれを各 GSI に適用します。
  • 射影された属性だけが保存される。 インデックスは GSI キー、ベースキー、そしてあなたが射影した属性を保持します。
  • GSI キーは一意である必要はない。 複数のベースアイテムが 1 つの GSI パーティション/ ソートキーを共有できます。各エントリと一緒に保存されるベースの が、それらを区別します。

1 つのベースアイテムから始める

SaaS の 監査ログ を取ります。ワークスペース内のすべての特権的なアクションが不変のイベントになります。ベーステーブル WorkspaceEvents は、あるワークスペースのすべてのイベントが 1 つの に、時刻順で存在するようにキー付けされています。

WorkspaceEvents (base table)
EventPKEventSKactorIdverbtargetRef
WS#orbit-9TS#2026-06-23T14:02:11ZUSR#kpROLE_GRANTEDUSR#mara

EventPK = "WS#orbit-9" はワークスペースでパーティション分けし、EventSK は ISO タイムスタンプなので Query はあるワークスペースのイベントを時系列順で返します。それは「このワークスペースのタイムラインを見せて」を完璧に提供します。

それ以外は何も提供しません。「USR#kp はすべてのワークスペースで何をしたか?」は問えません。 actorId はキーではないので、ベーステーブルでそれに答える唯一の方法はフルの Scan です。それこそ、GSI が追加するために存在するアクセスパターンです。

GSI を追加して 2 つ目のテーブルが現れるのを見る

同じイベントを、それを実行した者で再パーティション分けする GSI ByActor を定義します。

ByActor (GSI)
partition key = actorId   ("USR#kp")
sort key      = EventSK   ("TS#2026-06-23T14:02:11Z")

DynamoDB は今や 2 つ目の物理構造を維持します。同じ論理イベントが 2 回 保存されます。一度はベーステーブルの WS#orbit-9 パーティションに、そしてもう一度は GSI の USR#kp パーティションにです。

ByActor (GSI) — its own partition space
actorIdEventSKEventPKverb
USR#kpTS#2026-06-23T14:02:11ZWS#orbit-9ROLE_GRANTED

何が一緒に乗ってきたかに注目してください。ベーステーブルのキー(EventPK、EventSK)は、すべての GSI アイテムに自動的に保存されます。それが、GSI のヒットがあなたを完全なアイテムへ指し戻せる理由であり、KEYS_ONLY インデックスでもストレージがかかる理由です。

GSI に何が住むのか

インデックスはアイテム全体を コピーしません。各 GSI エントリはちょうど 3 つのものを保持し、あなたが制御するのは 3 つ目だけです。

GSI に保存されるものどこから来るか任意?
GSI パーティション + ソートキーGSI キーとして名付けた属性いいえ
ベーステーブルのキーすべてのベースアイテムからコピーいいえ
射影された属性あなたの Projection の選択はい

Projection は KEYS_ONLY、INCLUDE(名前付きリスト)、または ALL です。GSI に対する Query は、インデックス内にある属性しか返せません。

射影されていない属性を求めると、その Query は ValidationException("Global secondary index ByActor does not project [targetRef]")で失敗します。ALL 以外のインデックスに対する Select: ALL_ATTRIBUTES も同じように失敗します。

AWS: "Global secondary index queries cannot fetch attributes from the parent table."(Query API リファレンス)

SQL なら欠けたカラムのためにヒープへ結合し戻します。GSI の Query はそうしないので、読むものは射影するか、一緒に運ばれるキーでベーステーブルから完全なアイテムを取得しましょう。

書き込みがインデックスに届く仕組み

ベースの書き込みとそのインデックス更新は、1 つのアトミックな操作ではありません。

PutItem すると、DynamoDB はベーステーブルにコミットし、あなたの書き込みを承認し、その後各 GSI を更新します。承認はインデックスを待ちません。

監査書き込みの、上から下への順序はこうです。

PutItemWS#orbit-9 イベントベースパーティションにコミット200 OKを呼び出し元へ非同期パス:GSI キーを抽出ByActor パーティションUSR#kp へルート射影された属性を書き込む

呼び出し元はステップ 3 で、ステップ 4 から 6 が終わる前に 200 OK を受け取るので、そのギャップ中に ByActor に対する Query は、真新しいイベントを見逃すことがあります。

その非同期性は文書化された動作です。AWS によれば、GSI は "asynchronously, using an eventually consistent model" で、通常 "within a fraction of a second" に更新されます。完全な帰結はなぜ GSI は結果整合性なのか にあります。

GSI キーは一意キーではない

SQL では、非一意のセカンダリインデックスがデフォルトで、一意なものはオプトインする制約です。 GSI には一意性の保証が まったく ありません。

2 つのワークスペースで同じアクターが同じ瞬間に行った 2 つのイベントは、同じ actorId かつ EventSK を共有します。

DynamoDB は両方を保存し、各エントリはそれぞれ自分のベースのプライマリキーを持ちます。AWS によれば、GSI キーを共有するアイテムは "in no particular order" で返ってきます。

だから 1 人のアクターの 1 つの瞬間に対する GSI Query は、正当に複数のアイテムを返すことがあります。SQL の一意インデックスが与えるようにキーごとに 1 行と仮定していたなら、それが地雷です。

一意な値(メールアドレス、ハンドル)が必要なときは、ベーステーブルで強制しましょう。1 つの TransactWriteItems の中で、本来のアイテムと、その値をキーにしたマーカーアイテム(EMAIL#<value>)を put し、それぞれの Put を attribute_not_exists でガードします。

重複があるとトランザクション全体がキャンセルされます。完全なパターンは複数の属性での一意性にあります。

キャパシティはテーブルではなくインデックスにある

プロビジョンドのテーブルでは、GSI は 独自の 読み取りと書き込みのキャパシティを持ち、ベーステーブルとは別にスロットルされます。ByActor からの読み取りは GSI の読み取りユニットを消費し、テーブルのものは決して消費しません。

書き込みは両者を結び付けます。インデックスに関わるすべてのベーステーブルの書き込みはインデックスにも書き込み、GSI がそれを吸収できないと、ベーステーブルの書き込みがスロットルされます。その仕組みはそれ自身のガイドを持っています。 GSI がベーステーブルの書き込みをスロットルするとき。

これはまた、GSI のパーティションキーがベーステーブルのそれと同じくらい重要な理由でもあります。低カーディナリティの GSI キーは、ベースの書き込みが分散していても、書き込みを 1 つのインデックスパーティションに固めます。あなたが再キー付けによって作り出したホットパーティションです。

解決策は、高カーディナリティな部分を持つ複合 GSI キー(ACTIVE ではなく ACTIVE#customer123)にするか、GSI がキーにする属性を書き込みシャーディングして各シャードをクエリすることです。シャーディングはホットパーティションで扱っています。

GSI の書き込み増幅

GSI を変更するすべてのベーステーブル書き込みは、どちらのキャパシティモードでも ベースの書き込みユニット + インデックスの書き込みユニット がかかります(プロビジョンドでは書き込みキャパシティユニット、オンデマンドでは書き込みリクエストユニット)。

GSI を 1 つ持つテーブルの 1 KB のアイテムで、そのインデックスエントリも 1 KB に収まるなら、かかるのは 2 書き込みユニットです。テーブルに 1 つ、インデックスエントリに 1 つです。

  • GSI キーを変更する更新 は、インデックスへの書き込みが 2 回かかります。古いエントリの削除と、新しいエントリの put です。
  • インデックスがキーにも射影にもしていない属性だけに触れる更新 は、インデックスへの書き込みがまったくかかりません。
  • 射影がコストを変えるのは 1 KB を超えてから。 1 KB までのインデックスエントリは、射影にかかわらず 1 書き込みユニットです。KEYS_ONLY は大きなアイテムでは書き込みユニットを、すべてのアイテムではストレージを節約します。ALL はストレージを倍にすることがあります。

アイテムサイズと射影は 料金計算機 でモデルしてください。

落とし穴と次のステップ

  • 射影されていない属性を要求しない。 それを指定した GSI Query は失敗します。完全なアイテムが必要なら、それを射影するか、一緒に運ばれるキーでベーステーブルから取得しましょう。
  • GSI キーを一意として扱わない。 Query がキーごとに複数のアイテムを返すことを想定しましょう。ベースのプライマリキーだけが唯一の本当のアイデンティティです。
  • それに供給した書き込みの直後に GSI を読まない。 非同期パスのため、インデックスがまだあなたの書き込みを表示していないことがあります。read-your-own-writes が必要なときは、 ConsistentRead: true でベーステーブルを読みましょう(ベースキーに対する GetItem または Query)。
  • GSI に十分な書き込みキャパシティを与える。 プロビジョンドのテーブルについて AWS は、GSI の書き込みキャパシティは "should be equal or greater than the write capacity of the base table" としています。オンデマンドでは、GSI はテーブルのモードを継承し、パーティションごとの上限はそのまま適用されます。

すべての勝負どころは、あなたのパターンを提供するキーの形を選ぶことです。シングルテーブル設計 は 1 つの GSI を多数のパターンにまたいでオーバーロードします。GSI と LSI は、代わりにローカルインデックスが合うのはいつかを扱います。

GSI の KeyConditionExpression を DynamoDB 式ビルダーで組み立ててプレビューしましょう。名前と値はビルダーがエスケープします。例えば、あるカットオフ以降の 1 人のアクターに一致させる場合です。

KeyConditionExpression: "#a = :actor AND #ts > :since"
ExpressionAttributeNames:  { "#a": "actorId", "#ts": "EventSK" }
ExpressionAttributeValues: {
  ":actor": { "S": "USR#kp" },
  ":since": { "S": "TS#2026-06-01T00:00:00Z" }
}

それから DynoTable を試して みましょう。テーブルの 設定 にあるテーブルのインデックス セクションに各インデックスのキーと射影が表示され、ベーステーブルの隣で GSI をクエリできます。

著者: Dmitriy · 更新日