O Limite de Tamanho de Item do DynamoDB (400 KB)

Um único item do DynamoDB pode conter no máximo 400 KB de dados. Vindo do MongoDB (documentos de 16 MB) ou de uma linha relacional sem teto prático, esse limite parece baixo — e você tende a descobri-lo do jeito difícil, quando uma escrita que funcionou por meses de repente falha com uma ValidationException porque um item finalmente cresceu demais.

O limite não é arbitrário, e não é uma cota que você pode aumentar. É uma restrição de modelagem, e os itens que a atingem geralmente estão te dizendo que os dados foram modelados errado.

Qual é o tamanho máximo de um item no DynamoDB?

O DynamoDB limita um único item a 400 KB — um limite rígido que você não pode aumentar. O tamanho conta nomes de atributos mais valores juntos, incluindo cada elemento aninhado de lista, mapa e conjunto. Os itens geralmente o atingem por crescimento ilimitado, como uma lista embutida em expansão constante; a solução é modelagem, dividir a coleção em itens separados, não compressão.

• 400 KB por item, teto rígido. Não ajustável, não é uma cota flexível.
• Tamanho = nomes de atributos + valores, juntos. Nomes de atributos longos contam, em cada item.
• Aninhamento e conjuntos contam também. Listas, mapas e seus valores aninhados todos somam.
• A causa usual é o crescimento ilimitado — embutir uma lista que cresce sem limite em um item pai.
• A solução é modelagem, não compressão. Divida a coleção que cresce em seus próprios itens sob uma chave de partição compartilhada.

O problema: o item que cresce para sempre

Digamos que você rastreia uma frota de veículos, e decide armazenar as leituras de telemetria de cada veículo como uma lista no item do veículo:

PK: VEHICLE#A1   readings: [ {ts, lat, lng, fuel}, {ts, lat, lng, fuel}, ... ]

Por um dia ou dois está tudo bem. Mas as leituras chegam a cada poucos segundos e nunca param, então a lista cresce sem limite. Eventualmente mais uma leitura empurraria o item além de 400 KB, e o DynamoDB rejeita a escrita com uma ValidationException: Item size has exceeded the maximum allowed size — você não consegue mais registrar telemetria alguma para aquele veículo, porque cada atualização reescreve o item inteiro.

O bug não é o limite de tamanho. É modelar um relacionamento um-para-muitos ilimitado como uma lista embutida. Isso só funciona quando o lado "muitos" é limitado e pequeno.

O que de fato conta para os 400 KB

O DynamoDB mede o tamanho total do item como a soma de:

• Cada nome de atributo, codificado em UTF-8. Um nome de 20 caracteres repetido por milhões de itens é tanto tamanho quanto armazenamento que você paga — é por isso que modeladores experientes mantêm os nomes de atributos curtos.
• Cada valor de atributo. Strings e binário pelo seu comprimento em bytes; números por uma codificação compacta; booleanos e nulos por um custo fixo minúsculo.
• Estrutura aninhada. Uma lista ou mapa conta seu próprio overhead mais o tamanho de cada elemento e chave dentro dela, até o fundo.

Não há um teto separado por atributo para planejar em torno — é o item inteiro contra a linha dos 400 KB. A documentação de tamanho de item da AWS detalha a contabilidade exata de bytes.

Por que o limite existe

Itens grandes são caros de mover. As leituras do DynamoDB são medidas em unidades de 4 KB, então um item de 400 KB custa 100 RCU para ler de forma forte — e leituras, escritas e replicação todas ficam mais lentas e caras conforme os itens crescem. O teto te empurra na direção de itens pequenos e direcionados e para longe do antipadrão "buscar um blob gigante" que iniciantes em NoSQL recorrem por hábito relacional.

Modelando em torno disso

Para o exemplo da frota, pare de embutir. Dê a cada leitura seu próprio item na mesma partição do veículo, ordenado por timestamp na chave de ordenação:

PK: VEHICLE#A1   SK: READING#2026-06-27T10:00:05Z   lat, lng, fuel
PK: VEHICLE#A1   SK: READING#2026-06-27T10:00:10Z   lat, lng, fuel

Agora nenhum item cresce, as escritas nunca ultrapassam o teto, e um único Query em VEHICLE#A1 ainda puxa as leituras de um veículo de volta como uma única coleção de itens ordenada. Sub-listas limitadas (um punhado de tags, um bloco de config fixo) podem ser embutidas sem problema; as ilimitadas viram itens.

Verificando o tamanho de um item no DynoTable

Antes de se comprometer com um formato, pese um item representativo. No DynoTable, abra um no Quick View e ele mostra o tamanho em bytes do item ao lado dos seus atributos — para você pegar um formato pesado demais enquanto navega em dados reais, no tempo de design em vez da escrita que falhou.

Prefere ficar no navegador? A calculadora de tamanho de item do DynamoDB faz o mesmo a partir de uma amostra colada, reportando os KB exatos e as RCU/WCU que cada leitura e escrita vão custar.

Verificado contra o DynamoDB

Regras de tamanho são fáceis de enunciar e fáceis de errar sutilmente, então conferimos as nossas contra a única autoridade que importa: o que o DynamoDB de fato cobra.

O truque é que ConsumedCapacity reporta unidades em vez de bytes, e uma escrita de N bytes custa ceil(N / 1024) WCU. Grosseiro no geral — mas exato numa fronteira. Um item construído para cair em exatamente 1024 bytes tem que custar 1 WCU, e um construído para cair em 1025 tem que custar 2, então um erro de um único byte na aritmética muda o número observado.

Seis de seis batem, e os pares de fronteira são os que carregam a prova: os itens de 1.024 e 1.025 bytes diferem por um único caractere de preenchimento e o DynamoDB os cobra de forma diferente, exatamente onde o nosso cálculo diz que o degrau cai.

A consequência prática é a que custa dinheiro. Um item um byte acima de um kilobyte custa uma WCU inteira a mais, e em 4 KB o mesmo precipício aparece no lado da leitura — então cortar um item de 1.025 bytes para 1.024 reduz pela metade o custo de escrita, enquanto enchê-lo de 1.024 para 1.025 dobra esse custo. Nomes de atributos contam para o total, e é por isso que encurtar chaves numa tabela quente não é micro-otimização.

Armadilhas + próximos passos

• Fique de olho em listas embutidas que crescem com o tráfego — elas são a clássica bomba-relógio de 400 KB. Limite-as ou divida-as.
• Encurte os nomes de atributos em itens de alta cardinalidade — é tamanho e armazenamento de graça de volta.
• Valores grandes pertencem ao S3. Armazene blobs grandes (imagens, documentos) no S3 e mantenha apenas a chave no item.
• Relacionados: desnormalização e relacionamentos um-para-muitos cobrem quando embutir vs dividir.

Quer ver os tamanhos reais dos itens de uma tabela num relance? Baixe o DynoTable e inspecione seus dados diretamente.

Números de capacidade verificados em 2026-07-26 no serviço DynamoDB real em us-east-1 (pnpm content:verify-item-size).