Como as Partition Keys do DynamoDB Funcionam

Sua partition key não é uma coluna — é um endereço. O DynamoDB faz hash dessa chave e o hash decide qual máquina física guarda o item. Escolha a chave bem e a carga se espalha; escolha mal e um servidor leva todo o calor.

Como as partition keys do DynamoDB funcionam?

O DynamoDB passa sua partition key por uma função de hash interna, e esse hash decide qual partição física armazena o item. A chave não é ordenada nem indexada como uma coluna SQL — é um endereço. Escolha uma chave de alta cardinalidade e a carga se espalha por muitas partições; escolha uma de baixa cardinalidade e uma única partição leva todo o calor.

• A chave é hasheada, não ordenada. O DynamoDB passa sua partition key por um hash interno para escolher uma partição. Dois valores adjacentes caem em lugares nada próximos no disco.
• Uma partição é uma unidade de armazenamento real. Cada uma satura por volta de 10 GB, 3.000 unidades de leitura/s e 1.000 unidades de escrita/s. Seu tráfego é dividido por quantas partições suas chaves espalham.
• Hot keys são o footgun. Funile a maioria das requisições para um único valor de partition key e você sofre throttling naquela partição enquanto o resto da tabela fica ocioso.
• Chaves de alta cardinalidade vencem. Quanto mais valores de chave distintos e uniformemente acessados você tiver, mais partições absorvem a carga.

Comece pelo que a chave realmente faz

Vindo do SQL, uma primary key é uma coluna ordenada e indexada na qual você faz JOIN e ORDER BY. No DynamoDB a partition key (às vezes chamada de hash key) faz algo diferente: ela decide o posicionamento.

O DynamoDB alimenta a partition key em uma função de hash interna. A saída mapeia para um keyspace, e o keyspace é fatiado em faixas — cada faixa possuída por uma partição física. Essa partição é armazenamento real em um nó real.

Então a partition key responde uma pergunta: qual máquina guarda este item? A sort key, se você tiver uma, só ordena itens dentro daquela máquina. Ela não tem papel algum no posicionamento.

Acompanhe uma escrita pelo hash

Digamos que você roda um SaaS que ingere leituras de dispositivos. Sua tabela SensorReadings usa uma partition key deviceId e uma sort key readingTs. Você escreve uma leitura para deviceId = "vac-7741".

Aqui está o caminho que essa escrita percorre — da sua chave ao disco onde ela cai:

A escrita para vac-7741 é hasheada para um ponto no keyspace, esse ponto cai na faixa de P2, e o item aterrissa em P2 — ordenado ali por readingTs.

O que internalizar: "vac-7741" e "vac-7742" estão a um caractere de distância, mas seus hashes não têm relação. Eles quase certamente vivem em partições diferentes. Não existe "próximo" no keyspace de partição.

Essa é a ideia de consistent hashing que o DynamoDB herdou do design original — o paper Amazon Dynamo de 2007 ("Dynamo: Amazon's Highly Available Key-value Store") espalhava chaves pelos nós fazendo hash exatamente para que nenhum nó único virasse um gargalo.

Respeite os limites rígidos da partição

Uma partição física é finita. Conforme o AWS DynamoDB Developer Guide, cada uma comporta até cerca de:

Quando uma partição enche além de 10 GB, ou seu throughput provisionado precisa de mais espaço, o DynamoDB divide ela — a faixa do keyspace é dividida e os itens se redistribuem por mais partições. Isso é automático; você não dispara o processo.

A pegadinha: uma divisão espalha itens pelo seu hash. Se toda requisição quente mira um único valor de partition key, dividir não ajuda — todo esse tráfego ainda faz hash para o mesmo ponto. Você não consegue dividir a carga de uma única chave entre partições.

Nomeie a armadilha: a hot partition

Uma hot partition é o footgun clássico. Acontece quando um valor de partition key (ou um conjunto minúsculo deles) absorve uma fatia desproporcional do tráfego.

Falha concreta: você troca SensorReadings para uma partition key region com valores como "us-east", "eu-west". Três regiões significa três valores de chave significa — no máximo — três partições fazendo trabalho real. Bombardeie "us-east" com leituras e ela sofre throttling em 3.000 RCU enquanto a capacidade total provisionada da tabela fica sem uso.

A adaptive capacity do DynamoDB suaviza isso — ela consegue deslocar throughput não usado em direção a uma partição ocupada e isolar uma única chave muito quente em sua própria partição. A AWS detalhou isso nas sessões deep-dive "Advanced Design Patterns for DynamoDB" do re:Invent. Mas a adaptive capacity compra tempo, não imunidade: ela não consegue subdividir a carga de uma chave individual. Projete para espalhar; não se apoie na rede de segurança.

Escolha uma chave de alta cardinalidade

A correção é cardinalidade — o número de valores de chave distintos, e quão uniformemente o tráfego os atinge.

• Baixa cardinalidade (region, status, true/false): poucas partições, o tráfego concentra, você sofre throttling cedo.
• Alta cardinalidade (deviceId, userId, um ID de pedido): muitos valores fazendo hash por muitas partições, a carga se espalha, a folga cresce.

Vindo do SQL você indexaria de boa uma coluna status e filtraria por ela. Como partition key do DynamoDB isso é uma armadilha — ela não consegue espalhar. Mantenha atributos de baixa cardinalidade como filtros ou como sort key de um índice secundário, nunca como a coisa que decide o posicionamento.

Quando uma chave naturalmente boa ainda inclina — um punhado de tenants baleia superando o resto — adicione um sufixo para distribuir um valor lógico entre N partições, ex.: tenantId#3 para um caminho de escrita fragmentado. Você reagrega na leitura.

Para mirar itens dentro de uma partição depois que sua chave está espalhada, você escreverá uma KeyConditionExpression na sort key. Você pode montar uma contra seu próprio schema no DynamoDB expression builder antes de fiá-la no código:

deviceId = "vac-7741" AND readingTs BETWEEN "2026-06-01" AND "2026-06-30"

Isso lê a janela de junho de um dispositivo de uma única partição — um Query, não um Scan. A partition key fixa a máquina; a condição de sort key restringe as linhas.

Armadilhas e próximos passos

• Não escolha uma chave pelo que lê bem no SQL. Escolha-a pelo que espalha. Cardinalidade primeiro, conveniência de query depois.
• Não suponha que a capacidade total da tabela é sua por chave. O throughput é por partição; um valor quente pode sofrer throttling enquanto a tabela parece ociosa.
• Não lute contra uma divisão. Ela é automática e guiada por hash — seu trabalho é dar a ela chaves distintas suficientes para espalhar.

Uma vez que sua chave espalha de forma limpa, as próximas decisões são como dispor os itens dentro de uma partição — veja single-table design — e quando um índice secundário é a ferramenta certa para um segundo padrão de acesso.

Baixe o DynoTable para navegar por suas partições e distribuição de chaves reais, e detectar uma hot key antes que ela te chame de madrugada.