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）。
屬性名稱打錯字，因此不再與結構相符。

如何修正

用 = 對分割區索引鍵做 Query。 每次 Query 都需要 pk = :pk（用你資料表真正的鍵名）。
需要用非鍵屬性查詢？ 建立一個以該屬性為分割區索引鍵的 GSI，並傳入 IndexName。
只是偶爾需要存取？ 改用帶 FilterExpression 的 Scan 而不是 Query — 但要注意 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 重現 — 上方輸出為逐字原文。