中級読了 2 分

DynamoDB のキー条件式

キー条件式 とは、Query に渡す KeyConditionExpression のことで、リクエストのうち、DynamoDB がアイテムを 見つける のに使う唯一の部分です。それ以外のすべて(フィルタ、射影)は、読み取りがすでに計測された後に動きます。

DynamoDB のキー条件式とは?

キー条件式とは、Query 上の KeyConditionExpression で、DynamoDB にどのアイテムを読むかを伝えるものです。 は等価(PK = :v)でなければならず、 は1つの演算子を取ります: =、<、<=、>、>=、 BETWEEN、begins_with。これは何が読まれ課金されるかを決める点で、フィルタとは異なります。

  • パーティションキーはアドレスです。 DynamoDB はそれをハッシュして1つのパーティションを特定するので、取れるのは = だけです: 範囲も、begins_with も、IN もなし。
  • これはフィルタではありません。 FilterExpression は、読み取りに支払った後で結果を絞るだけです。
  • String と Binary のソートキーはバイト順です。 範囲演算子はそれらを辞書順で比較するので、ソートキーの形式が、どの範囲をクエリできるかを決めます。Number のソートキーは数値的に比較します。

これらの例の値は : プレースホルダーです。その仕組みは式の属性名と値 にあります。

なぜパーティションキーは等価に固定されるのか

DynamoDB は、パーティションキーをハッシュして物理パーティションに割り当ててアイテムを格納します。ハッシュは範囲ではなく1つの場所を与えるので、またいで スキャンするものがありません。

だから PK > :v や begins_with(PK, :v) は端から拒否されます。エンジンは、テーブル全体を読まずに「キーが X で始まるすべてのパーティション」に答えられません。それはまさに、 DynamoDB が避けるために作られた Scan です。

SQL から来ると、これは逆に感じます。WHERE id LIKE 'ticket%' は Postgres では自明です。 DynamoDB では、パーティションキーは検索可能な列ではなくアドレスなのです。

マルチ属性キー(パーティションキー属性とソートキー属性をそれぞれ最大4つ)を持つ GSI では、すべてのパーティションキー属性が = を取り、ソートキー属性は左から右へ連鎖し、範囲を取れるのは最後の1つだけです (AWS: マルチ属性キー)。

ソートキーの演算子

1つのパーティション内では、アイテムは ソートキーでソートされて 格納されます。その順序こそが範囲演算子が活用するものです: DynamoDB はある位置にシークして前方に読みます。

演算子読むもの用途
SK = :v厳密に1つのアイテムキーで指定した特定の子
SK < / <= / > / >= :v片側が開いた1つのスライス「この地点より後のすべて」
SK BETWEEN :a AND :b閉じた範囲(両端を含む)有界な窓、日付範囲
begins_with(SK, :p)プレフィックスのスライスPK 配下の型または階層

キーに LIKE、CONTAINS、ENDS_WITH はありません。部分文字列や接尾辞のマッチングはバイト順ではないので、フル読み取りを強いることになり、API はそれを許しません。

部分文字列なら、contains() は Scan のフィルタ、または値の非キーのコピーに対する Query のフィルタで使えます。Query のフィルタはソートキーを参照できません。

接尾辞なら、反転したコピーを専用の属性(RevEmail、例: moc.elpmaxe@ada)に格納し、それをテナント(または1つの共有バケット)でパーティション分割した GSI のソートキーにして、接尾辞を反転したもの(moc.elpmaxe@)で begins_with(RevEmail, :rsuffix) をクエリします。 (AWS: キー条件式)

具体例: チャットアプリのメッセージ

チャンネルベースのチャットを作っているとします。1つのテーブルを、チャンネルでパーティション分割し、メッセージ時刻でソートします。元のキースキーマ:

  • パーティションキー ChannelRef: CH#{channelId}
  • ソートキー PostedAt: ISO-8601 のタイムスタンプ、MSG#2026-06-23T14:05:00Z

MSG# プレフィックスは、メッセージ行をソート可能に保ち、同じチャンネル配下に同居させる他の行タイプ(たとえば PIN# 配下のピン留めメッセージ)と区別します。

チャンネルの最新メッセージを読み込む。 パーティションキーと MSG# プレフィックスで、新しい順に:

KeyConditionExpression      ChannelRef = :ch AND begins_with(PostedAt, :msg)
ExpressionAttributeValues   { ":ch": { "S": "CH#general" }, ":msg": { "S": "MSG#" } }
ScanIndexForward            false

ScanIndexForward: false は、ソート済みのコレクションを逆向きに歩きます。クライアント側でソートせずに「最新が先頭」を得る安上がりな方法です。プレフィックスを省くと、 PIN# の行も返ってきて、しかもすべてのメッセージより前に来ます。PIN# は MSG# の後にソートされるからです。

begins_with で特定の1日を。 タイムスタンプがソートキーであり、テキストとして格納されるので、日付プレフィックスはきれいなスライスになります。

