ValidationException: Query condition missed key schema element

TL;DR — KeyConditionExpression'ınız bölüm anahtarında bir eşitlik (=) içermelidir. Anahtar olmayan bir özniteliğe göre sorguluyorsanız, o özniteliği anahtarı olarak taşıyan bir GSI/LSI üzerinde bir Query'ye — ya da bir FilterExpression içeren bir Scan'e ihtiyacınız var.

Ne anlama gelir

Tam mesaj genellikle şudur:

ValidationException: Query condition missed key schema element: pk

İki noktadan sonraki ad, tablonuzun bölüm anahtarı özniteliğidir, dolayısıyla değişir.

Query yalnızca bir anahtara karşı çalışır. DynamoDB size, KeyConditionExpression'ın ya bölüm anahtarını tamamen atladığını ya da tablonun (veya sorguladığınız indeksin) bölüm/sıralama anahtarı olmayan bir özniteliği adlandırdığını söylüyor.

Neden olur

• KeyConditionExpression, bölüm anahtarı yerine normal bir öznitelik (örneğin email, status) üzerinde filtreliyor.
• Temel tabloyu sorguluyorsunuz ama öznitelik yalnızca bir GSI'de anahtar — IndexName'i unuttunuz.
• Bölüm anahtarı var ama = dışında bir operatörle (bölüm anahtarı tam bir eşleşme olmalıdır; yalnızca sıralama anahtarı <, >, begins_with, between'i destekler).
• Öznitelik adında bir yazım hatası, dolayısıyla artık şemayla eşleşmiyor.

Nasıl düzeltilir

1. Bölüm anahtarını = ile sorgulayın. Her Query'nin pk = :pk'ye ihtiyacı vardır (tablonuzun gerçek anahtar adını kullanarak).
2. Anahtar olmayan bir özniteliğe göre sorgulamanız mı gerekiyor? O özniteliği bölüm anahtarı olarak taşıyan bir GSI oluşturun ve IndexName iletin.
3. Yalnızca ara sıra erişime mi ihtiyacınız var? Query yerine bir FilterExpression içeren Scan kullanın — ancak Scan'in tüm tabloyu okuduğunu unutmayın.

Örnek

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'}
  })
);

SSS

"Query condition missed key schema element" ne anlama gelir? KeyConditionExpression'ınız ya bölüm anahtarını tamamen atlıyor ya da sorguladığınız tablonun veya indeksin bölüm veya sıralama anahtarı olmayan bir özniteliği adlandırıyor. Her Query, bölüm anahtarında bir eşitlik koşuluna ihtiyaç duyar.

DynamoDB'yi anahtar olmayan bir özniteliğe göre nasıl sorgularım? O özniteliği bölüm anahtarı olarak taşıyan bir GSI oluşturun ve Query'de IndexName iletin — ya da ara sıra erişim için, bir Scan'in tüm tabloyu okuduğunu akılda tutarak bir FilterExpression içeren bir Scan kullanın.

Nasıl yeniden oluşturulur

Koşulunda yalnızca sıralama anahtarını adlandıran bir Query:

await client.send(
  new QueryCommand({
    TableName: 'orders',
    KeyConditionExpression: 'sk = :s',
    ExpressionAttributeValues: {':s': {S: 'META'}}
  })
);

Gerçek çıktı:

ValidationException: Query condition missed key schema element
HTTP 400

Her Query tam olarak bir bölüm anahtarını sabitlemelidir. Yalnızca sıralama anahtarına göre arama yapmak istemek, erişim deseninin bir Query değil bir GSI gerektirdiğinin klasik işaretidir — ya da her bölümü gerçekten okumanız gerekiyorsa bir Scan'in.

İlgili hatalar

• The provided key element does not match the schema
• ValidationException (genel bakış)
• Kod örneği: Query in Node.js · Python (boto3) ile — doğru yapılmış bir KeyConditionExpression.
• Öğrenin: Query vs Scan · Key condition expressions

Kaynaklar

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

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.