Query key condition not supported

TL;DR — Deine KeyConditionExpression hat einen Operator verwendet, den das Schlüsselschema nicht erlaubt. Der Partition Key unterstützt nur Gleichheit (=). Der Sort Key unterstützt =, <, <=, >, >=, BETWEEN und begins_with() — aber nicht contains(), <>, IN oder begins_with auf dem Partition Key. Verschiebe alles andere in eine FilterExpression.

Was es bedeutet

ValidationException: Query key condition not supported

Diese ValidationException (HTTP 400) bedeutet, dass die Bedingung, die du auf einen Schlüssel gesetzt hast, keine ist, die DynamoDB gegen die sortierte Schlüsselstruktur auswerten kann. Query durchläuft eine Partition und scannt deren Sort-Key-Bereich, sodass Schlüsselbedingungen auf Operationen beschränkt sind, die auf diese Struktur abbilden. Er ist nicht wiederholbar — schreibe die Abfrage um.

Warum es passiert

contains() auf einem Schlüssel — contains() funktioniert nur in einer FilterExpression, nie auf einem Partition- oder Sort Key.
Ein Nicht-Gleichheits-Operator auf dem Partition Key — der Partition Key muss = verwenden. begins_with, <, >, BETWEEN oder <> darauf werden nicht unterstützt.
IN oder <> (ungleich) auf einem Schlüssel — keiner ist ein unterstützter Schlüsseloperator; beide gehören in einen Filter.
Verweis auf ein Nicht-Schlüssel-Attribut in der KeyConditionExpression — nur die Partition- und Sort Keys der Tabelle/des Index sind dort erlaubt (diese Variante ist Query condition missed key schema element).
begins_with() auf einem Number-Sort-Key — begins_with funktioniert nur auf String- oder Binary-Sort-Keys, und der Funktionsname unterscheidet Groß-/Kleinschreibung (begins_with, nicht BEGINS_WITH).
Abfrage eines GSI/LSI, dessen Schlüsselschema sich von dem der Basistabelle unterscheidet, unter irrtümlicher Verwendung der Schlüssel der Basistabelle.

So behebst du es

Verwende = auf dem Partition Key, immer. Query braucht einen exakten Partition Key; du kannst nicht über Partitionen hinweg per Bereich scannen.
Beschränke den Sort Key auf unterstützte Operatoren — =, <, <=, >, >=, BETWEEN … AND … oder begins_with(sk, :prefix).
Verschiebe alles andere in eine FilterExpression — contains(), <>, IN, Teilstring-Abgleiche. (Filter laufen nach dem Read und verbrauchen trotzdem Kapazität, also entwirf Schlüssel für das gängige Zugriffsmuster.)
Frage den richtigen Index ab — wenn du ein anderes Zugriffsmuster brauchst, füge einen GSI hinzu bzw. frage ihn ab, dessen Partition-/Sort Keys zur gewünschten Bedingung passen, und übergib seinen IndexName.
Verweise nur auf Schlüsselattribute in der Schlüsselbedingung; setze Nicht-Schlüssel-Prädikate in den Filter.

FAQ

Warum wird "Query key condition not supported" geworfen? Die KeyConditionExpression hat einen Operator verwendet, den das Schlüsselschema nicht auswerten kann — etwa contains() auf einem Schlüssel oder eine Ungleichheit/begins_with auf dem Partition Key. Partition Keys erlauben nur Gleichheit; Sort Keys erlauben einen begrenzten Satz von Vergleichen. Alles andere muss in eine FilterExpression verschoben werden.

Kann ich contains() in einer DynamoDB-Query verwenden? Nur in einer FilterExpression, nicht in einer KeyConditionExpression. contains() ist kein gültiger Schlüsseloperator. Wenn du Teilstring-Abgleich als Zugriffsmuster brauchst, modelliere ihn in einen Sort Key, gegen den du begins_with() anwenden kannst, oder nutze einen GSI.

So reproduzierst du es

Eine Query, die begins_with auf dem Partition Key verwendet:

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

Echte Ausgabe:

ValidationException: Query key condition not supported
HTTP 400

Der Partition Key akzeptiert Gleichheit und sonst nichts. begins_with, <, > und BETWEEN sind nur auf dem Sort Key erlaubt — das ist die eigentliche Lehre hinter diesem Fehler und der Grund, warum er meist bedeutet, dass das Zugriffsmuster ein anderes Key-Design braucht statt einer anderen Expression.

Referenzen

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.

Am 2026-07-26 gegen DynamoDB Local 2.x mit dem AWS SDK for JavaScript v3.1095.0 reproduziert — die Ausgabe oben ist wortgetreu.