中級読了 2 分

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日後の を設定します。

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 になるのを見てください。

リクエストを構築
生成されたコード
new QueryCommand({
  "TableName": "Articles",
  "KeyConditionExpression": "#hashKey = :hashKeyValue",
  "FilterExpression": "#filter0 = :filterValue0",
  "ExpressionAttributeNames": {
    "#hashKey": "PK",
    "#filter0": "status"
  },
  "ExpressionAttributeValues": {
    ":hashKeyValue": {
      "S": "BLOG#eng"
    },
    ":filterValue0": {
      "S": "published"
    }
  }
})

dynamodb-expression-builder は、このツールの基盤となるオープンソース(MIT)ライブラリです。

ネストした、扱いにくいパスのための名前

# プレースホルダーは予約語を回避する以上のことをします。ドキュメントパス構文はドットとブラケットを使うため、文字どおりドットを含む属性、例えばメタデータキー og.title は、プレースホルダーなしではアドレス指定できません。

ProjectionExpression       #og
ExpressionAttributeNames   { "#og": "og.title" }

それがないと、DynamoDB は og.title を「og マップの中の title フィールド」と読みます。まったく別物です。スペース、ハイフン、先頭の数字を持つ名前も同じ話です。ネストには各セグメントをプレースホルダー化します。#meta.#author で、#meta と #author の両方を定義します。

名前と値、並べて

#name:value
置き換えるもの属性 名属性 値
マップExpressionAttributeNamesExpressionAttributeValues
プレフィックス#:
必要な場面予約語、.、-、スペース常に(インラインリテラルなし)
未定義、未使用、または別のマップValidationExceptionValidationException

静かな失敗は、: であるべきだった # です。ExpressionAttributeNames で #published を published にマップすると、#status = #published は2つの属性を比較する有効なフィルタになります: エラーは出ず、published 属性を持たないアイテムにはマッチしません。

マッチするはずのフィルタが何も返さないなら、値のつもりで書いたすべてのオペランドが : で始まっているか確認しましょう。

落とし穴と次のステップ

  • 使わないプレースホルダーを宣言する。 DynamoDB はどちらのマップでも未使用のエントリを拒否するので、削った句がその値を残し、呼び出しを失敗させることがあります。マップは式の先回りではなく、式から構築しましょう。ビルダーはそれらを歩調を合わせて保ちます。
  • 一度動いたから名前が安全と思い込む。 予約語の衝突は属性ごとです。一律にプレースホルダー化し、当て推量をやめましょう。

すべての式タイプがこれらのマップを使います: 条件式、更新式、キー条件式、射影式 で実際の使われ方を見てください。

記事テーブルに対する DynoTable のフィルタービルダー:BLOG#eng パーティションへの status = published フィルタ。
記事テーブルに対する DynoTable のフィルタービルダー:BLOG#eng パーティションへの status = published フィルタ。

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

著者: Dmitriy · 更新日