KeyConditionExpression      ChannelRef = :ch AND begins_with(PostedAt, :day)
ExpressionAttributeValues   { ":ch": { "S": "CH#general" }, ":day": { "S": "MSG#2026-06-23" } }

これは 2026-06-23 のすべてのメッセージを、それ以外は何も読みません。DynamoDB はプレフィックスにシークし、その末尾を外れたところで止まります。これが機能するのは、プレフィックスがバイトソートされた文字列の真の左端アンカーだからです。1時間まるごとも同じように機能します(MSG#2026-06-23T14)。

BETWEEN で厳密な窓を。「14:15 から 14:45 までのメッセージ」に合うプレフィックスはないので、両端を含む範囲を使います。

KeyConditionExpression      ChannelRef = :ch AND PostedAt BETWEEN :lo AND :hi
ExpressionAttributeValues   { ":ch": { "S": "CH#general" },
                              ":lo": { "S": "MSG#2026-06-23T14:15:00Z" },
                              ":hi": { "S": "MSG#2026-06-23T14:45:00Z" } }

BETWEEN は両端を含むので、端点は意図をもって選びましょう。ここでの off-by-one が、端のメッセージをこっそり落としたり二重にしたりします。

DynamoDB Expression Builder は、これらのどれでも ExpressionAttributeValues マップを埋めた状態で組み立てます。下のものは上の1日分のクエリ(ChannelRef = CH#general AND begins_with(PostedAt, MSG#2026-06-23))にプリセットされています。演算子を変えて KeyConditionExpression が更新されるのを見てください。

リクエストを構築
生成されたコード
new QueryCommand({
  "TableName": "ChatMessages",
  "KeyConditionExpression": "#hashKey = :hashKeyValue AND begins_with(#rangeKey, :rangeKeyValue)",
  "ExpressionAttributeNames": {
    "#hashKey": "ChannelRef",
    "#rangeKey": "PostedAt"
  },
  "ExpressionAttributeValues": {
    ":hashKeyValue": {
      "S": "CH#general"
    },
    ":rangeKeyValue": {
      "S": "MSG#2026-06-23"
    }
  }
})

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

罠: キー条件とフィルタを混同する

高くつく間違いは、キーの仕事をさせようと FilterExpression に手を伸ばすことです。Query のフィルタは PostedAt を参照することすらできません: それはソートキーであり、DynamoDB はキー属性へのフィルタを ValidationException で拒否します。

そこで回避策は、日付を素の非キー属性(MessageDate)に複製し、代わりにそれをフィルタすることです。

KeyConditionExpression   ChannelRef = :ch
FilterExpression         begins_with(MessageDate, :day)

これは上記の begins_with キー条件と 同等に見え、同じ行を返しますが、まずチャンネルのパーティション全体 を読み、それからその日以外をすべて捨てます。フル読み取り分を課金されます。

フィルタは読み取りコストを決して減らしません。DynamoDB がアイテムを計測した後に動くのは、フィルタ付き Scan と同じ自爆装置です。述語をキー条件に入れられるなら、そこに属します。

対処は上流にあります。あるアクセスパターンを、1つの PK 等価とソートキーの範囲として表現できないなら、それはモデリングのサインです: フィルタしている属性をソートキーに入れるか、そのパターン用にキー付けしたインデックスを追加します。

フィルタリング戦略 で選択肢を比較しています。キーの並べ方は GSI と LSI とシングルテーブル設計 を参照してください。

DynoTable で見る

実際のチャンネルのパーティションに対して、同じキー条件を実行してみてください。キーピルにパーティションキーの値を設定した瞬間、DynoTable は Query を発行するので、テーブル全体ではなく、そのスライスだけを読み込みます。

落とし穴と次のステップ

  • パーティションキーは常に =。 パーティションをまたぐ範囲には、パーティションキーが少数のシャード値(MSG#0 から MSG#9)で、ソートキーが範囲を取る値である GSI を追加し、各シャードをクエリしてクライアント側でマージします(書き込みシャーディング)。
  • クエリごとにソートキー条件は1つ。 2つのソートキー述語を AND することはできません(マルチ属性の GSI キー では、先頭のソートキー属性に等価、最後の1つに範囲を1つ)。プレフィックスと範囲を組み合わせるには、上の 14:15 から 14:45 の窓のように、プレフィックスを BETWEEN の両方の境界に入れます: PIN# の行は入ってきません。
  • 予約語にはエイリアスが必要です。 Timestamp や Name という名前のキーは ExpressionAttributeNames(#ts)を使わなければならず、さもないとクエリがエラーになります。式の属性名と値 を参照してください。 (AWS: 予約語)
  • BETWEEN は両端を含みます。 両方の端点がマッチするので、それに合わせて境界を設計しましょう。

Query が正しいスライスを読むようになったら、射影式 で返す内容を絞りましょう。キー条件を Expression Builder で下書きし、それから DynoTable を試して、同じ条件をキーピルに設定し、どのスライスが返るかを見てください。

著者: Dmitriy · 更新日