DynamoDB 複合プライマリキー:パーティションキー + ソートキー
複合プライマリキーは2つの属性です: パーティションキーとソートキー。パーティションキーはアイテムがどこに存在するかを決め、ソートキーはそのパーティションキーを共有するアイテムを順序付けます。
SQL の出身者なら、一意の id 列よりも、(partition, sort) に対するクラスタ化インデックスに近いものと考えてください。
DynamoDB の複合プライマリキーとは?
- 2つのパート、2つの仕事。 DynamoDB はパーティションキーをハッシュして物理パーティションを選び、ソートキーはそのパーティションキーの値を共有するすべてのアイテムを順序付けます。
- 一意性はペア。 2つのアイテムは、ソートキーが異なる限り、パーティションキーの値を共有できます。それが1つのパーティションキーの値が多数のアイテムを保持できる仕組みです。
- ソートキーが範囲を可能にする。
Queryは1つのパーティションキーの下で、ソート済みの範囲(>=、BETWEEN、begins_with)をScanなしに返せます。 - キーはスカラーでなければならない。 パーティションキーとソートキーは文字列、数値、バイナリのみで、マップ、リスト、セットは不可です(AWS ドキュメント)。
単純なキー vs 複合キー
単純なプライマリキーはパーティションキーだけです。1つのアイテムを識別し、GetItem で読み戻します。それに対する Query が返すのは、多くてもその1アイテムです。読み取る範囲も、「最新の N 件を取得」もありません。
複合キーはソートキーを加えます。そのたった1つの追加が、キーバリューのルックアップを順序付きの範囲読み取りに変えます。
| 単純なキー | 複合キー | |
|---|---|---|
| 属性 | パーティションキーのみ | パーティションキー + ソートキー |
| 一意性 | パーティションキーの値 | 値のペア |
| パーティションキーの値あたりの数 | 1件 | 多数 |
範囲の Query | 不可(返るのは最大1アイテム) | 可(begins_with、BETWEEN、>) |
| 自然な適合 | ID によるルックアップ | 時系列、1対多、履歴 |
センサー読み取り値のテーブルをモデル化する
フィールドセンサーの一群から温度サンプルを収集しているとします。アクセスパターンは「1つのデバイスの読み取り値を、新しい順に、時間枠内で取得する」です。これは教科書的な複合キーです。
デバイス ID をパーティションキーに、読み取り値のタイムスタンプをソートキーに使います:
| deviceId | readingTs | tempC | humidity |
|---|---|---|---|
| DEV#a1b2 | 2026-06-23T08:00:00Z | 21.4 | 48 |
| DEV#a1b2 | 2026-06-23T08:05:00Z | 21.7 | 47 |
| DEV#a1b2 | 2026-06-23T08:10:00Z | 22.1 | 46 |
| DEV#c9d8 | 2026-06-23T08:00:00Z | 19.8 | 55 |
3つの DEV#a1b2 の読み取り値は1つのパーティションキーの値を共有するので、DynamoDB はそれらをまとめて、readingTs でソートして保存します。
AWS はソートキーを範囲属性と呼び、その名前は "derives from the way DynamoDB stores items with the same partition key physically close together, in sorted order by the sort key value" と説明しています(AWS ドキュメント)。
1つのパーティションキーの下のアイテムは アイテムコレクション を形成します。このページはキーの選び方を扱います。コレクションを1単位として読み取る方法と、LSI が加えるサイズ上限についてはアイテムコレクションで説明しています。
パーティションキーに対する1回の Query が、そのデバイスの読み取り値をすでにタイムスタンプ順で読み取るので、クライアント側でのソートは不要です。
各レスポンスページは 1 MB で止まります。5分ごとに報告するデバイスは1年で約105,000件の読み取り値を生むので、残りは LastEvaluatedKey をたどって取得します(ページネーション)。
その時間枠のコスト
各読み取り値が約2 KB で、時間枠に10件あるとします。合計20 KB です。Query は読み取るアイテムのサイズを合計し、その合計を1回だけ次の4 KB に切り上げます。
したがって、その時間枠に対する結果整合性のある Query は2.5読み取りユニット(4 KB ブロック5個 × 0.5)、強整合性の Query は5ユニットです。プロビジョニングされたテーブルではこれを RCU として、オンデマンドのテーブルでは読み取りリクエストユニットとして数えます。
10回の個別の GetItem 呼び出しでは、アイテムごとに切り上げます。2 KB の読み取り値はそれぞれ4 KB ブロック1つ分になるので、結果整合性で5ユニット、強整合性で10ユニット、加えて10回の往復です。
| 読み取りパターン | アイテム | 触れたデータ | EC 読み取りユニット |
|---|---|---|---|
1回の Query、readingTs が開始と終了の間 | 10 | 20 KB | 2.5 |
完全な複合キーに対する GetItem 10回 | 10 | 20 KB | 5 |
パーティションのみ Query、アプリでフィルタ | 約105,000(1年分) | 約205 MB | 約26,000 |
テーブルを Scan、deviceId と時間枠でフィルタ | 全件 | テーブル全体 | テーブルサイズ次第 |
フィルタを使っても3行目の請求額は減りません。ソートキー条件がなければ Query はコレクション全体を読み取ります。1年分の2 KB の読み取り値は、残すかフィルタで除くかにかかわらず、約200ページにわたって約26,000ユニットになります。
プロトタイピング中は ReturnConsumedCapacity: TOTAL を渡しましょう。秒あたりのリクエスト数が分かれば、料金計算ツールがそのユニット数を月額の項目に変えてくれます。
範囲をスキャンせずに照会する
ISO-8601 文字列が時系列順にソートされるのは、すべての値が1つの固定形式を使う場合だけです。Z 付きの UTC で、すべてのアイテムで同じ精度にします。このテーブルはどこでも YYYY-MM-DDTHH:MM:SSZ を使っています。形式が混在すると順序が崩れます:
| 2026-06-23T08:00:00.500Z | sorts first: "." comes before "Z" |
|---|---|
| 2026-06-23T08:00:00Z | |
| 2026-06-23T09:00:00+02:00 | 07:00 UTC, yet sorts last |
形式が1つなら、時間枠の読み取りはフィルタではなく、キー条件の範囲になります:
Query
deviceId = "DEV#a1b2"
readingTs BETWEEN "2026-06-23T08:00:00Z" AND "2026-06-23T08:10:00Z"
これは KeyConditionExpression です。DynamoDB がデータを返す前に読み取りを絞るので、枠内のアイテム分だけ料金を払います。FilterExpression は読み取りの後に実行され、読み取ったすべてのアイテム分を請求します。それがミニチュア版の Scan の罠です。
その式そのものは、プレースホルダと型付けされた値があり、手で書くのは面倒です。DynamoDB Expression Builder で視覚的に構築し、正確な KeyConditionExpression を SDK 呼び出しにコピーしましょう。
その読み取りには、時間バケットをキーとする GSI を追加します。各読み取り値に readingDay = "2026-06-23" を書き込み、readingTs をソートキーとしてインデックス化し、時間枠がまたがる日ごとに1回、readingDay = :day AND readingTs > :eightAm でインデックスに Query します。
フリート規模では、そのバケットを最初からシャーディングしましょう。1つの readingDay キーがその日のすべての書き込みを受けます。下で使う秒あたり10,000件の読み取り値(各2 KB)なら20,000書き込みユニットで、1パーティションが処理できる1,000の20倍です。
readingTs は増える一方なので、分割は役に立ちません。書き込みユニット ÷ 1,000 を十分に上回る数のシャード(ここでは 2026-06-23#0 から #31、それぞれ約625)を使い、すべてのシャードに Query して結果をマージします。シャーディングについてはホットパーティションで説明しています。
スロットリングされた GSI はベーステーブルもスロットリングします。テーブルへの書き込みは、すべての GSI にその分の書き込みキャパシティがあるときにだけ成功します。
ソートキーを意図的に設計する
範囲条件をサポートするのはソートキーだけなので、クエリに合わせて形作りましょう。
- ソート可能なタイムスタンプを使う。 1つの固定 UTC 形式の ISO-8601 文字列や ゼロ埋め したエポック数値は正しくソートされます。生のローカライズされた日付はソートされません。
- 1対多の オーバーロード のためにプレフィックスを付ける。
READING#2026-06-23T08:00:00Zのようなソートキーは、1つのパーティションの下にエンティティ型を混在させ、begins_withでスライスできるようにします。それがシングルテーブル設計への入り口です。 - 高カーディナリティの次元をパーティションキーに置く。 デバイス ID は数千の値を持つので、書き込みを均等に分散させます。低カーディナリティのパーティションキー(たとえば
region)は ホットパーティション を作ります。
region に値が5つしかなく、フリートが秒あたり10,000件の読み取り値(各約2 KB)を書き込むとします。各 region キーに秒あたり約4,000書き込みユニットが集中し、1つのパーティションが処理できる1,000の4倍です。
readingTs は増える一方なので、新しい書き込みはすべてコレクションの末尾に着地し、分割で分散させることはできません(物理パーティション)。5,000個のデバイス ID をキーにすれば、同じストリームはキーあたり秒間約2書き込みです。
複合キーが噛んでくるとき
複合キーはコミットメントです。パーティションキーを選んでリリースし、それから別のグループ化を必要とするアクセスパターンを発見します。「フリート全体で30°Cを超えるすべての読み取り値」です。
パーティションキーは固定されているので、ベーステーブルはそれに答えられません。スパース GSI を使いましょう。30°Cを超える読み取り値にだけ alertBucket = "HOT" を書き込み、alertBucket と readingTs をキーとする GSI を作ります。
alertBucket を持たない読み取り値はインデックスに入らないので、alertBucket = "HOT" に対する Query は高温の読み取り値だけを時間順で返します。アラートが頻繁ならバケットをシャーディングしてください。スパースインデックスを参照してください。
テーブルのプライマリキーは変更できないので、キースキーマをコミットする前に読み取りを列挙しましょう。新しいキーは新しいテーブルを意味します。作成し、バックフィルし、切り替え中は二重書き込みし、それから読み取りを移します。
バックフィルするには、S3 にエクスポートして新しいテーブルにインポートします。これは新しいキー属性がすでにすべてのアイテムに存在する場合に使えます(インポートはテーブルを LSI なしで作成します)。そうでなければ、古いテーブルを Scan して各アイテムを新しいキーで書き込みます。
切り替えの手順はマイグレーションで説明しています。
DynoTable では、テーブルの「概要」にプライマリキーとすべてのセカンダリインデックスが一覧表示されます。フィルタビルダーでインデックスを選んで Query を実行すると、行がソートキー順で返ってくるので、誤ってソートされるタイムスタンプ形式が本番より前に見つかります。
次のステップ
複合キーはそのままアイテムコレクションにつながります。そこでは1つのキーの下のアイテムを1単位として読み取ります。次にシングルテーブル設計と GSI と LSI の比較を読んでください。
DynamoDB Expression Builder で KeyConditionExpression を描き、クエリビルダーでページネーション込みの完全な Query を出力し、それからDynoTable を試して、自分のテーブルに対してこれらのクエリを実行し、ソート順が並ぶ様子を観察しましょう。