初級読了 2 分

DynamoDB のアイテムサイズ上限(400 KB)

単一の DynamoDB アイテムが保持できるデータは、最大 400 KB です。MongoDB(16 MB のドキュメント)やリレーショナルの行から来ると、その上限は低く感じます。

たいていは痛い目に遭って発見します。何か月も動いていた書き込みが、1つのアイテムが大きくなりすぎたせいで ValidationException で失敗するのです。

DynamoDB の最大アイテムサイズは?

アイテムあたり 400 KB(409,600 バイト)で、属性名と値を合わせて数えます。引き上げられるクォータではなく固定の制約なので、これに達したアイテムは形を変えるしかありません。

  • 値だけでなく名前もカウントされます。 すべてのアイテムのすべての属性名が、その UTF-8 のバイト数を加えます。リスト、マップ、セットの中のすべての要素も同様です。
  • よくある原因は際限のない肥大化です。 親アイテムに埋め込まれたリストが、トラフィックとともに増えていくことです。
  • AWS 自身のガイダンスによる3つの出口: 増え続けるデータを別々のアイテムに分割する、大きな属性値を Binary に圧縮する、または塊を Amazon S3 に格納してそのキーをアイテムに保持する。

問題: 永遠に増え続けるアイテム

顧客アカウントごとに監査証跡を残していて、そのアカウントの監査イベントをアカウントアイテム上のリストとして格納すると決めたとします。

PK: ACCOUNT#A-7741   events: [ {ts, actor, action}, {ts, actor, action}, ... ]

1日か2日は問題ありません。しかしサインイン、設定の変更、キーのローテーションのたびにイベントが1つ増え、イベントは止まらないので、リストは際限なく増えます。

やがて、あと1回の追加でアイテムが 400 KB を超えることになり、DynamoDB はその更新を ValidationException: Item size to update has exceeded the maximum allowed size で拒否します。

それ以降、アイテムは一切大きくなれないので、そのアカウントの監査イベントをもう記録できなくなります。(サイズ超過のアイテムを PutItem すると、少し違う文面になります: Item size has exceeded the maximum allowed size。)

失敗より先にコストが効いてきます。UpdateItem はアイテムの更新前と更新後のサイズの大きい方で課金されるので、300 KB のアイテムに小さなイベントを1つ追加するだけで 301 WCU かかります。

埋め込みがうまくいくのは、「多」の側が有界で小さい場合だけです。際限のない一対多の関係には、独自のアイテムが必要です。

400 KB に何がカウントされるか

DynamoDB はアイテムの合計サイズを、次の合計として測ります。

  • すべての属性名、UTF-8 エンコード。数百万のアイテムにわたって繰り返される20文字の名前は、サイズでもあり、支払うことになるストレージでもあります。大量のアイテムでは名前を短く保ちましょう。
  • すべての属性値。 文字列とバイナリはそのバイト長で、数値はコンパクトなエンコードで(AWS はそのサイズを有効桁2桁あたり「約」1バイト、プラス1バイトとしています)、ブール値と null は1バイトで。
  • ネスト構造。 リストやマップは自身のオーバーヘッドに 加えて、その中のすべての要素とキーのサイズを、末端まですべてカウントします。

その予算の中では、ほかに2つの上限が適用されます。キー属性にはそれぞれ独自の最大値があります。パーティションキーの値は最大 2,048 バイト、ソートキーの値は最大 1,024 バイトです。

ローカルセカンダリインデックスを持つテーブルでは、各アイテム と、すべての LSI におけるそのエントリ(キーと射影された属性)の合計も 400 KB に収まらなければなりません。それ以外に、単一の属性に独自の上限はありません。

AWS のアイテムサイズのドキュメントが正確なバイト計算を詳述しており、制約のページがキーと LSI の上限を列挙しています。

大きなアイテムのコスト

サイズは上限に達したときだけでなく、すべてのリクエストでコストを左右します。読み取りは 4 KB 単位、書き込みは 1 KB 単位で計測されるので、400 KB のアイテムは強整合性の読み取りで 100 RCU(結果整合性なら 50)、書き込みで 400 WCU かかります。

大きなアイテムへの更新は、1つの属性しか変えない場合でも、毎回アイテム全体の分を支払います。だからこそ小さく的を絞ったアイテムが有利です。必要な部分だけを読み書きしましょう。

回避するモデリング

何が増えているかで対処を選びます。

際限のないリスト → 独自のアイテムへ。 監査の例では、埋め込みをやめましょう。各イベントに、アカウントと同じパーティション内で、ソートキーのタイムスタンプで順序付けた 独自のアイテムを与えます。

PK: ACCOUNT#A-7741   SK: EVT#2026-06-27T10:00:05Z   actor, action
PK: ACCOUNT#A-7741   SK: EVT#2026-06-27T10:00:10Z   actor, action

これで単一のアイテムが成長することはなくなり、ACCOUNT#A-7741 に対する1回の Query でソートキーを EVT# のプレフィックスに絞れば、依然としてアカウントのイベントを1つのアイテムコレクションから時刻順に取り出せます。

1つの大きなテキスト値 → 圧縮する。 長い説明文、ログ、ドキュメント本文はよく圧縮できます。GZIP して Binary 属性に入れましょう。AWS によると、圧縮した値はフィルタリングには役立たないので、フィルタに使う属性は圧縮せずに残しておきます。

