Como um DynamoDB GSI é armazenado internamente

UMÍndice Secundário Globalnão é um ponteiro de volta para sua mesa. É um separado, tabela gerenciada internamente — suas próprias partições, seu próprio esquema de chave, seu próprio capacidade - que DynamoDB mantém sincronizado, copiando gravações nele de forma assíncrona.

Vindo de SQL, um índice é uma árvore B fixada na mesma tabela física, atualizada dentro da mesma transação. Um GSI quebra ambas as suposições e quase cada surpresa GSI remonta a esse fato.

Como um DynamoDB GSI é armazenado?

Um DynamoDB GSI é armazenado como uma tabela separada e gerenciada internamente – suas próprias partições, esquema de chave e capacidade – não como um ponteiro para a tabela base. DynamoDB copia cada gravação no índice de forma assíncrona, armazenando apenas as chaves GSI, as chaves da tabela base e quaisquerprojetadoatributos.

• A GSI é sua própria tabela. Possui um espaço de partição totalmente independente codificado por a chave de partição do GSI, não a da tabela base.
• As gravações são replicadas de forma assíncrona. Sua gravação é confirmada primeiro na tabela base, então DynamoDB distribui para cada GSI em um caminho de fundo.
• Apenas atributos projetados são armazenados. O índice contém as chaves GSI, a base chaves, além de quaisquer atributos que você projetou - nada mais.
• A chave GSI não precisa ser exclusiva. Vários itens base podem compartilhar um GSI chave de partição/classificação; a basechave primáriaé o desempate que os mantém distinto.

Comece com um item base

Faça um registro de auditoria de SaaS. Cada ação privilegiada em um espaço de trabalho se torna um evento imutável. A tabela base, WorkspaceEvents, é codificada para que todos os os eventos do espaço de trabalho vivem em umcoleção de itens, ordenado por tempo:

EventPK = "WS#orbit-9" partições por espaço de trabalho; EventSK é um carimbo de data/hora ISO, então um Query retorna os eventos de um espaço de trabalho em ordem cronológica. Isso serve "mostre-me a linha do tempo deste espaço de trabalho" perfeitamente.

Não serve para mais nada. Você não pode perguntar "o que USR#kp fez em cada espaço de trabalho?" — actorId não é uma chave, então a única maneira de respondê-la na base tabela é um Scan completo. Esse é o padrão de acesso a GSI existe para adicionar.

Adicione um GSI e veja uma segunda mesa aparecer

Defina um GSI, ByActor, que reparticiona os mesmos eventos por quem os executou:

ByActor (GSI)
partition key = actorId   ("USR#kp")
sort key      = EventSK   ("TS#2026-06-23T14:02:11Z")

DynamoDB agora mantém uma segunda estrutura física. O mesmo evento lógico é armazenado duas vezes — uma vez na partição WS#orbit-9 da tabela base e novamente em a partição USR#kp do GSI:

Observe o que aconteceu: as chaves da tabela base (EventPK, EventSK) são armazenadas em cada item GSI automaticamente. É assim que um acerto GSI pode apontar você de volta para o item completo - e por que um KEYS_ONLY o índice ainda custa armazenamento.

O que realmente vive no GSI

O índice não copia o item inteiro. Cada entrada GSI contém exatamente três coisas, e você controla apenas a terceira:

Projeção é KEYS_ONLY, INCLUDE (uma lista nomeada) ou ALL. Um Query no GSI só pode retornar atributos que estão no índice.

Peça um que não seja projetado e DynamoDB não o busca de forma transparente

• você não recebe nada em troca por esse campo. (documentos AWS GSI)

Essa é a armadilha relacional invertida: SQL se juntaria novamente ao heap para o coluna faltante. Um GSI nunca o faz. Oprojeçãoé o contrato completo.

Como uma gravação chega ao índice

A replicação é a parte que mais quebra a intuição SQL. Uma escrita básica e sua atualização de índice não é uma operação atômica.

Quando você PutItem, DynamoDB se compromete de forma duradoura com a tabela base, reconhece seu escreve e então propaga a mudança em um caminho de segundo plano que atualiza cada GSI. A confirmação não espera pelo índice.

