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 會走訪一個分割區並掃描它的排序索引鍵範圍，所以鍵條件被限制在能對應到那個結構的操作上。它不可重試 — 請改寫查詢。

為什麼會發生

在鍵上用 contains() — contains() 只能用在 FilterExpression，絕不能用在分割區或排序索引鍵上。
在分割區索引鍵上用非等值運算子 — 分割區索引鍵必須使用 =。在它上面用 begins_with、<、>、BETWEEN 或 <> 都不支援。
在鍵上用 IN 或 <>（不等於） — 兩者都不是支援的鍵運算子；它們都屬於 filter。
在 KeyConditionExpression 中引用非鍵屬性 — 那裡只允許資料表／索引的分割區與排序索引鍵（那個變體是 Query condition missed key schema element）。
在 Number 型排序索引鍵上用 begins_with() — begins_with 只能用在 String 或 Binary 型排序索引鍵上，而且函式名稱區分大小寫（是 begins_with，不是 BEGINS_WITH）。
查詢的 GSI/LSI 其鍵結構與基礎資料表不同，卻誤用了基礎資料表的鍵。

如何修正

分割區索引鍵一律用 =。 Query 需要一個精確的分割區索引鍵；你無法跨分割區做範圍掃描。
把排序索引鍵限制在支援的運算子 — =、<、<=、>、>=、BETWEEN … AND …，或 begins_with(sk, :prefix)。
其他一切都移到 FilterExpression — contains()、<>、IN、子字串比對。（Filter 在讀取之後才執行，而且仍會消耗容量，所以請針對常見的存取模式來設計鍵。）
查詢正確的索引 — 如果你需要不同的存取模式，就新增／查詢一個分割區／排序索引鍵符合你想要條件的 GSI，並傳入它的 IndexName。
在鍵條件中只引用鍵屬性；非鍵的述詞請放進 filter。

常見問題

為什麼會拋出「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 僅在排序索引鍵上合法 — 這才是這個錯誤背後真正的教訓，也是為什麼它通常代表這個存取模式需要不同的鍵設計，而不是不同的運算式。

參考資料

最後於 2026-07-13 對照上方連結的官方 AWS 文件驗證。

已於 2026-07-26 對照 DynamoDB Local 2.x 與 AWS SDK for JavaScript v3.1095.0 重現 — 上方輸出為逐字原文。