塊(画像、PDF、大きな JSON)→ S3 へ。 オブジェクトを Amazon S3 に格納し、アイテムにはそのキーだけを保持します。DynamoDB には S3 にまたがるトランザクションがないので、書き込みが途中で失敗したときは、孤立したオブジェクトをコード側で片付ける必要があります。

圧縮は余裕を生みますが、永遠に増え続けるリストを直すわけではありません。有界なサブリスト(ひとつまみのタグ、固定の設定ブロック)は埋め込んで構いません。際限のないものはアイテムにします。

書き込み時にリストを有界に保つ

アイテム上に上限付きのリストを残すなら、その上限を書き込み自体で強制しましょう。そうすればあふれたときはサイズエラーではなく、処理できる ConditionalCheckFailedException になります。if_not_exists と attribute_not_exists の部分によって、最初の追加でリストを作成できます。

await client.send(
  new UpdateItemCommand({
    TableName: 'AuditLog',
    Key: {PK: {S: 'ACCOUNT#A-7741'}, SK: {S: 'META'}},
    UpdateExpression: 'SET events = list_append(if_not_exists(events, :empty), :e)',
    ConditionExpression: 'attribute_not_exists(events) OR size(events) < :max',
    ExpressionAttributeValues: {
      ':e': {L: [{M: {action: {S: 'sign-in'}}}]},
      ':empty': {L: []},
      ':max': {N: '100'}
    }
  })
);

構文は更新式と条件式で説明しています。

すでに上限に達したアイテムを救出する

アイテムを縮める書き込みは引き続き成功します。新しいイベントは今すぐ EVT#<ts> アイテムとして書き込み始め、埋め込まれたリストを BatchWriteItem(1回の呼び出しで25アイテム)でコピーし、それから親から REMOVE events します。

最後の更新の分は予算に入れておきましょう。削除前のアイテムの全サイズで課金されるので、上限に達したアイテムなら約 400 WCU です。

DynoTable でアイテムサイズを確認する

形を確定させる前に、代表的なアイテムを量りましょう。DynoTable では、クイックビューがアイテムの推定 DynamoDB サイズを属性と並べて表示するので、失敗した書き込みでではなく、実データを閲覧しながら重すぎる形を捕まえられます。

ブラウザで済ませたいですか? DynamoDB アイテムサイズ計算ツール が、貼り付けたサンプルから同じことを行い、KB と、各読み取り・書き込みにかかる RCU/WCU を報告します。

本番環境では、DynamoDB に直接尋ねましょう。AWS は書き込みに ReturnConsumedCapacity を設定し、400 KB に近づいたアイテムでアラートを出すことを推奨しています。1回の書き込みで数百 WCU が報告されたら、それは上限に近いアイテムです。

DynoTable のクイックビューで 1 つの DynamoDB アイテムの属性を確認し、400 KB のアイテムサイズ上限に何が算入されるかを見る。
DynoTable のクイックビューで 1 つの DynamoDB アイテムの属性を確認し、400 KB のアイテムサイズ上限に何が算入されるかを見る。

DynamoDB に照らしてバイト計算を確認する

ConsumedCapacity はバイトではなくユニットを報告し、N バイトの書き込みは ceil(N / 1024) WCU かかります。一般には粗いのですが、境界上では正確です。ちょうど 1,024 バイトのアイテムは必ず 1 WCU、1,025 バイトのアイテムは必ず 2 WCU になります。

そこで以下の各テストアイテムは、1つの文字列属性でパディングして境界に着地させ、属性名と値のバイト数を数えてサイズを求め、1回書き込んで、消費キャパシティを読み戻しました。

アイテム計算上のバイト数予測 WCU課金 WCU
ちょうど 1 KB1,02411
1 KB + 1 バイト1,02522
ちょうど 2 KB2,04822
2 KB + 1 バイト2,04933
ちょうど 4 KB4,09644

1,024 バイトと 1,025 バイトのアイテムはパディング1文字分しか違いませんが、DynamoDB は計算上のサイズが段差の位置だと示すまさにその場所で、それらを異なる料金で課金します。

これで文字列についての名前と値を合わせた計算が確認できます。数値のサイズは概算でしかないので、多くの数値を含むアイテムでは余裕を残しておきましょう。

1キロバイトを1バイト超えると、毎回の書き込みでまるまる 1 WCU 余計にかかります。そして 4 KB では同じ段差が読み取り側に現れます。アイテムを 1,025 バイトから 1,024 バイトに削れば以降の書き込みコストは半分になり、1,024 から 1,025 に膨らませれば倍になります。

落とし穴と次のステップ

  • トラフィックとともに増える埋め込みリストは、アイテムが 400 KB に達する典型的な経路です。独自のアイテムに移すか、上で示した size() 条件で上限を設けましょう。
  • 属性名を短くすると、大量のアイテムでサイズとストレージを取り戻せます。
  • 大きな値は S3 へ(キーはアイテムに保持)。大きなテキストは Binary に圧縮できます。
  • 関連: 非正規化 と一対多の関係 が、いつ埋め込み、いつ分割するかを扱います。DynamoDB の制限 にはその他の上限がまとめられています。

自分のアイテムを量るには、DynoTable をダウンロードしましょう。クイックビューは各アイテムの推定サイズを、テーブルの概要は平均アイテムサイズ(DynamoDB による推定値で、約6時間ごとに更新)を表示します。

キャパシティの数値は 2026-07-26 に us-east-1 の実稼働 DynamoDB サービスに照らして検証し、 DynamoDB Local 3.3.1 で再現しました。

著者: Dmitriy · 更新日