DynamoDB: importar do S3 sempre cria uma tabela nova, nunca atualiza a existente

DynamoDB: importar do S3 sempre cria uma tabela nova, nunca atualiza a existente

A documentação oficial é clara: o import nativo do Amazon S3 para o DynamoDB sempre gera uma tabela do zero. Veja formatos aceitos, permissões IAM, o que acontece com chaves duplicadas e o caminho real para popular uma tabela que já existe.

Nota da redação: duas ressalvas sobre este texto. Primeiro, a seção sobre a divergência entre itens processados e itens efetivamente gravados na tabela atribui esse efeito à rejeição por schema incompatível; a documentação oficial, porém, liga esse comportamento especificamente ao caso de chaves duplicadas/sobrescritas, não ao de schema incompatível. Segundo, os detalhes do comando aws dynamodb import-table (sintaxe, parâmetros, formato de retorno do ImportArn e acompanhamento via describe-import) não foram encontrados na documentação usada como fonte deste artigo; são apresentados de forma ilustrativa e devem ser conferidos na documentação oficial antes de uso em produção. A tese central do artigo, de que o import do S3 sempre cria uma tabela nova e não atualiza uma existente, foi confirmada na fonte.

O que a documentação realmente diz

Antes de qualquer passo a passo, vale alinhar a expectativa: a página oficial de importação do Amazon S3 para o DynamoDB é explícita sobre um ponto que costuma pegar quem já tem uma tabela em produção. Segundo a documentação, "durante o processo de importação do Amazon S3, o DynamoDB cria uma nova tabela de destino para a qual os dados serão importados" e que "a importação para tabelas existentes não é suportada atualmente por esse recurso".

Ou seja: não existe um comando ou opção no console que pegue um arquivo no S3 e jogue linha por linha dentro de uma tabela DynamoDB que você já usa. Todo import cria uma tabela nova, do zero, com o schema que você declarar no momento da importação. Se a sua pauta era "atualizar a tabela de produção direto do S3", o recurso nativo não resolve isso sozinho, e o restante deste texto explica tanto o que ele faz de verdade quanto o caminho real para o resultado que você provavelmente queria.

Formatos aceitos e como preparar o bucket

O S3 import aceita três formatos de arquivo, e qualquer um deles pode estar comprimido ou não:

• CSV: cada linha vira um item, com o cabeçalho definindo os atributos.
• DynamoDB JSON: o formato nativo do DynamoDB, com os tipos (S, N, M, L etc.) explícitos em cada valor.
• Amazon Ion: superset binário/textual de JSON usado internamente pela AWS, com tipagem mais rica.

A compressão aceita é ZSTD ou GZIP; dá para importar sem compressão também. A fonte dos dados pode ser um único objeto do S3 ou vários objetos que compartilham o mesmo prefixo (KeyPrefix), útil quando você exporta dados particionados por um job de ETL. O bucket pode até pertencer a outra conta AWS, desde que você tenha as permissões corretas para ler aquele bucket específico (a própria documentação remete a uma página separada sobre configuração e permissões do Amazon S3, que não foi usada como fonte aqui), e a tabela nova pode nascer numa região diferente da do bucket de origem.

A chave primária decide o sucesso

Como a importação sempre cria a tabela, você declara o KeySchema (partition key e, se houver, sort key) no momento do pedido de import, junto com os AttributeDefinitions. É aqui que mora o erro mais comum: se o atributo que você apontou como chave primária não existe em algum item do arquivo de origem, ou existe com um tipo diferente do declarado (por exemplo, a chave foi definida como número mas o CSV traz a coluna como texto), aquele item não entra na tabela.

A documentação é direta sobre a consequência financeira disso: "itens que são processados mas falham ao carregar na tabela devido a formatação ou outras inconsistências nos dados de origem também são cobrados como parte do processo de importação". Na prática, um arquivo com schema incompatível não só falha silenciosamente para parte dos registros, como você paga pelo processamento desses registros rejeitados. Vale conferir o resumo da importação (ImportTableDescription) depois que ela termina: o campo de itens processados costuma divergir do número de itens que de fato chegaram na tabela quando há rejeição por schema.

Como o import trata chaves duplicadas

O comportamento aqui também surpreende quem espera um erro de chave duplicada. Segundo a documentação, "os atributos associados às chaves devem ser únicos na tabela base. Se alguma chave não for única, a importação sobrescreverá os itens associados até que reste apenas a última sobrescrita". O exemplo dado pela própria AWS: se a chave primária é o mês e vários itens têm o mês de setembro, cada novo item sobrescreve o anterior, e só um item com chave "setembro" sobrevive no final.

Em resumo: não há deduplicação inteligente nem merge de atributos entre itens com a mesma chave. É last write wins, na ordem em que o DynamoDB processa o arquivo, sem garantia documentada de qual registro do S3 "vence" quando há empate.

