ValidationException: Query condition missed key schema element

요약 — 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은 정렬 키만 지원합니다).
• 속성 이름에 오타가 있어 스키마와 더 이상 일치하지 않는 경우.

어떻게 해결하는가

1. 파티션 키를 =로 조회하세요. 모든 Query에는 pk = :pk가 필요합니다(테이블의 실제 키 이름 사용).
2. 키가 아닌 속성으로 조회해야 하나요? 그 속성을 파티션 키로 가진 GSI를 만들고 IndexName을 전달하세요.
3. 가끔만 접근하면 되나요? Query 대신 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'}
  })
);

FAQ

"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는 정확히 하나의 파티션 키를 고정해야 합니다. 정렬 키만으로 검색하고 싶다는 것은 그 액세스 패턴에 Query가 아니라 GSI가 필요하다는 전형적인 신호입니다 — 정말로 모든 파티션을 읽어야 한다면 Scan이겠고요.

관련 오류

• 제공된 키 요소가 스키마와 일치하지 않음
• ValidationException(개요)
• 코드 예제: Node.js의 Query · Python(boto3) — 제대로 작성한 KeyConditionExpression.
• 학습: Query vs Scan · 키 조건 표현식

참고 자료

• Query — Amazon DynamoDB API Reference
• Reserved words in DynamoDB — Amazon DynamoDB Developer Guide
• Using Global Secondary Indexes in DynamoDB — Amazon DynamoDB Developer Guide

위에 링크된 공식 AWS 문서를 기준으로 2026-07-13에 마지막으로 검증했습니다.

2026-07-26에 DynamoDB Local 2.x와 AWS SDK for JavaScript v3.1095.0으로 재현했습니다 — 위 출력은 그대로 옮긴 것입니다.