初級読了 2 分

DynamoDB の射影式 (Projection Expression)

射影式は DynamoDB の SELECT col1, col2 です。カンマ区切りの名のリストで、GetItem、Query、Scan にアイテム全体ではなくそれらの属性だけを返すよう伝えます。

DynamoDB の射影式は読み取りコストを削減しますか?

いいえ。ProjectionExpression はレスポンスのペイロードを削りますが、課金される読み取りキャパシティは削りません。DynamoDB はアイテム全体を読み取り、アイテムの全体サイズでを計量し、それから指定しなかった属性を出力の途中で落とします。読み取りコストを削るには、代わりにカバリングを使います。

  • アクセス制御ではない。 射影を選ぶのは呼び出し元であり、射影のない読み取りはすべての属性を返します。ロールが読めるものを強制するのは、dynamodb:Attributes と dynamodb:Select に対する IAM 条件です。
  • 予約語になりうるものには #name プレースホルダを使う。 式の中の素の属性名は、 DynamoDB の約 570 の予約語と衝突し、リクエストを失敗させます。
  • 読み取りの節約には、代わりにカバリングインデックスを使う。 必要な属性だけを射影する は、それ自身の (より小さい) サイズで読まれます。

実際に何を節約するのか

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 が変わる様子を見てみましょう。

リクエストを構築
生成されたコード
new GetItemCommand({
  "TableName": "Profiles",
  "Key": {
    "PK": {
      "S": "PROFILE#ada"
    },
    "SK": {
      "S": "PROFILE#ada"
    }
  },
  "ProjectionExpression": "#proj0, #proj1, #proj2",
  "ExpressionAttributeNames": {
    "#proj0": "displayName",
    "#proj1": "avatarUrl",
    "#proj2": "bio"
  }
})

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 は何を射影しても返ってきます。
  • カバリングインデックスに手を伸ばすのは、ホットなパターンが大きなアイテムから少数のフィールドを読むときだけ。まず書き込みとストレージのコストを天秤にかけましょう。
DynoTable で公開プロフィールの 3 フィールドを PartiQL で SELECT したところ。
DynoTable で公開プロフィールの 3 フィールドを PartiQL で SELECT したところ。

射影は、キー条件がすでに読み取ったものを削ります。ProjectionExpression とその属性名マップは式ビルダーで組み立てましょう。DynoTable では、同じ列リストを PartiQL の SELECT displayName, avatarUrl, bio として実行できます。


  1. AWS DynamoDB デベロッパーガイド、Using projection expressions in DynamoDB。読み取りキャパシティは、いかなる ProjectionExpression が適用される前のアイテムサイズに基づく。https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html ↩
  2. AWS DynamoDB デベロッパーガイド、Reserved Words in DynamoDB。https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ReservedWords.html ↩
  3. AWS DynamoDB デベロッパーガイド、Attribute Projections (KEYS_ONLY / INCLUDE / ALL)。https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html ↩

著者: Dmitriy · 更新日