ValidationException: Query condition missed key schema element

TL;DR — 你的 KeyConditionExpression 必须包含一个对分区键的相等（=）条件。如果你要按非键属性查询，就需要在一个以该属性为键的 GSI/LSI 上做 Query——或者用带 FilterExpression 的 Scan。

含义

完整消息通常是：

ValidationException: Query condition missed key schema element: pk

冒号后面的名字是你这张表的分区键属性，所以它会随表而变。

Query 只能作用在键上。DynamoDB 是在告诉你：KeyConditionExpression 要么完全没有包含分区键，要么点名了一个既不是表（也不是你正在查询的索引）的分区键、也不是排序键的属性。

为什么会发生

KeyConditionExpression 过滤的是一个普通属性（例如 email、status），而不是分区键。
你查询的是基表，但那个属性只是某个 GSI 上的键——你忘了传 IndexName。
分区键在，但用的运算符不是 =（分区键必须精确匹配；只有_排序_键支持 <、>、begins_with、between）。
属性名拼错了，于是它不再与 schema 匹配。

如何修复

用 = 对分区键做查询。每次 Query 都需要 pk = :pk（用你表里真实的键名）。
需要按非键属性查询？创建一个以该属性为分区键的 GSI，并传入 IndexName。
只是偶尔需要访问？改用带 FilterExpression 的 Scan——但要注意 Scan 会读取整张表。

示例

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient, QueryCommand} from '@aws-sdk/lib-dynamodb';

const doc = DynamoDBDocumentClient.from(new DynamoDBClient({}));

// Query the base table by its partition key:
await doc.send(
  new QueryCommand({
    TableName: 'Orders',
    KeyConditionExpression: 'pk = :pk',
    ExpressionAttributeValues: {':pk': 'USER#123'}
  })
);

// Query by a non-key attribute → use a GSI that keys on it
// ("status" is a DynamoDB reserved word, so alias it with #status):
await doc.send(
  new QueryCommand({
    TableName: 'Orders',
    IndexName: 'byStatus',
    KeyConditionExpression: '#status = :s',
    ExpressionAttributeNames: {'#status': 'status'},
    ExpressionAttributeValues: {':s': 'SHIPPED'}
  })
);

常见问题

"Query condition missed key schema element" 是什么意思？ 你的 KeyConditionExpression 要么完全没有包含分区键，要么点名了一个既不是你所查询的表或索引的分区键、也不是其排序键的属性。每次 Query 都需要一个对分区键的相等条件。

我该怎么按非键属性查询 DynamoDB？ 创建一个以该属性为分区键的 GSI，并在 Query 中传入 IndexName——或者，对于偶尔的访问，用带 FilterExpression 的 Scan，但要记住 Scan 会读取整张表。

复现方法

一个条件里只点名了排序键的 Query：

await client.send(
  new QueryCommand({
    TableName: 'orders',
    KeyConditionExpression: 'sk = :s',
    ExpressionAttributeValues: {':s': {S: 'META'}}
  })
);

实际输出：

ValidationException: Query condition missed key schema element
HTTP 400

每个 Query 都必须钉死恰好一个分区键。想只按排序键搜索，是这个访问模式需要一个 GSI 而不是 Query 的典型信号——又或者，如果你确实必须读遍每个分区，那就用 Scan。

参考资料

最后核实于 2026-07-13，依据上方链接的 AWS 官方文档。

2026-07-26 针对 DynamoDB Local 2.x 与 AWS SDK for JavaScript v3.1095.0 复现——上方输出为原样照录。