Query key condition not supported

TL;DR — KeyConditionExpression が、キースキーマの許さない演算子を使いました。パーティションキーは等価比較（=）だけをサポートします。ソートキーは =、<、<=、>、>=、BETWEEN、begins_with() をサポートしますが、contains()、<>、IN、パーティションキーに対する begins_with は使えません。それ以外は FilterExpression に移してください。

意味

ValidationException: Query key condition not supported

この ValidationException（HTTP 400）は、キーに付けた条件が、ソートされたキー構造に対して DynamoDB が評価できるものではないことを意味します。Query は1つのパーティションを辿り、そのソートキーの範囲を走査するため、キー条件はその構造に対応づく操作に制限されます。リトライ不可 です — クエリを書き直してください。

発生する理由

• キーに対する contains() — contains() は FilterExpression でのみ機能し、パーティションキーにもソートキーにも使えません。
• パーティションキーに対する非等価演算子 — パーティションキーは = を使わなければなりません。begins_with、<、>、BETWEEN、<> は非対応です。
• キーに対する IN や <>（等しくない） — どちらもサポートされるキー演算子ではなく、両方ともフィルタに属します。
• KeyConditionExpression で キー以外の属性を参照している — そこに書けるのはテーブル/インデックスのパーティションキーとソートキーだけです（そのバリエーションが Query condition missed key schema element です）。
• 数値型のソートキーに対する begins_with() — begins_with は文字列またはバイナリのソートキーでのみ機能し、関数名は大文字小文字を区別します（BEGINS_WITH ではなく begins_with）。
• ベーステーブルとキースキーマが異なる GSI/LSI に対するクエリ で、誤ってベーステーブルのキーを使っている。

修正方法

1. パーティションキーには常に = を使います。 Query には正確なパーティションキーが必要で、パーティションをまたいで範囲走査することはできません。
2. ソートキーはサポートされた演算子に限ります — =、<、<=、>、>=、BETWEEN … AND …、begins_with(sk, :prefix)。
3. それ以外はすべて FilterExpression に移します — contains()、<>、IN、部分文字列一致など。（フィルタは読み取りの後に走り、それでもキャパシティを消費するので、よくあるアクセスパターンに合わせてキーを設計しましょう。）
4. 正しいインデックスをクエリします — 別のアクセスパターンが必要なら、望む条件に合うパーティションキー/ソートキーを持つ GSI を追加してクエリし、その IndexName を渡します。
5. キー条件では キー属性だけを参照し、キー以外の述語はフィルタに入れます。

よくある質問

「Query key condition not supported」はなぜ発生しますか？ KeyConditionExpression が、キースキーマでは評価できない演算子を使いました — キーに対する contains()、あるいはパーティションキーに対する不等号や begins_with などです。パーティションキーは等価比較のみ、ソートキーは限られた比較のみを許します。それ以外は FilterExpression に移す必要があります。

DynamoDB の Query で contains() は使えますか？ FilterExpression でのみ使えます。KeyConditionExpression では使えません。contains() は有効なキー演算子ではありません。部分文字列一致をアクセスパターンとして必要とするなら、begins_with() で辿れるソートキーにモデル化するか、GSI を使ってください。

再現方法

パーティションキーに begins_with を使う Query です。

await client.send(
  new QueryCommand({
    TableName: 'orders',
    KeyConditionExpression: 'begins_with(pk, :p)',
    ExpressionAttributeValues: {':p': {S: 'ORDER#'}}
  })
);

実際の出力:

ValidationException: Query key condition not supported
HTTP 400

パーティションキーは等価比較しか受け付けず、それ以外は一切受け付けません。begins_with、<、>、BETWEEN が正当なのはソートキーだけです — それがこのエラーの背後にある本当の教訓であり、たいていは式ではなくキー設計を変える必要があることを意味します。

関連するエラー

• Query condition missed key schema element — キー条件にキー以外の属性がある、またはパーティションキーが欠けている。
• ValidationException (overview)
• Code example: Query in Node.js · in Python (boto3) — 動くコードの中の有効なキー条件。
• Learn: Key condition expressions · Query vs Scan · インデックス (Indexes)

参考資料

• Query — Amazon DynamoDB API Reference
• Working with queries in DynamoDB — Amazon DynamoDB Developer Guide
• Constraints in Amazon DynamoDB — Amazon DynamoDB Developer Guide
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。

2026-07-26 に DynamoDB Local 2.x と AWS SDK for JavaScript v3.1095.0 で再現しました — 上記の出力はそのままの逐語です。