Query em um GSI do DynamoDB com a AWS CLI

Consultar um índice secundário global é um aws dynamodb query normal mais uma flag: --index-name. A condição de chave passa então a mirar as chaves do índice, não as da tabela — aqui o AlbumTitle-index nos permite buscar músicas por álbum, um padrão de acesso que a tabela base (Artist + SongTitle) não consegue atender sem um scan.

Código

aws dynamodb query \
  --table-name 'Music' \
  --index-name 'AlbumTitle-index' \
  --key-condition-expression '#hashKey = :hashKeyValue' \
  --expression-attribute-names '{"#hashKey":"AlbumTitle"}' \
  --expression-attribute-values '{":hashKeyValue":{"S":"Danzon"}}'

A saída são os itens correspondentes em JSON do DynamoDB:

{
    "Items": [
        {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, ...}
    ],
    "Count": 2,
    "ScannedCount": 2
}

Explicação

A tabela base não é cobrada em nada por esta consulta. Adicione --return-consumed-capacity INDEXES e a divisão fica explícita:

"ConsumedCapacity": {
    "CapacityUnits": 132.0,
    "Table": {"CapacityUnits": 0.0},
    "GlobalSecondaryIndexes": {"AlbumTitle-index": {"CapacityUnits": 132.0}}
}

Zero contra a tabela, tudo contra o índice. Um GSI é uma tabela separada com o seu próprio schema de chave, as suas próprias partições e a sua própria capacidade, e lê-lo nunca toca a tabela base. É também por isso que um GSI tem a sua própria história de throttling: um GSI com throttle pode fazer throttle nas escritas da tabela base, ainda que as leituras nunca cruzem para lá.

--consistent-read é rejeitado, não rebaixado. GSIs replicam de forma assíncrona e não existe flag que mude isso:

aws: [ERROR]: An error occurred (ValidationException) when calling the Query operation: Consistent reads are not supported on global secondary indexes

Código de saída 254. A referência da API diz o mesmo de antemão: "Strongly consistent reads are not supported on global secondary indexes. If you query a global secondary index with ConsistentRead set to true, you will receive a ValidationException" (consultada em 2026-07-28). Índices secundários locais aceitam sim, o que é um dos poucos motivos reais para escolher um LSI. O atraso em si está coberto em por que os GSIs têm consistência eventual.

Itens sem a chave do índice simplesmente não estão no índice. Contados na mesma tabela: 35 itens na tabela base, 32 no AlbumTitle-index. Os três que faltam não têm atributo AlbumTitle nenhum, o que foi confirmado com um scan em attribute_not_exists(AlbumTitle). Nada deu erro e nada avisou. Este é o padrão de índice esparso, e é design deliberado quando você grava o atributo-sinalizador só para as linhas que quer indexadas, e um bug silencioso de perda de dados quando você presume que o índice espelha a tabela.

Você só recebe o que o índice projeta. "If you query or scan a global secondary index, you can only request attributes that are projected into the index. Global secondary index queries cannot fetch attributes from the parent table" (consultada em 2026-07-28). Em um índice KEYS_ONLY ou INCLUDE isso significa um segundo get-item por resultado para preencher o resto, que é justamente o N+1 que você tentava evitar. A projeção é fixada quando o índice é criado e não pode ser alterada depois; veja projeções de índice antes de escolher uma.

Chaves de índice não são únicas. Muitos itens podem compartilhar um mesmo AlbumTitle, então uma consulta a um GSI retorna uma coleção onde a consulta equivalente na tabela retornaria um único item. Não existe get-item contra um GSI, exatamente por isso.

A paginação se comporta como em qualquer consulta a uma tabela, incluindo a mania da CLI de reportar o ConsumedCapacity de uma página para um resultado paginado automaticamente. Isso está medido em detalhe em Query com a AWS CLI; as flags são as mesmas aqui.

Faça isso visualmente

Uma consulta a um índice tem mais peças móveis do que uma à tabela: o índice certo, os nomes de chave do próprio índice e uma projeção que pode não carregar os atributos de que você precisa. O DynamoDB Query Builder gratuito deixa você escolher o índice, monta a condição de chave contra as chaves dele e emite o comando da CLI.

Para ver quais índices uma tabela realmente tem e consultá-los contra os seus próprios dados — projeções listadas, uma grade que pagina conforme você rola, copiar a requisição de volta como comando da CLI — baixe o DynoTable.

Exemplos relacionados

Query em um GSI do DynamoDB em Node.js — a mesma consulta a índice com o AWS SDK v3.
Query em um GSI do DynamoDB em Python — a mesma consulta a índice com boto3.
GSI vs. LSI — qual tipo de índice combina com o padrão de acesso.
"The table does not have the specified index" — o nome do índice não confere (nomes de GSI diferenciam maiúsculas de minúsculas).
"Consistent reads are not supported on global secondary indexes" — por que a flag de leitura consistente falha em um GSI.

Referências

Reproduzido em 2026-07-28 com aws-cli/2.36.9 contra o DynamoDB Local (amazon/dynamodb-local) na porta 9000, em uma tabela Music com um AlbumTitle-index projetando ALL. O texto do erro, a divisão de capacidade e as contagens de itens são saída capturada.