DynamoDB JSON とマーシャリング
DynamoDB API から生のデータを初めて読むと、それは自分が入れた JSON のようには見えません。
{"status": "open", "priority": 3} のような素のオブジェクトが、
{"status": {"S": "open"}, "priority": {"N": "3"}} として返ってきます。
すべての値が、その型を名指しする1キーのオブジェクトに包まれています。その包み込みが DynamoDB JSON であり、それとの相互変換が マーシャリング と呼ばれます。
DynamoDB JSON とは?
DynamoDB API の、型タグ付きのワイヤ形式です。このタグがあるからこそ、DynamoDB は素の JSON では表現できない型(セット、バイナリ)を運び、数値を正確に保てます。
- すべての値がその型を持ちます: 文字列なら
{"S": "..."}、数値なら{"N": "..."}、といった具合に、10 種類の DynamoDB のデータ型 すべてに及びます: S、N、B、BOOL、NULL、 L、M、SS、NS、BS。 - マーシャリング = 素の JSON → DynamoDB JSON。アンマーシャリング = その逆。
- 数値はワイヤ上では文字列です:
{"N": "3"}であって{"N": 3}ではありません。 - 手書きしないこと。 SDK のドキュメントクライアント(または
marshall())が代わりにやってくれます。生の形を読むのは、低レベルのリクエストやログの行をデバッグするときだけにしましょう。
問題: 素の JSON では足りない
JSON には文字列、数値、ブール値のスカラーに加えて、null、配列、オブジェクトがあります。
DynamoDB にはもっとあります。バイナリと、JSON がまったく表現できない3つの セット 型(文字列セット、数値セット、バイナリセット)です。JSON の配列は、それがリストなのかセットなのかを示せません。
もう1つの隔たりは数値です。タグがなければ、文字列 "3" は String とも Number とも取れるので、DynamoDB がどちらとして格納すべきかをタグが明示します。タグは、あらゆるリクエストとレスポンスで、各値の正確な型をロスレスに示す方法です。
エンコードの仕組み
すべての属性値は、キーが 型記述子 である単一キーのオブジェクトになります:
S、N、B、BOOL、NULL、L、M、SS、NS、BS のいずれかです。データ型ガイド に、それぞれの例と、どの型がキーになれるかを含む完全な表があります。
リストとマップは同じ記述子を末端までネストするので、深く構造化されたアイテムは深く包まれます。この形式は AWS 低レベル API リファレンスで定義されています。
数値がワイヤ上で 文字列 として載るのは意図的です。DynamoDB は最大38桁の精度を保ちますが、
JSON.parse をはじめ、ほとんどの JSON パーサーは JSON の数値を IEEE-754 の倍精度として読み、有効数字はおよそ15〜17桁にとどまります。
具体例: 監査ログのエントリ
アプリで書くであろう素の JSON:
{
"actor": "u-204",
"action": "ticket.close",
"ticketId": 8842,
"tags": ["billing", "urgent"],
"redacted": false
}API 用に DynamoDB JSON へマーシャルしたもの:
{
"actor": {"S": "u-204"},
"action": {"S": "ticket.close"},
"ticketId": {"N": "8842"},
"tags": {"SS": ["billing", "urgent"]},
"redacted": {"BOOL": false}
}ticketId は 文字列 値の N になりました。tags を 文字列セット(SS)にしたのはモデリング上の選択です。素の JSON を与えられた汎用コンバータは L を出力します。JSON の配列は順序付きで重複できる一方、SS は重複を排除し順序を持たないからです。
その判断はどのコンバータも代わりにしてくれないので、次のセクションのとおり、コードの中で自分で決めます。
コードで変換する
JavaScript では、@aws-sdk/util-dynamodb が双方向に変換し、
@aws-sdk/lib-dynamodb(ドキュメントクライアント)があらゆるリクエストとレスポンスで同じ変換を実行します:
import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient, PutCommand} from '@aws-sdk/lib-dynamodb';
import {marshall, unmarshall} from '@aws-sdk/util-dynamodb';
// A JS Set marshals to SS (or NS); an array marshals to L.
const item = {actor: 'u-204', ticketId: 8842, tags: new Set(['billing', 'urgent'])};
marshall(item); // { actor: {S: 'u-204'}, ticketId: {N: '8842'}, tags: {SS: ['billing', 'urgent']} }
unmarshall({ticketId: {N: '8842'}}); // { ticketId: 8842 }
const doc = DynamoDBDocumentClient.from(new DynamoDBClient({}), {
marshallOptions: {removeUndefinedValues: true}
});
await doc.send(new PutCommand({TableName: 'AuditLog', Item: item}));戻りでは、素の unmarshall は {"N": "3.14159265358979323846"} をエラーなしで
3.141592653589793 に変えてしまいます。大きな整数は BigInt として返り、大きな小数は例外を投げます。精度が重要な場面では wrapNumbers: true(ドキュメントクライアントでは
unmarshallOptions)を渡すと、すべての数値が正確な文字列を保持する NumberValue として得られます。
他の SDK にも同じ組み合わせがあります。Python では、boto3 のリソース層と
TypeSerializer/TypeDeserializer がこの役目を担います。
コードを書かずに済ませるなら、素の JSON を DynamoDB JSON コンバータ に貼り付けてマーシャル(および逆変換)できます。リクエストを組み立てるときは、 DynamoDB Expression Builder が、式と並んで正しくマーシャルされた属性値マップを出力します。
低レベルクライアントとドキュメントクライアント
AWS SDK for JavaScript は2つの層を提供します:
| 層 | 入力の形 | 誰がマーシャルするか |
|---|---|---|
@aws-sdk/client-dynamodb(低レベル) | DynamoDB JSON の AttributeValue マップ | 自分のコードかヘルパー |
@aws-sdk/lib-dynamodb(ドキュメント) | 素の JS オブジェクト | 送受信時に SDK |
既定はドキュメントクライアントにしましょう。どのコマンドでも Item、Key、そして
ExpressionAttributeValues をマーシャルするので、手書きの更新式 にも素の値を渡せます。生の AttributeValue
マップが必要になるのは、低レベルクライアントを使うときだけです。
式の属性値もマーシャルされる
低レベルクライアントでは、ConditionExpression、UpdateExpression、FilterExpression
のプレースホルダ(:val、:inc)は、ExpressionAttributeValues の中のマーシャル済みの値に対応します:
{
":status": {"S": "open"},
":count": {"N": "1"}
}S のラッパーなしに "open" を送るとリクエストは失敗します。DynamoDB は裸の文字列を属性値として読めないからです。式ビルダー は式の文字列と並んでこのマップを出力するので、プレースホルダと型がずれません。
予約語 と衝突する属性 名 には、代わりに
ExpressionAttributeNames(#st)を使います。チェッカーツールは貼り付けられる形のエイリアスマップを出力します。
テストでのマーシャリングの失敗
- 空のセット: DynamoDB は空の
SS/NS/BSを拒否します。代わりに属性を省きましょう。 Nの中の浮動小数点: ワイヤ上では JSON の数値ではなく文字列として"3.14"を送ります。- Node でのバイナリ: SDK のコードでは
Uint8Array、生の JSON では base64 です。 - undefined の値: ドキュメントクライアントは
undefinedに設定されたトップレベルの属性を取り除きますが、マップやリストの中にあるものにはPass options.removeUndefinedValues=true to remove undefined values from map/array/set.を投げます。 - undefined への対処:
marshall()はトップレベルでも例外を投げるので、上のスニペットのようにremoveUndefinedValues: trueを設定して、すべて取り除きましょう。 - キーの空文字列: 非キー属性では 2020 年から許可されていますが、テーブルとインデックスのキー属性では拒否されます。
- 空のキーへの対処: GSI や LSI のキーなら、
""を書く代わりに属性を省きます。そのアイテムはそのインデックスに入らず(スパースインデックス)、書き込みは成功します。テーブルのキーには、空でない番兵値を使いましょう。
Lambda が生の API レスポンスをログに出しているときは、フィクスチャと差分を取る前にアイテムを1つ DynamoDB JSON コンバータ に貼り付けて、読みやすい素の JSON に戻しましょう。
型タグでアイテムは大きくなる?
ワイヤ上ではそうですが、アイテムとしてはそうではありません。上の監査ログのエントリは素の JSON で 102 バイト、マーシャルすると 138 バイトで、リクエストのペイロードは約35%増えます。
DynamoDB はそのタグを保存も課金もしません。アイテムのサイズは属性名と値の合計なので、同じエントリは 65 バイトで、ブール値のフラグは名前に加えて1バイトしかかかりません。アイテムサイズ上限ガイド に完全な計算があります。
マーシャル済みのアイテムを一括ロードする前に、アイテムサイズ計算機 でサンプルを確認しましょう。
BatchWriteItem は最大 25 件の put または delete リクエストを受け付け、各アイテムは最大
400 KB で、たいていは 25 件という件数が先に効いてきます。
AWS は 16 MB の上限を2通りに書いています。制約のページは "the total size of all the items written" を数え、API リファレンスは "The total request size exceeds 16 MB" のときにバッチを拒否します。後者の読み方では、型タグも数えられます。
DynamoDB Local 3.3.1 はリクエストとしての読み方に従います。それぞれ約 197 KB として課金される 25 アイテム(長い数値のリスト)が 16.8 MB のリクエストになり、拒否されました。
ですから、タグの多いアイテム(長い数値のリスト、多数の小さな属性)は、件数だけでなくシリアライズ後のサイズでも分割しましょう。そうすれば、どちらの読み方でもバッチは上限に収まります。
DynoTable で変換する
アプリでは、アイテムエディタが既定で素の値を表示し、コミット時にマーシャルします。 CloudWatch のログにあったアイテムをデバッグするときは、エディタを DynamoDB JSON ビューに切り替えて正確なタグを確認し、編集するときはプレーン JSON に戻しましょう。
グリッドの右クリックメニューから、形式を選んでコピー → JSON または形式を選んでコピー → DynamoDB-JSON で、チケットやテストのフィクスチャ用にどちらの形式でもクリップボードに置けます。

落とし穴と次のステップ
- DynamoDB JSON では数値は文字列です:
{"N": "3"}。クォートが重要です。裸の数値を出力しないこと。 - セットかリストかはモデリングの判断 で、エンコードがそれを可視化します。
SS/NSのつもりならSetを渡しましょう(データ型 を参照)。 - アプリのコードでは手作業のマーシャリングよりドキュメントクライアントを。
removeUndefinedValuesを有効にし、精度が重要な場面ではwrapNumbersを使います。 - 空のキー属性は省く。
""を書き込まないこと。
型タグを目でデコードする代わりにアイテムを素の値として読むには、 DynoTable をダウンロード して、任意のアイテムをエディタで開きましょう。


