필터 표현식에는 기본 키가 아닌 속성만 포함될 수 있습니다.

TL;DR — 쿼리 중인 테이블이나 인덱스의 기본 키 속성(파티션 키 또는 정렬 키)을 FilterExpression 안에 넣습니다. DynamoDB는 다음을 금지합니다. 키 속성은 KeyConditionExpression에 들어가고 필터는 키가 아닌 속성만 참조할 수 있습니다. 키 조건이 속한 곳으로 이동합니다.

무엇을 의미하는가

ValidationException: Filter Expression can only contain non-primary key attributes:
Primary key attribute: <name>

# what the engine actually returns, reproduced against DynamoDB Local:
ValidationException: Filter Expression can only contain non-primary key attributes: Primary key attribute: pk

FilterExpression는 항목을 읽은 **후** 실행하여 원하지 않는 행을 삭제합니다. KeyConditionExpression은 **전에** 실행되어 키로 읽을 항목을 선택합니다. 필터에서 파티션/정렬 키를 참조하면 이러한 역할이 혼합되므로 DynamoDB는 재구성할 때까지 **클라이언트 측이며 재시도할 수 없음** HTTP 400 ValidationException`로 이를 거부합니다.

왜 발생하는가

필터로 작성된 키 조건 — FilterExpression: 'sk = :v' 여기서 sk는 정렬 키입니다. KeyConditionExpression에 속합니다.
인덱스 키 필터링 — GSI/LSI를 Query할 때 해당 인덱스의 자체 파티션/정렬 키는 이 쿼리에 대한 "기본 키 속성"이며 필터에 나타날 수 없습니다.
필터링된 속성 하나가 키인 쿼리에 스캔 필터를 복사하여 붙여넣기.
정렬 키에 두 번째 조건을 키 조건으로 표현하는 대신 필터(예: 범위)를 통해 추가하려고 합니다.

어떻게 해결하는가

주요 조건을 KeyConditionExpression로 이동합니다:

KeyConditionExpression: 'pk = :pk AND begins_with(sk, :prefix)',
// FilterExpression: only NON-key attributes, e.g. 'status = :active'

올바른 색인을 사용하세요. 키가 아닌 속성을 필터링/선택해야 하는 경우 이를 GSI의 파티션/정렬 키로 모델링하고 해당 색인을 키별로 쿼리하세요.
키가 아닌 속성에 대해서만 필터를 유지 - 결과를 잘라내지만 검색된 모든 항목에 대해 읽기 용량을 계속 소비하므로 선택 시 키/인덱스에 의존합니다.
GSI를 쿼리하시나요? 주요 속성은 필터에서도 제한되지 않습니다. 키 조건에서 조건을 지정하세요.
생성된 요청을 감사합니다. KeyConditionExpression과 FilterExpression을 함께 기록합니다. 필터의 주요 속성은 스캔 코드에서 흔히 발생하는 복사-붙여넣기 실수입니다.

DynoTable에서 실행

DynoTable의 쿼리 패널은 키 조건과 필터를 별도의 필드에 유지합니다. 파티션 및 정렬 키 제약 조건은 FilterExpression에 절대 포함되지 않습니다. ⌘K가 있는 테이블을 열고 키 조건을 설정한 다음 키가 아닌 필터를 추가합니다. 생성된 요청을 SDK에 복사합니다.

인덱스 키가 KeyConditionExpression에 있어야 하는 GSI 쿼리의 프로토타입을 생성하려면 Query Builder를 사용하세요. ⌘P로 프로필을 전환합니다. 설정 → 프로필의 연결 테스트에서 색인이 존재하는지 확인합니다. Connect to AWS 및 Install를 참조하세요.

출처

Query — Amazon DynamoDB API Reference (2026-07-13 검증)
Filter expressions for Query (2026-07-13 인증)

참고 자료

위에 링크된 공식 AWS 문서를 기준으로 2026년 7월 13일에 마지막으로 확인되었습니다.