O que afeta o tempo de importação

Não existe um número fixo de minutos por gigabyte na documentação, porque o tempo depende de um conjunto de fatores que a própria AWS lista: tamanho dos dados, formato do arquivo, esquema de compressão, uniformidade da distribuição das chaves, número de objetos no S3 e variáveis relacionadas. O ponto mais prático desse parágrafo é sobre distribuição de chaves: "se a chave do seu índice secundário usa o mês do ano para particionamento, e todos os seus dados são de dezembro, importar esses dados pode levar significativamente mais tempo".

Isso é o mesmo princípio de hot partition que já vale para gravação normal no DynamoDB, só que aplicado ao processo de import: dados com chave bem distribuída importam mais rápido que dados concentrados num único valor de partição. Antes de rodar um import grande, vale olhar a cardinalidade da partition key no seu dataset.

Permissões IAM mínimas

Nota da redação: o código desta seção não foi executado em ambiente real nem extraído da documentação oficial de import; é um exemplo ilustrativo baseado em práticas comuns de IAM na AWS. A página de importação do S3 para o DynamoDB não detalha ações IAM específicas, apenas menciona que é preciso ter "as permissões corretas" e remete a uma página separada sobre configuração e permissões do Amazon S3. Valide e ajuste a política antes de usar em produção.

Para pedir a importação você precisa, no mínimo, de permissão para criar a tabela de destino e ler o bucket de origem. Um exemplo de política que cobre esse cenário, a título de ilustração:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:ImportTable",
        "dynamodb:DescribeImport",
        "dynamodb:CreateTable"
      ],
      "Resource": "arn:aws:dynamodb:sa-east-1:123456789012:table/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::meu-bucket-origem",
        "arn:aws:s3:::meu-bucket-origem/*"
      ]
    }
  ]
}

Se o bucket for de outra conta, também é preciso garantir, naquele bucket específico, as permissões corretas de leitura: a documentação trata isso em uma página separada sobre configuração e permissões do Amazon S3, que não detalha aqui o mecanismo exato. E como todo pedido de import passa pelo AWS CloudTrail, qualquer tentativa (bem-sucedida ou não) fica registrada nos logs de API do DynamoDB, o que ajuda a auditar quem disparou uma importação em produção.

O comando que de fato cria a tabela

Via AWS CLI, o pedido de importação é feito com aws dynamodb import-table, apontando o bucket de origem e os parâmetros de criação da tabela nova:

aws dynamodb import-table \
  --s3-bucket-source Bucket=meu-bucket-origem,KeyPrefix=exports/2026-11/ \
  --input-format DYNAMODB_JSON \
  --input-compression-type GZIP \
  --table-creation-parameters '{
    "TableName": "PedidosImportados",
    "AttributeDefinitions": [
      {"AttributeName": "pedidoId", "AttributeType": "S"}
    ],
    "KeySchema": [
      {"AttributeName": "pedidoId", "KeyType": "HASH"}
    ],
    "BillingMode": "PAY_PER_REQUEST"
  }' \
  --region sa-east-1

O retorno traz um ImportArn que você acompanha com aws dynamodb describe-import --import-arn <arn> até o status virar COMPLETED. É só nesse ponto que PedidosImportados existe de verdade e pode ser consultada, com os índices secundários globais (GSI) já ativos, se você declarou algum no table-creation-parameters, índices secundários locais (LSI) não são suportados nesse fluxo.

O caminho real para popular uma tabela que já existe

Como o recurso nativo não atualiza tabela existente, o padrão que funciona tem duas etapas. Primeiro, importe o arquivo do S3 para uma tabela de staging com import-table, exatamente como acima. Depois, mova os itens dessa tabela de staging para a tabela de produção, o que exige algum processo de leitura e escrita: um scan na tabela de staging seguido de batch-write-item na tabela de destino, rodado via script, via AWS Glue job ou via Lambda.

Se a meta é apenas substituir o conteúdo inteiro de uma tabela (uma carga diária completa, por exemplo), existe um atalho mais simples que evita qualquer cópia item a item: importe sempre para uma tabela nova com nome versionado (PedidosImportados-20261110) e troque o nome da tabela que a aplicação consulta, por variável de ambiente ou parâmetro no Parameter Store. A tabela antiga fica disponível por um tempo como rollback e depois é apagada. Isso não precisa de Lambda nem de merge de itens, só exige que a aplicação não dependa de um nome de tabela fixo.

Fonte: Amazon DynamoDB, Importing Amazon S3 data into a table (docs.aws.amazon.com/amazondynamodb/latest/developerguide/S3DataImport.HowItWorks.html).

Fonte: Amazon DynamoDB — Importing Amazon S3 data into a table