DynamoDB の射影式 (Projection Expression)
射影式は DynamoDB の SELECT col1, col2 です。カンマ区切りの属性名のリストで、GetItem、Query、Scan にアイテム全体ではなくそれらの属性だけを返すよう伝えます。
DynamoDB の射影式は読み取りコストを削減しますか?
いいえ。ProjectionExpression はレスポンスのペイロードを削りますが、課金される読み取りキャパシティは削りません。DynamoDB はアイテム全体を読み取り、アイテムの全体サイズでRCUを計量し、それから指定しなかった属性を出力の途中で落とします。読み取りコストを削るには、代わりにカバリングGSIを使います。
- アクセス制御ではない。 射影を選ぶのは呼び出し元であり、射影のない読み取りはすべての属性を返します。ロールが読めるものを強制するのは、
dynamodb:Attributesとdynamodb:Selectに対する IAM 条件です。 - 予約語になりうるものには
#nameプレースホルダを使う。 式の中の素の属性名は、 DynamoDB の約 570 の予約語と衝突し、リクエストを失敗させます。 - 読み取りの節約には、代わりにカバリングインデックスを使う。 必要な属性だけを射影する GSIは、それ自身の (より小さい) サイズで読まれます。
実際に何を節約するのか
SQL から来ると、SELECT a, b は SELECT * より少なくスキャンすると思い込むでしょう。
DynamoDB ではその直感は誤りです。
読み取りのキャパシティは、射影が適用される前のアイテムの全体サイズから計算されます。
GetItem ではアイテムごとに 4 KB に切り上げ、Query や Scan では合計サイズに対して切り上げます(サイズはアイテムサイズ計算ツールで確認できます)。AWS は明言しています。ProjectionExpression はリクエストが消費する読み取りキャパシティを変えません。1
ですから射影が節約するのは2つのことで、どちらも読み取りの下流です。
- ワイヤー上のバイト。 6 KB のアイテムが2つの小さな属性として返されれば、レスポンスはちっぽけです。数百のアイテムを返す
Queryでは、それがすぐに積み上がります。 - クライアント側の作業。 デシリアライズするものが少なく、メモリに保持するものが少なく、うっかりログや API レスポンスに漏らすものが少なくなります。
節約しないのは RCU です。読み取りは射影が実行される前に計量されるので、射影で請求が下がることは決してありません。射影を追加しても数字が動かなかったなら、それが文書化された挙動です。
公開ユーザープロフィールを射影する
ユーザーディレクトリを運営しているとします。各プロフィールは1つのアイテムで、ハンドルで人を取得できるようにキーイングされています。
PK = "PROFILE#ada" (partition key)
SK = "PROFILE#ada" (sort key, single-item collection)
そのアイテムは太っています。アカウントの公開の顔に加えて、非公開で運用上の属性の山を運びます。
{
"PK": "PROFILE#ada",
"SK": "PROFILE#ada",
"displayName": "Ada L.",
"avatarUrl": "https://cdn.example.com/u/ada.png",
"bio": "Builds things.",
"emailAddress": "ada@example.com",
"passwordResetToken": "…",
"billingCustomerId": "cus_…",
"lastLoginIp": "…",
"internalRiskScore": 0.02
}公開プロフィールカードには3つのフィールドが必要です。アイテム全体を取得すると、
emailAddress、lastLoginIp、internalRiskScore が、それらを決して見るべきでないコンテキストへ渡ってしまいます。公開サブセットだけを指定しましょう。
GetItem PK = "PROFILE#ada" SK = "PROFILE#ada"
ProjectionExpression: displayName, avatarUrl, bio
レスポンスは3つの属性を運びます。非公開のものはそもそもレスポンスにシリアライズされないので、このコードパスがそれらをログや下流の API に漏らすことはありえません。
それが守るのはあなたのコードであって、テーブルではありません。GetItem を許可された呼び出し元なら誰でも、射影を外してすべてを読めます。
境界を強制するには、IAM ポリシーを使います。dynamodb:Attributes はロールが要求できる属性を列挙し、dynamodb:Select を SPECIFIC_ATTRIBUTES に設定すると、すべての読み取りにそれらの指定を強制します。
Select パラメータを持たない GetItem でも同じです。AWS はこのキーを、アイテムの属性を返すすべての操作に適用し、属性を何も指定しない読み取りは ALL_ATTRIBUTES として扱われます。読み取り専用のロールでは、AWS の読み取り専用の例と同じく、条件を StringEqualsIfExists
ではなく StringEquals で書いてください。
Select 条件がなければ、射影のない読み取りは依然としてアイテム全体を返します。(AWS: きめ細かなアクセス制御)
DynamoDB 式ビルダーは、ProjectionExpression、その ExpressionAttributeNames のマップ、そして SDK 呼び出しを生成します。下のプリセットは上のプロフィールカード用の GetItem です。フィールドを追加または削除して、ProjectionExpression
が変わる様子を見てみましょう。
dynamodb-expression-builder は、このツールの基盤となるオープンソース(MIT)ライブラリです。
# プレースホルダで予約語をエスケープする
status のような予約語を指定した射影は拒否されるので、2
式属性名でエイリアスを付けます。ネストされたパスはセグメントごとにプレースホルダを取り、リストの要素はインデックスを取ります。
ProjectionExpression displayName, #s, #addr.#city, tags[0]
ExpressionAttributeNames { "#s": "status", "#addr": "address", "#city": "city" }
仕組みは式の名前と値で説明しています。予約語チェッカーは、名前のリストの中の衝突を指摘し、エイリアスマップを出力します。
カバリングインデックスが射影に勝るとき
ペイロードだけでなく読み取りコストを削るには、読み取る属性だけを射影するグローバルセカンダリインデックスを使います。それに対する Query は、インデックスエントリのより小さいサイズで計量されます。3
プロフィールカードなら、同じ PK をキーとし、
Projection: { ProjectionType: "INCLUDE", NonKeyAttributes: ["displayName", "avatarUrl", "bio"] }
を持つ GSI です。
注意点が2つあります。GetItem は GSI を読めないので、参照はインデックスに対する Query になります。また GSI の読み取りは結果整合性のみなので、保存したばかりのプロフィールが一瞬古く読めることがあります(GSI の読み取りが古くなりうるとき)。
ProjectionExpression | カバリング GSI | |
|---|---|---|
| ペイロードを削る | はい | はい |
| 読み取りコストを削る | いいえ | はい、インデックスのサイズで読む |
| 追加のストレージ | なし | 射影したフィールドの2つ目のコピー |
| 追加の書き込みコスト | なし | 書き込みがインデックスに伝播する |
| 最適な用途 | レスポンスを削る。小さな勝利 | 大きなアイテムから少数のフィールドをホットに読む |
インデックスは、読み取りキャパシティを節約するために、ストレージと書き込みキャパシティを費やします。重いアイテムから薄いスライスを頻繁に読むなら見合います。一度きりの GetItem
のためには見合いません。
KEYS_ONLY、INCLUDE、ALL の比較はインデックス射影で扱っています。インデックスを使わないなら、太ったアイテムを小さな公開アイテムと非公開アイテムに分割し、必要な方だけを読みましょう。
落とし穴と次のステップ
- 請求が小さくなると期待しない。 射影だけでは RCU は決して変わりません。数字が動かなかったなら、それはバグではなく文書化された挙動です。
- 予約語をプレースホルダ化する。 式の中の素の
nameやstatusはリクエストを失敗させるので、#でマッピングしましょう。 - アイテムを再取得または更新するなら、キー属性を含める。 ページングには不要です。
LastEvaluatedKeyは何を射影しても返ってきます。 - カバリングインデックスに手を伸ばすのは、ホットなパターンが大きなアイテムから少数のフィールドを読むときだけ。まず書き込みとストレージのコストを天秤にかけましょう。

射影は、キー条件がすでに読み取ったものを削ります。ProjectionExpression とその属性名マップは式ビルダーで組み立てましょう。DynoTable では、同じ列リストを PartiQL の
SELECT displayName, avatarUrl, bio として実行できます。
- AWS DynamoDB デベロッパーガイド、Using projection expressions in DynamoDB。読み取りキャパシティは、いかなる
ProjectionExpressionが適用される前のアイテムサイズに基づく。https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html ↩ - AWS DynamoDB デベロッパーガイド、Reserved Words in DynamoDB。https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ReservedWords.html ↩
- AWS DynamoDB デベロッパーガイド、Attribute Projections (
KEYS_ONLY/INCLUDE/ALL)。https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html ↩


