Consultar um GSI do DynamoDB em Python (boto3)

Consultar um índice secundário global é um query normal mais um parâmetro: IndexName. 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

import boto3

client = boto3.client("dynamodb")

paginator = client.get_paginator("query")

items = []
for page in paginator.paginate(
    TableName="Music",
    IndexName="AlbumTitle-index",
    KeyConditionExpression="#hashKey = :hashKeyValue",
    ExpressionAttributeNames={"#hashKey": "AlbumTitle"},
    ExpressionAttributeValues={":hashKeyValue": {"S": "Danzon"}},
):
    items.extend(page["Items"])

print(f"Found {len(items)} songs on the album")

Explicação

IndexName — nomeia o GSI a consultar (TableName ainda é obrigatório). A KeyConditionExpression 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. Passar ConsistentRead=True em uma query de GSI não a atualiza; ela levanta 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. Precisa de um atributo não projetado? Faça um get_item de acompanhamento na chave da tabela, ou amplie a projeção.
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).
Paginação — client.get_paginator("query") segue o LastEvaluatedKey por todas as páginas exatamente como numa query de tabela; cada page carrega uma lista Items.
Na API resource, a mesma query é table.query(IndexName="AlbumTitle-index", KeyConditionExpression=Key("AlbumTitle").eq("Danzon")) com valores nativos do Python.

Faça visualmente

O DynamoDB Expression Builder constrói a key condition + mapas de nome/valor para queries de índice e copia código boto3 executável.

Para navegar nos índices de uma tabela e executar queries de GSI a partir de um formulário — grade paginada, copiar como código — 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 com a AWS CLI — a mesma query de índice a partir do shell.
DynamoDB Query em Python — 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.