Query key condition not supported

요약 — 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이나 <>(같지 않음) — 둘 다 지원되는 키 연산자가 아니며, 필터에 속합니다.
• KeyConditionExpression에서 키가 아닌 속성을 참조 — 거기에는 테이블/인덱스의 파티션 키와 정렬 키만 허용됩니다(그 경우는 Query condition missed key schema element입니다).
• Number 정렬 키에 대한 begins_with() — begins_with는 String 또는 Binary 정렬 키에서만 동작하며, 함수 이름은 대소문자를 구분합니다(BEGINS_WITH가 아니라 begins_with).
• 기본 테이블과 키 스키마가 다른 GSI/LSI를 조회하면서 실수로 기본 테이블의 키를 쓰는 경우.

어떻게 해결하는가

1. 파티션 키에는 항상 =를 쓰세요. Query에는 정확한 파티션 키가 필요하며, 여러 파티션에 걸친 범위 스캔은 할 수 없습니다.
2. 정렬 키는 지원되는 연산자로 제한하세요 — =, <, <=, >, >=, BETWEEN … AND …, begins_with(sk, :prefix).
3. 그 밖의 것은 모두 FilterExpression으로 옮기세요 — contains(), <>, IN, 부분 문자열 매칭. (필터는 읽기 이후에 적용되며 여전히 용량을 소비하므로, 자주 쓰는 액세스 패턴에 맞게 키를 설계하세요.)
4. 올바른 인덱스를 조회하세요 — 다른 액세스 패턴이 필요하다면 원하는 조건에 맞는 파티션/정렬 키를 가진 GSI를 추가해 조회하고 IndexName을 전달하세요.
5. 키 조건에서는 키 속성만 참조하고, 키가 아닌 조건은 필터에 두세요.

FAQ

"Query key condition not supported"는 왜 발생하나요? KeyConditionExpression이 키 스키마가 평가할 수 없는 연산자를 사용한 경우입니다 — 예를 들어 키에 대한 contains(), 또는 파티션 키에 대한 부등호나 begins_with 등입니다. 파티션 키는 등호만 허용하고, 정렬 키는 제한된 비교 연산만 허용합니다. 그 밖의 것은 FilterExpression으로 옮겨야 합니다.

DynamoDB Query에서 contains()를 쓸 수 있나요? KeyConditionExpression이 아니라 FilterExpression에서만 가능합니다. 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은 정렬 키에서만 유효합니다 — 이것이 이 오류가 주는 진짜 교훈이며, 이 오류가 보통 다른 표현식이 아니라 다른 키 설계가 필요하다는 뜻인 이유입니다.

관련 오류

• Query condition missed key schema element — 키 조건에 키가 아닌 속성이 있거나 파티션 키가 빠진 경우.
• ValidationException(개요)
• 코드 예제: Node.js의 Query · Python(boto3) — 동작하는 코드 속 유효한 키 조건.
• 학습: 키 조건 표현식 · Query vs Scan · 인덱스(Indexes)

참고 자료

• Query — Amazon DynamoDB API Reference
• Working with queries in DynamoDB — Amazon DynamoDB Developer Guide
• Constraints in Amazon DynamoDB — Amazon DynamoDB Developer Guide
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

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

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