Consultar 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 key condition então mira as chaves do índice, não as da tabela — aqui 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.

Code

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 DynamoDB JSON:

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

Explicação

--index-name — nomeia o GSI a consultar (--table-name ainda é obrigatório). A --key-condition-expression usa a chave de partição (e a chave de classificação opcional) do índice — AlbumTitle aqui — com os mesmos operadores de uma query de tabela.
Apenas consistência eventual — os GSIs replicam da tabela base de forma assíncrona. Adicionar --consistent-read a uma query de GSI não a atualiza; ela falha com uma ValidationException. (Índices secundários locais suportam consistência forte.)
Você obtém apenas os atributos projetados — uma query de GSI retorna o que o índice projeta (ALL, KEYS_ONLY ou os atributos listados em INCLUDE) e não pode buscar o resto na tabela base.
As chaves não são únicas em um GSI — muitos itens podem compartilhar a mesma chave de índice, e itens que não têm o atributo da chave de índice simplesmente não aparecem (esse é o padrão de índice esparso).
A paginação é automática — a CLI segue os tokens de paginação do serviço nos bastidores e imprime o resultado combinado. Use --max-items para limitar a saída (aparece um NextToken; retome com --starting-token), ou --no-paginate para uma única chamada de serviço.

Faça visualmente

O DynamoDB Expression Builder constrói a key condition + mapas de nome/valor para queries de índice e entrega um comando de CLI pronto para executar.

Para navegar nos índices de uma tabela e executar queries de GSI a partir de um formulário — grade paginada, copiar como CLI — baixe o DynoTable.

Exemplos relacionados

Consultar um GSI do DynamoDB em Node.js — a mesma query de índice com o AWS SDK v3.
Consultar um GSI do DynamoDB em Python — a mesma query de índice com boto3.
DynamoDB Query com a AWS CLI — consultando a tabela base.
GSI vs. LSI — qual tipo de índice se encaixa no padrão de acesso.
Por que os GSIs têm consistência eventual — o atraso de replicação explicado.
"The table does not have the specified index" — o nome do índice não corresponde (os 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.

References

Última verificação em 2026-07-13 contra a documentação oficial da AWS vinculada acima.