Query key condition not supported

TL;DR — KeyConditionExpression Anda memakai operator yang tidak diizinkan key schema. Partition key hanya mendukung kesetaraan (=). Sort key mendukung =, <, <=, >, >=, BETWEEN, dan begins_with() — tapi bukan contains(), <>, IN, atau begins_with pada partition key. Pindahkan selebihnya ke FilterExpression.

Apa artinya

ValidationException: Query key condition not supported

ValidationException (HTTP 400) ini berarti kondisi yang Anda pasang pada sebuah key bukan kondisi yang bisa dievaluasi DynamoDB terhadap struktur key yang terurut. Query menyusuri satu partisi dan memindai rentang sort key-nya, jadi kondisi key dibatasi pada operasi yang memetakan ke struktur itu. Ia tidak bisa dicoba ulang — tulis ulang query-nya.

Mengapa itu terjadi

• contains() pada sebuah key — contains() hanya bekerja di FilterExpression, tidak pernah pada partition atau sort key.
• Operator non-kesetaraan pada partition key — partition key harus memakai =. begins_with, <, >, BETWEEN, atau <> padanya tidak didukung.
• IN atau <> (tidak sama dengan) pada sebuah key — keduanya bukan operator key yang didukung; keduanya tempatnya di filter.
• Merujuk atribut non-key di dalam KeyConditionExpression — hanya partition dan sort key tabel/index yang diizinkan di sana (varian itu adalah Query condition missed key schema element).
• begins_with() pada sort key bertipe Number — begins_with hanya bekerja pada sort key bertipe String atau Binary, dan nama fungsinya peka huruf besar-kecil (begins_with, bukan BEGINS_WITH).
• Melakukan Query pada GSI/LSI yang key schema-nya berbeda dari tabel dasar, tetapi keliru memakai key tabel dasar.

Bagaimana cara memperbaikinya

1. Selalu pakai = pada partition key. Query butuh partition key yang persis; Anda tidak bisa memindai rentang lintas partisi.
2. Batasi sort key pada operator yang didukung — =, <, <=, >, >=, BETWEEN … AND …, atau begins_with(sk, :prefix).
3. Pindahkan selebihnya ke FilterExpression — contains(), <>, IN, pencocokan substring. (Filter berjalan setelah pembacaan dan tetap memakan kapasitas, jadi rancang key untuk pola akses yang paling umum.)
4. Lakukan Query pada index yang tepat — kalau Anda butuh pola akses berbeda, tambahkan/Query sebuah GSI yang partition/sort key-nya cocok dengan kondisi yang Anda inginkan, lalu kirimkan IndexName-nya.
5. Rujuk hanya atribut key di kondisi key; taruh predikat non-key di filter.

FAQ

Mengapa "Query key condition not supported" dilempar? KeyConditionExpression memakai operator yang tidak bisa dievaluasi key schema — misalnya contains() pada sebuah key, atau pertidaksamaan/begins_with pada partition key. Partition key hanya mengizinkan kesetaraan; sort key mengizinkan sejumlah perbandingan terbatas. Selebihnya harus dipindahkan ke FilterExpression.

Bisakah saya memakai contains() di dalam Query DynamoDB? Hanya di FilterExpression, bukan di KeyConditionExpression. contains() bukan operator key yang valid. Kalau Anda butuh pencocokan substring sebagai pola akses, modelkan ke dalam sort key yang bisa Anda kenai begins_with(), atau pakai GSI.

Cara mereproduksinya

Sebuah Query yang memakai begins_with pada partition key:

await client.send(
  new QueryCommand({
    TableName: 'orders',
    KeyConditionExpression: 'begins_with(pk, :p)',
    ExpressionAttributeValues: {':p': {S: 'ORDER#'}}
  })
);

Keluaran sebenarnya:

ValidationException: Query key condition not supported
HTTP 400

Partition key menerima kesetaraan dan tidak yang lain. begins_with, <, >, dan BETWEEN hanya sah pada sort key — itulah pelajaran sesungguhnya di balik error ini, dan alasan mengapa ia biasanya berarti pola aksesnya butuh desain key yang berbeda ketimbang expression yang berbeda.

Kesalahan terkait

• Query condition missed key schema element — atribut non-key di kondisi key, atau partition key yang hilang.
• ValidationException (ikhtisar)
• Contoh kode: Query di Node.js · di Python (boto3) — kondisi key yang valid dalam kode yang berjalan.
• Pelajari: Key condition expression · Query vs Scan · Index

Referensi

• 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

Terakhir diverifikasi 2026-07-13 terhadap dokumentasi resmi AWS yang ditautkan di atas.

Direproduksi 2026-07-26 terhadap DynamoDB Local 2.x dengan AWS SDK for JavaScript v3.1095.0 — keluaran di atas dikutip apa adanya.