DynamoDBコマンドでのexpression-attribute-namesとexpression-attribute-valuesの使いどころを整理してみた

2020.07.16

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

こんにちは、CX事業本部の若槻です。

DynamoDBへのコマンドアクセスでよく使われるパラメータとして

  • expression-attribute-names
  • expression-attribute-values

というものがあります。どちらもとても便利なパラメータなのですが、名前が似ているせいか用途を混同してしまったりする時があります。

そこで今回は、DynamoDBへのコマンドによるアクセスでの上記2パラメータの使いどころを整理してみました。

expression-attribute-valuesの使い所

このパラメータはDynamoDBコマンドでテーブルにアクセスする際にfilter-expressionkey-condition-expressionなどのパラメータで属性値の比較を行いたい場合に使用します。

使い方としては、expression-attribute-valuesパラメータにより、属性値を:から始まる任意の英数字のプレースホルダーで置き換えます。

例えば下記のように、コマンドにおいてキー属性objectIdの値の一致の指定はkey-condition-expression内では直接できず、プレースホルダー:idのように置き換えて指定する必要があります。

$ aws dynamodb query --table-name object \
  --key-condition-expression "objectId = :id" \
  --expression-attribute-values '{":id":{"S":"g0001"}}'

複数の値を使用する場合は下記のようになります。

$ aws dynamodb query --table-name object \
  --key-condition-expression "objectId = :id" \
  --filter-expression "objectType = :type" \
  --expression-attribute-values '{":id":{"S":"g0001"}, ":type":{"S":"user"}}'

expression-attribute-namesの使い所

このパラメータはDynamoDBコマンドでテーブルにアクセスする際にkey-condition-expressionprojection-expressionなどのパラメータでAWSの定めた予約語またはドット.の含まれた属性を指定したい場合に使用します。

使い方としては、expression-attribute-namesパラメータにより、属性値を#から始まる任意の英数字のプレースホルダーで置き換えます。

例えば下記のように、属性名agent(予約語)をクエリでの検索キーに使用したい場合、key-condition-expressionに直接指定するとAttribute name is a reserved keywordというエラーとなります。

$ aws dynamodb query \
  --table-name sample \
  --key-condition-expression "agent = :a" \
  --expression-attribute-values  '{":a":{"S":"maguire"}}'

An error occurred (ValidationException) when calling the Query operation: Invalid KeyConditionExpression: Attribute name is a reserved keyword; reserved keyword: agent

そこで下記のようにexpression-attribute-namesagent#aに置き換えてやることによりクエリの検索キーに使用できるようになります。

$ aws dynamodb query \
  --table-name sample \
  --key-condition-expression "#a = :a" \
  --expression-attribute-values '{":a":{"S":"maguire"}}'
  --expression-attribute-names '{"#a":"agent"}'

一方、同じ検索キーへの指定であってもget-itemコマンドのkeyパラメータのようにマップでの指定あれば直接指定は可能です。

$ aws dynamodb get-item \
  --table-name sample \
  --key '{"agent":{"S":"maguire"},"datetime":{"N":"11111111"}}'

しかし、get-itemコマンドであってもprojection-expressionパラメータなどでの文字列での指定であれば、expression-attribute-namesによる置き換えをしなければエラーとなります。

$ aws dynamodb get-item \
  --table-name sample \
  --key '{"agent":{"S":"maguire"},"datetime":{"N":"11111111"}}' \
  --projection-expression "agent"

An error occurred (ValidationException) when calling the GetItem operation: Invalid ProjectionExpression: Attribute name is a reserved keyword; reserved keyword: agent

おわりに

Dynamoコマンドでのexpression-attribute-namesとexpression-attribute-valuesの使いどころを整理してみました。

最近プロジェクトこれらパラメータを使う機会があったので良い復習になりました。

参考