Ordem dos eventos para nossa gravação de auditoria, de cima para baixo:

O chamador recebe 200 OK na etapa três, antes que as etapas quatro a seis terminem - então um Query em ByActor na lacuna pode perder um evento totalmente novo.

Essa assincronia é intencional. Vem da linhagem de 2007 Artigo do Amazon Dynamo, que escolheu disponibilidade em vez de consistência síncrona. Todas as consequências vivem em por que um GSI é eventualmente consistente.

A chave GSI não é uma chave única

Em SQL, um índice secundário não exclusivo é o padrão e um índice único é um restrição que você aceita. Um GSI é o oposto: não tem nenhuma exclusividade garantia, sempre.

Dois eventos de auditoria do mesmo ator em carimbos de data e hora que colidem compartilhariam o mesmo GSI1PK e GSI1SK. DynamoDB armazena ambos - elimina a ambiguidade deles internamente pela chave primária da tabela base, que é sempre transportada.

Portanto, um GSI Query para um ator em um instante pode retornar legitimamente vários itens. Se você presumisse uma linha por chave da mesma forma que um índice exclusivo SQL forneceria, essa é a arma.

Quando você consulta o índice, o DynamoDB Expression Builder grava o KeyConditionExpression com nomes e valores escapados corretamente - por exemplo. correspondência um ator desde um corte:

KeyConditionExpression: "#a = :actor AND #ts > :since"
ExpressionAttributeNames:  { "#a": "actorId", "#ts": "EventSK" }
ExpressionAttributeValues: {
  ":actor": { "S": "USR#kp" },
  ":since": { "S": "TS#2026-06-01T00:00:00Z" }
}

A capacidade reside no índice, não na tabela

Como GSI é sua própria tabela, ela possui sua própria capacidade de leitura e gravação, faturado e regulado separadamente da tabela base. Uma leitura ByActor consome as unidades de leitura do GSI, nunca as da tabela.

O acoplamento reverso é a parte que morde. Cada gravação na tabela base também grava o índice, e se o GSI não puder absorver isso, ele pressiona a gravação base. Isso mecanismo recebe seu próprio guia - quando um GSI limita as gravações da tabela base.

É também por isso que a chave de partição de GSI é tão importante quanto a da tabela base. Um grupos de chaves GSI de baixa cardinalidade gravam em uma partição de índice mesmo quando base as gravações são perfeitamente distribuídas - uma partição ativa que você criou redigitando.

GSI amplificação de gravação (faturada)

Cada gravação de tabela base que se projeta em GSI custa base WCU + índice WCU em sob demanda em us-east-1. Um item de 1 KB com projeção ALL normalmente custa ~2 WCU total — um para a linha da tabela, um para a cópia do índice. KEYS_ONLY reduz a gravação do índice; ALL dobra o armazenamento e o amplificador de gravação. Tamanho do item do modelo e projeção na calculadora de preços.

Armadilhas e próximos passos

• Não espere atributos não projetados de volta. Um GSI Query retorna apenas o que as lojas de índice. Se você precisar do item completo, projete-o ou busque-o no tabela base pelas teclas transportadas.
• Não trate uma chave GSI como única. Planeje que um Query retorne mais de uma item por chave; a chave primária base é a única identidade real.
• Não leia um GSI logo após a gravação que o alimentou. O caminho assíncrono significa o o índice pode ainda não mostrar sua gravação - leia a tabela base quando precisar leia suas próprias escritas.
• Dimensione a capacidade do GSI deliberadamente. É independente de leituras e um dependência oculta de gravações.

O jogo todo é escolher formas-chave que atendam aos seus padrões - design de tabela única sobrecarrega um GSI em muitos deles; GSI vs LSI cobre quando um índice local se ajusta.

Crie e visualize seu GSI KeyConditionExpression no DynamoDB Expression Builder, então tente DynoTable para inspecionar os atributos projetados de um índice e observar escreve replicado no GSI em suas próprias tabelas.