ValidationException: Query condition missed key schema element

TL;DR — Seu KeyConditionExpression precisa incluir uma igualdade (=) na chave de partição. Se você está consultando por um atributo que não é chave, precisa de uma Query em um GSI/LSI que tenha esse atributo como sua chave — ou de um Scan com um FilterExpression.

O que significa

A mensagem completa normalmente é:

ValidationException: Query condition missed key schema element: pk

O nome depois dos dois-pontos é o atributo de chave de partição da sua tabela, então ele varia.

Query só funciona contra uma chave. O DynamoDB está dizendo que o KeyConditionExpression ou omite a chave de partição inteiramente, ou nomeia um atributo que não é a chave de partição/ordenação da tabela (ou do índice que você está consultando).

Por que isso acontece

• O KeyConditionExpression filtra em um atributo comum (por exemplo, email, status) em vez da chave de partição.
• Você está consultando a tabela base mas o atributo só é chave em um GSI — você esqueceu o IndexName.
• A chave de partição está presente mas com um operador diferente de = (a chave de partição precisa ser uma correspondência exata; apenas a chave de ordenação suporta <, >, begins_with, between).
• Um erro de digitação no nome do atributo, de modo que ele não corresponde mais ao schema.

Como corrigir

1. Consulte na chave de partição com =. Toda Query precisa de pk = :pk (usando o nome real da chave da sua tabela).
2. Precisa consultar por um atributo que não é chave? Crie um GSI com esse atributo como sua chave de partição e passe IndexName.
3. Só precisa de acesso ocasional? Use Scan com um FilterExpression em vez de Query — mas note que o Scan lê a tabela inteira.

Exemplo

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

O que significa "Query condition missed key schema element"? Seu KeyConditionExpression ou omite a chave de partição inteiramente ou nomeia um atributo que não é a chave de partição ou de ordenação da tabela ou índice que você está consultando. Toda Query precisa de uma condição de igualdade na chave de partição.

Como consulto o DynamoDB por um atributo que não é chave? Crie um GSI com esse atributo como sua chave de partição e passe IndexName na Query — ou, para acesso ocasional, use um Scan com um FilterExpression, tendo em mente que um Scan lê a tabela inteira.

Reproduza

Uma Query cuja condição nomeia apenas a chave de ordenação:

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

Saída real:

ValidationException: Query condition missed key schema element
HTTP 400

Toda Query precisa fixar exatamente uma chave de partição. Querer buscar só pela chave de ordenação é o sinal clássico de que o padrão de acesso pede um GSI em vez de uma Query — ou, se você realmente precisa ler todas as partições, um Scan.

Erros relacionados

• The provided key element does not match the schema
• ValidationException (overview)
• Exemplo de código: Query in Node.js · in Python (boto3) — um KeyConditionExpression feito corretamente.
• Aprenda: Query vs Scan · Key condition expressions

Referências

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

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.