Query key condition not supported

TL;DR — Ta KeyConditionExpression a utilisé un opérateur que le schéma de clé n'autorise pas. La clé de partition ne supporte que l'égalité (=). La clé de tri supporte =, <, <=, >, >=, BETWEEN et begins_with() — mais pas contains(), <>, IN, ni begins_with sur la clé de partition. Déplace tout le reste vers une FilterExpression.

Ce que ça signifie

ValidationException: Query key condition not supported

Cette ValidationException (HTTP 400) signifie que la condition posée sur une clé n'est pas une condition que DynamoDB peut évaluer contre la structure de clé triée. Query parcourt une partition et balaie sa plage de clés de tri, donc les conditions de clé sont restreintes aux opérations qui correspondent à cette structure. Elle n'est pas réessayable — réécris la requête.

Pourquoi ça arrive

contains() sur une clé — contains() ne fonctionne que dans une FilterExpression, jamais sur une clé de partition ou de tri.
Un opérateur non-égalité sur la clé de partition — la clé de partition doit utiliser =. begins_with, <, >, BETWEEN ou <> dessus ne sont pas supportés.
IN ou <> (différent de) sur une clé — aucun des deux n'est un opérateur de clé supporté ; les deux relèvent d'un filtre.
Référencer un attribut non-clé dans la KeyConditionExpression — seules les clés de partition et de tri de la table/index y sont autorisées (cette variante est Query condition missed key schema element).
begins_with() sur une clé de tri de type Number — begins_with ne fonctionne que sur des clés de tri String ou Binary, et le nom de la fonction est sensible à la casse (begins_with, pas BEGINS_WITH).
Interroger un GSI/LSI dont le schéma de clé diffère de celui de la table de base, en utilisant par erreur les clés de la table de base.

Comment le corriger

Utilise = sur la clé de partition, toujours. Query a besoin d'une clé de partition exacte ; tu ne peux pas faire un range-scan à travers les partitions.
Restreins la clé de tri aux opérateurs supportés — =, <, <=, >, >=, BETWEEN … AND …, ou begins_with(sk, :prefix).
Déplace tout le reste vers une FilterExpression — contains(), <>, IN, correspondances de sous-chaîne. (Les filtres s'exécutent après la lecture et consomment quand même de la capacité, donc conçois les clés pour le schéma d'accès courant.)
Interroge le bon index — si tu as besoin d'un schéma d'accès différent, ajoute/interroge un GSI dont les clés de partition/tri correspondent à la condition voulue, et passe son IndexName.
Ne référence que des attributs de clé dans la condition de clé ; place les prédicats non-clé dans le filtre.

FAQ

Pourquoi « Query key condition not supported » est-elle levée ? La KeyConditionExpression a utilisé un opérateur que le schéma de clé ne peut pas évaluer — comme contains() sur une clé, ou une inégalité/begins_with sur la clé de partition. Les clés de partition n'autorisent que l'égalité ; les clés de tri autorisent un ensemble limité de comparaisons. Tout le reste doit être déplacé vers une FilterExpression.

Puis-je utiliser contains() dans une Query DynamoDB ? Seulement dans une FilterExpression, pas dans une KeyConditionExpression. contains() n'est pas un opérateur de clé valide. Si tu as besoin de correspondance de sous-chaîne comme schéma d'accès, modélise-la dans une clé de tri contre laquelle tu peux faire begins_with(), ou utilise un GSI.

Reproduire l'erreur

Une Query qui utilise begins_with sur la clé de partition :

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

Sortie réelle :

ValidationException: Query key condition not supported
HTTP 400

La clé de partition n'accepte que l'égalité, et rien d'autre. begins_with, <, > et BETWEEN ne sont légaux que sur la clé de tri — c'est la vraie leçon derrière cette erreur, et pourquoi elle signale généralement un pattern d'accès qui réclame une autre conception de clés plutôt qu'une autre expression.

Erreurs liées

Query condition missed key schema element — un attribut non-clé dans la condition de clé, ou une clé de partition manquante.
ValidationException (vue d'ensemble)
Exemple de code : Query en Node.js · en Python (boto3) — des conditions de clé valides dans du code fonctionnel.
En savoir plus : Key condition expressions · Query vs Scan · Index

Références

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.