😺

ProjectionExpression / FilterExpression / ConditionExpress の違いを整理してみた

に公開
AWS
DynamoDB
tech

はじめに

DynamoDB を触っていると、やたらと出てくるのが、ProjectionExpression、FilterExpression、ConditionExpression です。

この3つ。名前が似ているせいで「どれが何だっけ？」となる人も多いと思います。
今日はそれぞれの役割と違いを整理してみます。

ProjectionExpression とは？

一言でいうと 「返す属性を絞る」 ための仕組みです。例えばユーザーテーブルにこんなデータがあったとします。

{
  "UserId": "u001",
  "Name": "Taro",
  "Email": "taro@example.com",
  "CreatedAt": "2025-09-20"
}

普通に GetItem すると、全部の属性が返ってきます。
でも「UserId と Name だけ欲しい」といったケース、ありますよね？

そんなときに使うのが ProjectionExpression です。

ProjectionExpression: "UserId, Name"

結果は下記の通りです。

{
  "UserId": "u001",
  "Name": "Taro"
}

SQL で言うところの SELECT UserId, Name FROM Users のようなイメージです。

また、ProjectionExpression が使用可能なAPIは、GetItem、Query、Scan などがあり、書き込み系（PutItem, UpdateItem, DeleteItem）では、使用できません。

FilterExpression とは？

次に 「条件で結果を絞る」 のが FilterExpression です。例えば「年齢が20歳以上のユーザーだけ欲しい」とします。

FilterExpression: "Age >= :minAge",
ExpressionAttributeValues: { ":minAge": 20 }

すると、クエリの結果のうち Age >= 20 のレコードだけが返ります。
ただし、注意点があります。
DynamoDB の FilterExpression は データを読み込んだあとでフィルタリング します。
つまり、余計なデータも一度は読み込んで課金対象になります。SQL の WHERE に近いけど、内部処理はちょっと違うので要注意です。

また、FilterExpression が使用可能なAPIは、Query、Scan などがあり、GetItem や 書き込み系（PutItem, UpdateItem, DeleteItem）では使用できません。

ConditionExpression とは？

最後に 「書き込み条件をチェックする」 のが ConditionExpression です。例えば、ユーザーを新規登録したいけど、すでに同じ UserId が存在するなら失敗させたいときに使用すると良いです。

ConditionExpression: "attribute_not_exists(UserId)"

これを指定すると、もし UserId がすでに存在していたら PutItem はエラーになります。
つまり「条件を満たさなければ書き込みしない」という制御ができるわけです。
これは 競合回避 や 楽観的ロック を実現するためにめちゃくちゃ重要な機能です。

また、ConditionExpression が使用可能なAPIは、PutItem、UpdateItem、DeleteItem などがあり、読み取り系（GetItem, Query, Scan）では使用できません。

まとめ

今まで紹介した ProjectionExpression、FilterExpression、ConditionExpression の違いをざっくりまとめると下記の通りです。

種類 役割 SQLに例えると 主な利用シーン
ProjectionExpression 返す属性を絞る SELECT カラム レスポンスを軽量化したい
FilterExpression 読み込み結果をフィルタ WHERE（ただし読んでから絞る） 条件に合うデータだけ返したい
ConditionExpression 書き込み条件を制御 UPDATE ... WHERE 条件 競合回避や条件付き更新

まとめると、Projection → どれを返すか、Filter → 返す前に落とす、Condition → そもそも書き込みするかどうか という認識でいると良いかと思います。

また、各オプション（ProjectionExpression、FilterExpression、ConditionExpression）が、どのAPIであれば使用可能かどうかということを表した表が下記になります。

Expression GetItem Query Scan PutItem UpdateItem DeleteItem
ProjectionExpression ✅ ✅ ✅ ❌ ❌ ❌
FilterExpression ❌ ✅ ✅ ❌ ❌ ❌
ConditionExpression ❌ ❌ ❌ ✅ ✅ ✅

Discussion