Query key condition not supported

TL;DR — Tu KeyConditionExpression usó un operador que el esquema de claves no permite. La clave de partición solo admite igualdad (=). La clave de ordenación admite =, <, <=, >, >=, BETWEEN y begins_with() — pero no contains(), <>, IN, ni begins_with sobre la clave de partición. Mueve cualquier otra cosa a un FilterExpression.

Qué significa

ValidationException: Query key condition not supported

Este ValidationException (HTTP 400) significa que la condición que pusiste en una clave no es una que DynamoDB pueda evaluar contra la estructura ordenada de claves. Query recorre una partición y escanea su rango de clave de ordenación, así que las condiciones de clave se restringen a operaciones que encajan en esa estructura. No es reintentable — reescribe la consulta.

Por qué ocurre

contains() sobre una clave — contains() funciona solo en un FilterExpression, nunca sobre una clave de partición o de ordenación.
Un operador que no es de igualdad sobre la clave de partición — la clave de partición debe usar =. begins_with, <, >, BETWEEN o <> sobre ella no están soportados.
IN o <> (distinto de) sobre una clave — ninguno es un operador de clave soportado; ambos pertenecen a un filtro.
Referenciar un atributo que no es de clave en el KeyConditionExpression — allí solo se permiten las claves de partición y ordenación de la tabla/índice (esa variante es Query condition missed key schema element).
begins_with() sobre una clave de ordenación numérica — begins_with funciona solo sobre claves de ordenación de tipo String o Binary, y el nombre de la función distingue mayúsculas de minúsculas (begins_with, no BEGINS_WITH).
Consultar un GSI/LSI cuyo esquema de claves difiere del de la tabla base, usando por error las claves de la tabla base.

Cómo solucionarlo

Usa = sobre la clave de partición, siempre. Query necesita una clave de partición exacta; no puedes escanear por rangos entre particiones.
Restringe la clave de ordenación a los operadores soportados — =, <, <=, >, >=, BETWEEN … AND …, o begins_with(sk, :prefix).
Mueve todo lo demás a un FilterExpression — contains(), <>, IN, coincidencias de subcadenas. (Los filtros se ejecutan después de la lectura y aun así consumen capacidad, así que diseña las claves para el patrón de acceso habitual.)
Consulta el índice correcto — si necesitas un patrón de acceso diferente, añade/consulta un GSI cuyas claves de partición/ordenación coincidan con la condición que quieres, y pasa su IndexName.
Referencia solo atributos de clave en la condición de clave; pon los predicados que no sean de clave en el filtro.

FAQ

¿Por qué se lanza "Query key condition not supported"? El KeyConditionExpression usó un operador que el esquema de claves no puede evaluar — como contains() sobre una clave, o una desigualdad/begins_with sobre la clave de partición. Las claves de partición solo permiten igualdad; las claves de ordenación permiten un conjunto limitado de comparaciones. Cualquier otra cosa debe moverse a un FilterExpression.

¿Puedo usar contains() en un Query de DynamoDB? Solo en un FilterExpression, no en un KeyConditionExpression. contains() no es un operador de clave válido. Si necesitas coincidencia de subcadenas como patrón de acceso, modélalo en una clave de ordenación sobre la que puedas usar begins_with(), o usa un GSI.

Reproducirlo

Una Query que usa begins_with sobre la clave de partición:

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

Salida real:

ValidationException: Query key condition not supported
HTTP 400

La clave de partición acepta la igualdad y nada más. begins_with, <, > y BETWEEN solo son legales sobre la clave de ordenación — que es la verdadera lección detrás de este error, y la razón por la que normalmente significa que el patrón de acceso necesita un diseño de claves distinto, no una expresión distinta.

Errores relacionados

Query condition missed key schema element — un atributo que no es de clave en la condición de clave, o una clave de partición que falta.
ValidationException (visión general) — la familia de errores de validación al completo.
Ejemplo de código: Query in Node.js · en Python (boto3) — condiciones de clave válidas en código funcional.
Aprende: Key condition expressions · Query vs Scan · Índices

Referencias

Verificado por última vez el 2026-07-13 contra la documentación oficial de AWS enlazada arriba.

Reproducido el 2026-07-26 contra DynamoDB Local 2.x con AWS SDK for JavaScript v3.1095.0 — la salida de arriba es literal.