ValidationException: Query condition missed key schema element

In breve — Il tuo KeyConditionExpression deve includere un'uguaglianza (=) sulla partition key. Se stai interrogando per un attributo non-chiave, ti serve una Query su un GSI/LSI che abbia quell'attributo come chiave — o uno Scan con una FilterExpression.

Cosa significa

Il messaggio completo è di solito:

ValidationException: Query condition missed key schema element: pk

Il nome dopo i due punti è l'attributo partition key della tua tabella, quindi varia.

Query funziona solo contro una chiave. DynamoDB ti sta dicendo che il KeyConditionExpression o omette del tutto la partition key, oppure nomina un attributo che non è la partition/sort key della tabella (o dell'indice che stai interrogando).

Perché succede

Il KeyConditionExpression filtra su un attributo normale (es. email, status) invece che sulla partition key.
Stai interrogando la tabella base ma l'attributo è una chiave solo su un GSI — hai dimenticato IndexName.
La partition key è presente ma con un operatore diverso da = (la partition key deve essere una corrispondenza esatta; solo la sort key supporta <, >, begins_with, between).
Un refuso nel nome dell'attributo così non corrisponde più allo schema.

Come risolverlo

Interroga sulla partition key con =. Ogni Query necessita di pk = :pk (usando il vero nome della chiave della tua tabella).
Devi interrogare per un attributo non-chiave? Crea un GSI con quell'attributo come partition key e passa IndexName.
Ti serve solo un accesso occasionale? Usa Scan con una FilterExpression invece di Query — ma nota che Scan legge l'intera tabella.

Esempio

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

FAQ

Cosa significa "Query condition missed key schema element"? Il tuo KeyConditionExpression o omette del tutto la partition key oppure nomina un attributo che non è la partition o la sort key della tabella o dell'indice che stai interrogando. Ogni Query necessita di una condizione di uguaglianza sulla partition key.

Come interrogo DynamoDB per un attributo non-chiave? Crea un GSI con quell'attributo come partition key e passa IndexName nella Query — oppure, per un accesso occasionale, usa uno Scan con una FilterExpression, tenendo presente che uno Scan legge l'intera tabella.

Riproducilo

Una Query la cui condizione nomina solo la sort key:

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

Output reale:

ValidationException: Query condition missed key schema element
HTTP 400

Ogni Query deve fissare esattamente una partition key. Voler cercare solo per sort key è il classico segnale che il pattern di accesso ha bisogno di un GSI invece che di una Query — o, se devi davvero leggere ogni partizione, di uno Scan.

Errori correlati

The provided key element does not match the schema
ValidationException (overview)
Esempio di codice: Query in Node.js · in Python (boto3) — un KeyConditionExpression fatto bene.
Impara: Query vs Scan · Key condition expressions

Riferimenti

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.