Query key condition not supported

TL;DR — KeyConditionExpression'ınız, anahtar şemasının izin vermediği bir operatör kullandı. Bölüm anahtarı yalnızca eşitliği (=) destekler. Sıralama anahtarı =, <, <=, >, >=, BETWEEN ve begins_with()'i destekler — ama contains(), <>, IN ya da bölüm anahtarında begins_with'i desteklemez. Başka her şeyi bir FilterExpression'a taşıyın.

Ne anlama gelir

ValidationException: Query key condition not supported

Bu ValidationException (HTTP 400), bir anahtara koyduğunuz koşulun, DynamoDB'nin sıralı anahtar yapısına karşı değerlendirebileceği bir koşul olmadığı anlamına gelir. Query, bir bölümde dolaşır ve onun sıralama anahtarı aralığını tarar, dolayısıyla anahtar koşulları o yapıya eşlenen işlemlerle sınırlıdır. Yeniden denenebilir değildir — sorguyu yeniden yazın.

Neden olur

Bir anahtarda contains() — contains() yalnızca bir FilterExpression'da çalışır, asla bir bölüm ya da sıralama anahtarında değil.
Bölüm anahtarında eşitlik olmayan bir operatör — bölüm anahtarı = kullanmalıdır. Onda begins_with, <, >, BETWEEN ya da <> desteklenmez.
Bir anahtarda IN ya da <> (eşit-değil) — hiçbiri desteklenen bir anahtar operatörü değildir; her ikisi de bir filtreye aittir.
KeyConditionExpression'da bir anahtar olmayan özniteliğe başvurmak — orada yalnızca tablo/indeks bölüm ve sıralama anahtarlarına izin verilir (o varyant Query condition missed key schema element'tir).
Bir Number sıralama anahtarında begins_with() — begins_with yalnızca String veya Binary sıralama anahtarlarında çalışır ve fonksiyon adı büyük/küçük harfe duyarlıdır (BEGINS_WITH değil, begins_with).
Anahtar şeması temel tablonunkinden farklı olan bir GSI/LSI'yi, yanlışlıkla temel tablonun anahtarlarını kullanarak sorgulamak.

Nasıl düzeltilir

Bölüm anahtarında her zaman = kullanın. Query, tam bir bölüm anahtarına ihtiyaç duyar; bölümler arasında aralık tarayamazsınız.
Sıralama anahtarını desteklenen operatörlerle sınırlayın — =, <, <=, >, >=, BETWEEN … AND … ya da begins_with(sk, :prefix).
Başka her şeyi bir FilterExpression'a taşıyın — contains(), <>, IN, alt dize eşleşmeleri. (Filtreler okumadan sonra çalışır ve yine de kapasite tüketir, bu yüzden anahtarları yaygın erişim deseni için tasarlayın.)
Doğru indeksi sorgulayın — farklı bir erişim desenine ihtiyacınız varsa, bölüm/sıralama anahtarları istediğiniz koşulla eşleşen bir GSI ekleyin/sorgulayın ve IndexName'ini iletin.
Anahtar koşulunda yalnızca anahtar özniteliklerine başvurun; anahtar olmayan yüklemleri filtreye koyun.

SSS

"Query key condition not supported" neden fırlatılır? KeyConditionExpression, anahtar şemasının değerlendiremeyeceği bir operatör kullandı — bir anahtarda contains() ya da bölüm anahtarında bir eşitsizlik/begins_with gibi. Bölüm anahtarları yalnızca eşitliğe izin verir; sıralama anahtarları sınırlı bir karşılaştırma kümesine izin verir. Başka her şey bir FilterExpression'a taşınmalıdır.

Bir DynamoDB Query'de contains() kullanabilir miyim? Yalnızca bir FilterExpression'da, bir KeyConditionExpression'da değil. contains() geçerli bir anahtar operatörü değildir. Erişim deseni olarak alt dize eşleştirmesine ihtiyacınız varsa, onu begins_with() yapabileceğiniz bir sıralama anahtarına modelleyin ya da bir GSI kullanın.

Nasıl yeniden oluşturulur

Bölüm anahtarında begins_with kullanan bir Query:

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

Gerçek çıktı:

ValidationException: Query key condition not supported
HTTP 400

Bölüm anahtarı eşitlikten başka bir şey kabul etmez. begins_with, <, > ve BETWEEN yalnızca sıralama anahtarında geçerlidir — bu hatanın ardındaki asıl ders budur ve genellikle erişim deseninin farklı bir ifadeye değil, farklı bir anahtar tasarımına ihtiyaç duyduğu anlamına gelmesinin nedenidir.

İlgili hatalar

Query condition missed key schema element — anahtar koşulunda bir anahtar olmayan öznitelik ya da eksik bir bölüm anahtarı.
ValidationException (genel bakış)
Kod örneği: Query in Node.js · Python (boto3) ile — çalışan kodda geçerli anahtar koşulları.
Öğrenin: Key condition expressions · Query vs Scan · Index'ler

Kaynaklar

En son 2026-07-13 tarihinde yukarıda bağlantısı verilen resmi AWS belgelerine karşı doğrulandı.

2026-07-26 tarihinde AWS SDK for JavaScript v3.1095.0 ile DynamoDB Local 2.x'e karşı yeniden üretildi — yukarıdaki çıktı birebir alınmıştır.