DynamoDB の式属性名と値
DynamoDB の式はテンプレートです。プレースホルダーを書き、それから実際の属性名と値を2つのサイドマップで供給します。WHERE status = 'published' のように両方をインライン化する SQL から来ると、これが最初に壊れるところです。
DynamoDB における #name と :value の違いは何ですか?
#name は属性名のプレースホルダーで、ExpressionAttributeNames 経由で供給します。:value は属性値のプレースホルダーで、ExpressionAttributeValues 経由で供給します。予約語や特殊文字を回避するには #name を使い、リテラルにはすべて :value を使います。DynamoDB は値を決してインライン化しないからです。マップにないプレースホルダーは大声で失敗し、マップされた #name として書かれた値は静かに失敗します。
- 値は決してインラインにならない。 素の数値でさえ
:プレースホルダーを得て、値マップで型付けされます。 - 名前にプレースホルダーが必要なのは一部の場合だけ。 予約語、ASCII 英字で始まらない名前、または ASCII 英字・数字・
_以外の文字(ドット、スペース、ハイフン)を含む名前には必須です。すべての名前をエイリアス化するのが安全な習慣です。 - 取り違えが常に大声とは限らない。 値マップの
#キーはValidationExceptionですが、名前としてマップされた#publishedは、何にもマッチしない有効な属性参照です。
なぜ2つのマップが存在するのか
SQL ではクエリ文字列がすべてを運びます。列名、リテラル、演算子。DynamoDB は式の 形 をその データ から意図的に分離します。
値は自身のマップに入るので、DynamoDB は各値を型付け(S、N、BOOL …)でき、パーサーは文字列がどこで終わるかを推測する必要が決してありません。間違えるクオートやエスケープはありません。完全な型タグのリストは DynamoDB のデータ型 を参照してください。
名前も別の理由で同じ扱いを受けます。DynamoDB には長い 予約語 のリストがあり、そのいずれかに一致する属性は、式中で素の名前として現れられません。プレースホルダーが予約を完全に回避します。
予約語の罠
CMS の記事テーブル(パーティションキー BLOG#<blog>、ソートキー ARTICLE#<slug>)があります。その属性は自然に読めますが、たまたま予約語と衝突します。
| 属性 | 予約語? | 保持するもの |
|---|---|---|
status | はい | draft / published |
name | はい | 著者の表示名 |
size | はい | レンダリング後のバイト長 |
ttl | はい | アーカイブ期限(エポック) |
slug | いいえ | URL スラグ |
status、name、size、ttl はすべて AWS の予約語リストにあるため、このフィルタは最初の語で失敗します。
FilterExpression status = :s
DynamoDB は ValidationException を返します: "Attribute name is a reserved keyword;
reserved keyword: status"。修正は名前のプレースホルダーです。
FilterExpression #status = :s
ExpressionAttributeNames { "#status": "status" }
ExpressionAttributeValues { ":s": { "S": "published" } }
slug は予約語では ない ため、slug に対してテストしたクエリは動き、次のも動くと思い込みます。すると status がそれを壊します。リストは573語に及ぶので、覚えようとせず、すべての名前をプレースホルダー化しましょう。そうすれば決して噛まれません。
すべての値を、常にマップする
値は譲れません。インラインリテラルの構文はありません。素の数値でさえプレースホルダーを得ます。この更新は、記事を published に設定し、そのサイズを刻印し、30日後の TTL を設定します。
UpdateExpression: SET #status = :s, #size = :sz, #ttl = :exp
ExpressionAttributeNames: { "#status": "status", "#size": "size", "#ttl": "ttl" }
ExpressionAttributeValues: {
":s": { "S": "published" },
":sz": { "N": "20480" },
":exp": { "N": "1794096000" }
}
:exp は公開時刻に30日を足したエポック秒です(Math.floor(Date.now() / 1000) + 30 * 86400)。示した値は
2026-11-08T00:00:00Z です。
ttl で TTL が有効になっていて、その時刻を過ぎると、DynamoDB は通常数日以内にアイテムを削除します。アーカイブするには、TTL による削除を
DynamoDB Streams から受け取り、古いイメージを S3 に書き込みます。
:sz と :exp は N 文字列として送られます。DynamoDB の数値型はワイヤー上で文字列としてエンコードされるからです。
両方のマップは1つのリクエストに属するので、値を共有できるのはそのリクエストの中だけです:
:s を一度定義し、1つの UpdateItem の UpdateExpression と ConditionExpression の両方で使います(#status <> :s でガードされた SET #status = :s)。
Expression Builder は、式文字列と両方のマップを、型タグを埋めて一緒に生成するので、プレースホルダーが互いにずれることはありません。
下のものは BLOG#eng の記事をクエリし、status = published でフィルタします。すべての名前が ExpressionAttributeNames マップでエイリアス化され、status も #filter0
になるのを見てください。
dynamodb-expression-builder は、このツールの基盤となるオープンソース(MIT)ライブラリです。
ネストした、扱いにくいパスのための名前
# プレースホルダーは予約語を回避する以上のことをします。ドキュメントパス構文はドットとブラケットを使うため、文字どおりドットを含む属性、例えばメタデータキー og.title は、プレースホルダーなしではアドレス指定できません。
ProjectionExpression #og
ExpressionAttributeNames { "#og": "og.title" }
それがないと、DynamoDB は og.title を「og マップの中の title フィールド」と読みます。まったく別物です。スペース、ハイフン、先頭の数字を持つ名前も同じ話です。ネストには各セグメントをプレースホルダー化します。#meta.#author で、#meta と #author の両方を定義します。
名前と値、並べて
#name | :value | |
|---|---|---|
| 置き換えるもの | 属性 名 | 属性 値 |
| マップ | ExpressionAttributeNames | ExpressionAttributeValues |
| プレフィックス | # | : |
| 必要な場面 | 予約語、.、-、スペース | 常に(インラインリテラルなし) |
| 未定義、未使用、または別のマップ | ValidationException | ValidationException |
静かな失敗は、: であるべきだった # です。ExpressionAttributeNames で #published を
published にマップすると、#status = #published は2つの属性を比較する有効なフィルタになります: エラーは出ず、published 属性を持たないアイテムにはマッチしません。
マッチするはずのフィルタが何も返さないなら、値のつもりで書いたすべてのオペランドが : で始まっているか確認しましょう。
落とし穴と次のステップ
- 使わないプレースホルダーを宣言する。 DynamoDB はどちらのマップでも未使用のエントリを拒否するので、削った句がその値を残し、呼び出しを失敗させることがあります。マップは式の先回りではなく、式から構築しましょう。ビルダーはそれらを歩調を合わせて保ちます。
- 一度動いたから名前が安全と思い込む。 予約語の衝突は属性ごとです。一律にプレースホルダー化し、当て推量をやめましょう。
すべての式タイプがこれらのマップを使います: 条件式、更新式、キー条件式、射影式 で実際の使われ方を見てください。

式と両方のマップを Expression Builder で生成しましょう。 DynoTable では、ビジュアルフィルタービルダーが、キー条件とフィルタをコンパイルするときにプレースホルダーを代わりに書きます。


