ValidationException: Query condition missed key schema element

En bref — Ton KeyConditionExpression doit inclure une égalité (=) sur la clé de partition. Si tu interroges par un attribut hors clé, il te faut une Query sur un GSI/LSI qui a cet attribut comme clé — ou un Scan avec un FilterExpression.

Ce que ça signifie

Le message complet est généralement :

ValidationException: Query condition missed key schema element: pk

Le nom après les deux-points est l'attribut de clé de partition de ta table ; il varie donc.

Query ne fonctionne que contre une clé. DynamoDB te dit que le KeyConditionExpression soit omet entièrement la clé de partition, soit nomme un attribut qui n'est pas la clé de partition/de tri de la table (ou de l'index que tu interroges).

Pourquoi ça arrive

• Le KeyConditionExpression filtre sur un attribut ordinaire (p. ex. email, status) au lieu de la clé de partition.
• Tu interroges la table de base mais l'attribut n'est une clé que sur un GSI — tu as oublié IndexName.
• La clé de partition est présente mais avec un opérateur autre que = (la clé de partition doit être une correspondance exacte ; seule la clé de tri prend en charge <, >, begins_with, between).
• Une faute de frappe dans le nom de l'attribut, de sorte qu'il ne correspond plus au schéma.

Comment le corriger

1. Interroge sur la clé de partition avec =. Chaque Query a besoin de pk = :pk (avec le vrai nom de clé de ta table).
2. Besoin d'interroger par un attribut hors clé ? Crée un GSI avec cet attribut comme clé de partition et passe IndexName.
3. Besoin d'un accès occasionnel seulement ? Utilise Scan avec un FilterExpression au lieu de Query — mais note que Scan lit toute la table.

Exemple

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

Que signifie « Query condition missed key schema element » ? Ton KeyConditionExpression soit omet entièrement la clé de partition, soit nomme un attribut qui n'est pas la clé de partition ou de tri de la table ou de l'index que tu interroges. Chaque Query a besoin d'une condition d'égalité sur la clé de partition.

Comment interroger DynamoDB par un attribut hors clé ? Crée un GSI avec cet attribut comme clé de partition et passe IndexName dans la Query — ou, pour un accès occasionnel, utilise un Scan avec un FilterExpression, en gardant à l'esprit qu'un Scan lit toute la table.

Reproduire l'erreur

Une Query dont la condition ne nomme que la clé de tri :

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

Sortie réelle :

ValidationException: Query condition missed key schema element
HTTP 400

Toute Query doit épingler exactement une clé de partition. Vouloir chercher par la seule clé de tri est le signe classique d'un pattern d'accès qui réclame un GSI plutôt qu'une Query — ou, si tu dois vraiment lire toutes les partitions, un Scan.

Erreurs liées

• The provided key element does not match the schema
• ValidationException (aperçu)
• Exemple de code : Query en Node.js · en Python (boto3) — un KeyConditionExpression fait correctement.
• Apprends : Query vs Scan · Key condition expressions

Références

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

Dernière vérification le 2026-07-13 par rapport à la documentation officielle AWS liée ci-dessus.

Reproduit le 2026-07-26 sur DynamoDB Local 2.x avec l'AWS SDK for JavaScript v3.1095.0 — la sortie ci-dessus est reproduite telle quelle.