DynoTable
Iniciante4 min de leitura

Tipos de dados do DynamoDB

Todo atributo do DynamoDB é marcado com um código de tipo de uma ou duas letras no formato de transmissão. Conhecer o conjunto importa porque o tipo determina tanto como um valor é armazenado quanto como ele conta para o tamanho de um item.

Quais tipos de dados o DynamoDB suporta?

O DynamoDB suporta dez tipos de dados em três categorias. Escalares são String (S), Number (N), Binary (B), Boolean (BOOL) e Null (NULL). Documentos são Map (M) e List (L), que aninham outros tipos. Conjuntos são String Set (SS), Number Set (NS) e Binary Set (BS) — não ordenados, homogêneos e não vazios. Apenas S, N e B podem ser uma chave.

CódigoTipoCategoriaEquivalente JSON / JSExemplo (DynamoDB-JSON)
SStringEscalarstring{"S": "Ada"}
NNumberEscalarnumber{"N": "37"}
BBinaryEscalarUint8Array / base64{"B": "ZGF0YQ=="}
BOOLBooleanEscalarboolean{"BOOL": true}
NULLNullEscalarnull{"NULL": true}
MMapDocumentoobject{"M": {"k": {"S": "v"}}}
LListDocumentoarray{"L": [{"N": "1"}]}
SSString setConjunto— (sem tipo JSON){"SS": ["a", "b"]}
NSNumber setConjunto—{"NS": ["1", "2"]}
BSBinary setConjunto—{"BS": ["ZA=="]}

Escalares

  • S — string (UTF-8; dimensionada pelo comprimento em bytes, não pela contagem de caracteres).
  • N — número, enviado como string por precisão; até 38 dígitos.
  • B — binário, enviado codificado em base64.
  • BOOL — true / false.
  • NULL — um marcador explícito de null.

Documentos

  • M — map (objeto). Os atributos aninhados mantêm cada um sua própria etiqueta de tipo.
  • L — list. Os elementos podem ter tipos mistos.
{"profile": {"M": {"name": {"S": "Ada"}, "age": {"N": "37"}}}}

Conjuntos

  • SS — string set, NS — number set, BS — binary set.

Os conjuntos são não ordenados, homogêneos e não podem ser vazios. Fundamentalmente, o JSON puro não tem tipo de conjunto — um array vai e volta como uma list (L), nunca como um SS/NS. Isso é uma limitação real de conversão, não um bug; veja a nota do conversor de DynamoDB-JSON.

Quais tipos podem ser uma chave?

As chaves de e de — na tabela e em qualquer índice — devem ser um escalar, e apenas S, N ou B. Você não pode indexar por um boolean, conjunto, map ou list. Modele uma chave "composta" concatenando valores em um único S (por exemplo, ORDER#2026#42).

Limites que vale conhecer

  • Um item chega no máximo a 400 KB — cada nome de atributo mais o valor, incluindo os aninhados.
  • Os números carregam até 38 dígitos de precisão (positivos ou negativos).
  • Maps e lists aninham até 32 níveis de profundidade.
  • Os conjuntos são não vazios e homogêneos — sem conjunto vazio, sem misturar S e N.

Por que o tipo afeta o custo

O tamanho do item é a soma dos bytes dos nomes de atributo mais os bytes dos valores, e cada tipo é dimensionado de forma diferente — números são compactados, booleans e nulls têm 1 byte, maps e lists adicionam overhead por elemento. Esse tamanho é arredondado para cima até unidades de capacidade de leitura/escrita capacity units. Meça um item real com a calculadora de tamanho de item.

Faça isso no DynoTable

A distinção conjunto-vs-list acima é justamente o que as ferramentas costumam esconder. O editor de itens do DynoTable a torna explícita com um alternador de formato:

  • JSON puro — os primitivos permanecem simples ("age": 30), mas os conjuntos mantêm seu invólucro de tipo para que sobrevivam à ida e volta: "tags": { "SS": ["a", "b"] }, "scores": { "NS": ["1.5", "2.5"] }. Esta é a forma legível para a edição do dia a dia.
  • DynamoDB JSON — a forma canônica da AWS, onde cada valor carrega sua etiqueta de tipo: "age": { "N": "30" }, "name": { "S": "alice" }.

Alternar entre elas mostra exatamente como cada tipo escalar, de documento e de conjunto é representado no formato de transmissão — e, como os tipos de conjunto não têm equivalente em JSON puro, o alternador é a única forma de escrever um SS/NS/BS à mão sem fazer o marshalling do item inteiro manualmente.

O editor de itens do DynoTable mostrando um item com um number set e um string set, e o alternador JSON puro / DynamoDB-JSON.
O editor de itens do DynoTable mostrando um item com um number set e um string set, e o alternador JSON puro / DynamoDB-JSON.

Experimente o DynoTable para ver o tipo de cada atributo e a contagem de bytes ao vivo enquanto você edita um item — e para filtrar ou agregar entre atributos tipados no SQL Workbench, que lê cada etiqueta de tipo por você. Para converter um blob marshalled sem o app, o conversor de DynamoDB-JSON faz a mesma ida e volta no navegador.

Atualizado