Query key condition not supported

TL;DR — 你的 KeyConditionExpression 用了键 schema 不允许的运算符。分区键只支持相等（=）。排序键支持 =、<、<=、>、>=、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 或 <>（不等于）——两者都不是受支持的键运算符；它们都属于过滤条件。
在 KeyConditionExpression 里引用了非键属性——那里只允许表/索引的分区键和排序键（这个变体是 Query condition missed key schema element）。
在 Number 类型的排序键上用 begins_with()——begins_with 只对 String 或 Binary 排序键有效，而且函数名区分大小写（是 begins_with，不是 BEGINS_WITH）。
查询的 GSI/LSI 键 schema 与基表不同，你却误用了基表的键。

如何修复

在分区键上永远用 =。Query 需要一个精确的分区键；你没法跨分区做区间扫描。
把排序键限制在受支持的运算符内——=、<、<=、>、>=、BETWEEN … AND …，或者 begins_with(sk, :prefix)。
其他一切都挪到 FilterExpression——contains()、<>、IN、子串匹配。（过滤发生在读取之后，并且仍然消耗容量，所以要针对常见访问模式来设计键。）
查询正确的索引——如果你需要另一种访问模式，就新建/查询一个分区键与排序键匹配你想要的条件的 GSI，并传入它的 IndexName。
键条件里只引用键属性；把非键谓词放进过滤条件。

常见问题

为什么会抛出 "Query key condition not supported"？ KeyConditionExpression 用了键 schema 无法求值的运算符——比如在键上用 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 复现——上方输出为原样照录。