Query key condition not supported

In breve — Il tuo KeyConditionExpression ha usato un operatore che il key schema non consente. La partition key supporta solo l'uguaglianza (=). La sort key supporta =, <, <=, >, >=, BETWEEN e begins_with() — ma non contains(), <>, IN, o begins_with sulla partition key. Sposta qualsiasi altra cosa in una FilterExpression.

Cosa significa

ValidationException: Query key condition not supported

Questa ValidationException (HTTP 400) significa che la condizione che hai messo su una chiave non è una che DynamoDB può valutare rispetto alla struttura ordinata della chiave. Query percorre una partizione e scansiona il suo intervallo di sort key, quindi le condizioni sulla chiave sono ristrette alle operazioni che si mappano su quella struttura. Non è ripetibile — riscrivi la query.

Perché succede

• contains() su una chiave — contains() funziona solo in una FilterExpression, mai su una partition o sort key.
• Un operatore diverso dall'uguaglianza sulla partition key — la partition key deve usare =. begins_with, <, >, BETWEEN, o <> su di essa non sono supportati.
• IN o <> (diverso da) su una chiave — nessuno dei due è un operatore di chiave supportato; entrambi appartengono a un filtro.
• Riferimento a un attributo non-chiave nel KeyConditionExpression — solo le partition e sort key della tabella/indice sono consentite lì (quella variante è Query condition missed key schema element).
• begins_with() su una sort key Number — begins_with funziona solo su sort key String o Binary, e il nome della funzione è case-sensitive (begins_with, non BEGINS_WITH).
• Interrogare un GSI/LSI il cui key schema differisce da quello della tabella base, usando per errore le chiavi della tabella base.

Come risolverlo

1. Usa = sulla partition key, sempre. Query necessita di una partition key esatta; non puoi fare range-scan tra le partizioni.
2. Restringi la sort key agli operatori supportati — =, <, <=, >, >=, BETWEEN … AND …, o begins_with(sk, :prefix).
3. Sposta tutto il resto in una FilterExpression — contains(), <>, IN, corrispondenze di sottostringhe. (I filtri vengono eseguiti dopo la lettura e consumano comunque capacità, quindi progetta le chiavi per il pattern di accesso comune.)
4. Interroga l'indice giusto — se ti serve un pattern di accesso diverso, aggiungi/interroga un GSI le cui partition/sort key corrispondano alla condizione che vuoi, e passa il suo IndexName.
5. Fai riferimento solo ad attributi chiave nella condizione sulla chiave; metti i predicati non-chiave nel filtro.

FAQ

Perché viene generato "Query key condition not supported"? Il KeyConditionExpression ha usato un operatore che il key schema non può valutare — come contains() su una chiave, o una disuguaglianza/begins_with sulla partition key. Le partition key consentono solo l'uguaglianza; le sort key consentono un insieme limitato di confronti. Qualsiasi altra cosa deve spostarsi in una FilterExpression.

Posso usare contains() in una Query DynamoDB? Solo in una FilterExpression, non in un KeyConditionExpression. contains() non è un operatore di chiave valido. Se ti serve la corrispondenza di sottostringhe come pattern di accesso, modellala in una sort key su cui puoi fare begins_with(), o usa un GSI.

Riproducilo

Una Query che usa begins_with sulla partition key:

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

Output reale:

ValidationException: Query key condition not supported
HTTP 400

La partition key accetta l'uguaglianza e nient'altro. begins_with, <, > e BETWEEN sono leciti solo sulla sort key — che è la vera lezione dietro questo errore, e il motivo per cui di solito significa che il pattern di accesso richiede un key design diverso piuttosto che un'espressione diversa.

Errori correlati

• Query condition missed key schema element — un attributo non-chiave nella condizione sulla chiave, o una partition key mancante.
• ValidationException (overview)
• Esempio di codice: Query in Node.js · in Python (boto3) — condizioni sulla chiave valide in codice funzionante.
• Impara: Key condition expressions · Query vs Scan · Indici

Riferimenti

• 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

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.

Riprodotto il 2026-07-26 su DynamoDB Local 2.x con AWS SDK for JavaScript v3.1095.0 — l'output qui sopra è riportato alla lettera.