Query key condition not supported

TL;DR — Seu KeyConditionExpression usou um operador que o key schema não permite. A chave de partição suporta apenas igualdade (=). A chave de ordenação suporta =, <, <=, >, >=, BETWEEN e begins_with() — mas não contains(), <>, IN, ou begins_with na chave de partição. Mova qualquer outra coisa para um FilterExpression.

O que significa

ValidationException: Query key condition not supported

Este ValidationException (HTTP 400) significa que a condição que você colocou em uma chave não é uma que o DynamoDB pode avaliar contra a estrutura de chave ordenada. Query percorre uma partição e escaneia seu intervalo de chave de ordenação, então condições de chave são restritas a operações que mapeiam nessa estrutura. Ele não é retentável — reescreva a consulta.

Por que isso acontece

contains() em uma chave — contains() funciona apenas em um FilterExpression, nunca em uma chave de partição ou ordenação.
Um operador de não-igualdade na chave de partição — a chave de partição precisa usar =. begins_with, <, >, BETWEEN ou <> nela não são suportados.
IN ou <> (diferente) em uma chave — nenhum é um operador de chave suportado; ambos pertencem a um filtro.
Referenciar um atributo que não é chave no KeyConditionExpression — apenas as chaves de partição e ordenação da tabela/índice são permitidas ali (essa variante é Query condition missed key schema element).
begins_with() em uma chave de ordenação Number — begins_with funciona apenas em chaves de ordenação String ou Binary, e o nome da função é sensível a maiúsculas (begins_with, não BEGINS_WITH).
Consultar um GSI/LSI cujo key schema difere do da tabela base, usando as chaves da tabela base por engano.

Como corrigir

Use = na chave de partição, sempre. Query precisa de uma chave de partição exata; você não pode fazer range-scan entre partições.
Restrinja a chave de ordenação a operadores suportados — =, <, <=, >, >=, BETWEEN … AND …, ou begins_with(sk, :prefix).
Mova todo o resto para um FilterExpression — contains(), <>, IN, correspondências de substring. (Filtros rodam após a leitura e ainda consomem capacidade, então projete chaves para o padrão de acesso comum.)
Consulte o índice certo — se você precisa de um padrão de acesso diferente, adicione/consulte um GSI cujas chaves de partição/ordenação correspondam à condição que você quer, e passe seu IndexName.
Referencie apenas atributos de chave na condição de chave; ponha predicados que não são de chave no filtro.

FAQ

Por que "Query key condition not supported" é lançado? O KeyConditionExpression usou um operador que o key schema não consegue avaliar — como contains() em uma chave, ou uma desigualdade/begins_with na chave de partição. Chaves de partição permitem apenas igualdade; chaves de ordenação permitem um conjunto limitado de comparações. Qualquer outra coisa precisa mover para um FilterExpression.

Posso usar contains() em uma Query do DynamoDB? Apenas em um FilterExpression, não em um KeyConditionExpression. contains() não é um operador de chave válido. Se você precisa de correspondência de substring como um padrão de acesso, modele-a em uma chave de ordenação contra a qual você possa usar begins_with(), ou use um GSI.

Reproduza

Uma Query usando begins_with na chave de partição:

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

Saída real:

ValidationException: Query key condition not supported
HTTP 400

A chave de partição aceita igualdade e nada mais. begins_with, <, > e BETWEEN são válidos apenas na chave de ordenação — que é a lição de verdade por trás deste erro, e o motivo pelo qual ele geralmente significa que o padrão de acesso precisa de um design de chaves diferente, e não de uma expressão diferente.

Erros relacionados

Query condition missed key schema element — um atributo que não é chave na condição de chave, ou uma chave de partição ausente.
ValidationException (overview)
Exemplo de código: Query in Node.js · in Python (boto3) — condições de chave válidas em código funcional.
Aprenda: Key condition expressions · Query vs Scan · Índices

Referências

Verificado pela última vez em 2026-07-13 contra a documentação oficial da AWS vinculada acima.

Reproduzido em 2026-07-26 no DynamoDB Local 2.x com o AWS SDK for JavaScript v3.1095.0 — a saída acima é literal.