EventBridgeComunidade
Nível de dificuldade: Intermediário (3 de 5)
Distributed Map do Step Functions tira o SQS improvisado do processamento de CSV grande
O recurso Distributed Map do Step Functions processa arquivos de centenas de milhares de linhas direto do S3, em paralelo, sem fila própria nem contador de progresso caseiro. O ganho real para quem opera em produção está nos limites que ele remove e nas permissões de IAM que ele exige.
O problema que todo projeto serverless reinventa
Quem desenha pipelines serverless já viu essa montagem: uma Lambda lê um CSV grande, empurra cada linha para uma fila no SQS, um worker consome e processa, e no final ninguém sabe ao certo se todas as linhas chegaram ao destino. Um artigo publicado na DEV Community por Sascha, mantenedor do blog sascha-ms.de, descreve exatamente esse padrão improvisado como o ponto de partida do problema que o Distributed Map do Step Functions resolve.
A proposta é diferente: você descreve de onde vem o arquivo, qual o tamanho dos lotes e quantos podem rodar ao mesmo tempo, e o Step Functions cuida do resto, incluindo um limite de falhas tolerado e um relatório de resultado gravado no S3.
Step Functions cuida de todo o resto, incluindo um limite de falhas tolerado e um relatório de resultado no S3.
Step Functions takes care of everything else, including a failure threshold and a result report in S3.Sascha, autor do artigo na DEV Community
Map inline e Distributed Map: por que o limite de 40 iterações existe
O Step Functions oferece o estado Map em duas variantes, e a diferença não é estética. O Map inline roda dentro da própria execução que o chamou, com três travas conhecidas de quem já esbarrou nelas em produção.
| Limite | Map inline | Distributed Map |
|---|---|---|
| Tamanho do input | até 256 KiB (cabe no payload da execução) | lê direto do S3, sem esse teto |
| Histórico de eventos | compartilhado, até 25.000 entradas | cada child workflow tem o próprio histórico |
| Iterações em paralelo | até 40 | até 10.000 workflows filhos simultâneos |
A fonte resume em três sinais práticos para decidir a troca: o conjunto de dados passa de 256 KiB, uma única execução ultrapassaria 25.000 entradas no histórico, ou você precisa de mais de 40 iterações rodando ao mesmo tempo. Se nenhum desses três casos se aplica, fique no Map inline: ele é mais simples de ler e evita as permissões extras de IAM que o Distributed Map exige.
As quatro peças que fazem o Distributed Map funcionar
Quatro elementos do estado Map fazem o trabalho pesado, e entender como eles se combinam é o que separa uma configuração que funciona de uma que trava na primeira tentativa.
ItemReader: lê o arquivo direto do S3 coms3:getObject, suportando CSV, JSON, JSON Lines ou Parquet; no exemplo da fonte,CSVHeaderLocation: FIRST_ROWusa a primeira linha como nome das colunas eCSVDelimiter: SEMICOLONlida com exportações no padrão de planilha europeia.ItemBatcher: agrupa várias linhas num único child workflow em vez de abrir um por linha; o exemplo usaMaxItemsPerBatch: 500, respeitando o teto de 256 KiB por lote.MaxConcurrency: limita quantos child workflows rodam ao mesmo tempo; sem essa configuração, o Step Functions chega a disparar até 10.000 de uma vez, o que derruba qualquer tabela ou API de terceiros que não foi dimensionada para isso.ResultWriter: grava o resultado de todos os child workflows em bloco no S3, em vez de empilhar tudo na saída da execução.
O caso de uso: importar um catálogo em lotes de 500 linhas
O exemplo que a fonte constrói é o de uma biblioteca que recebe todo dia um export do catálogo consolidado: um CSV com separador ponto e vírgula, centenas de milhares de linhas com ISBN, título, autor, ano e número de exemplares. Cada linha precisa de validação própria (dígito verificador do ISBN, título presente, ano plausível), e um único erro de digitação na exportação não pode derrubar a importação inteira.
A Lambda que processa cada lote recebe um objeto com um campo Items (a lista de linhas) em vez de uma linha isolada, exatamente porque o ItemBatcher está ativo. Ela valida tudo, grava os registros válidos no DynamoDB em blocos de 25 itens, o teto do BatchWriteCommand, e devolve as linhas rejeitadas com o motivo.
for (const row of event.Items) {
const result = validateRow(row);
if (result.ok) valid.push(result.book);
else rejected.push({ isbn: row.isbn ?? '', reason: result.reason });
}Um detalhe de arquitetura importa mais do que parece: a função não lança exceção para um ISBN inválido, ela devolve um resultado estruturado. Erro de negócio (linha mal formatada) e erro técnico (DynamoDB fora do ar) seguem caminhos diferentes, e só o segundo deve derrubar o child workflow. Quando o BatchWriteCommand devolve itens em UnprocessedItems, a função reenvia com espera crescente e aleatória (exponential backoff com jitter), e só lança erro de fato depois de cinco tentativas, deixando o retry do próprio Step Functions assumir dali em diante.
Standard para o pai, Express para os filhos
O workflow pai, o que contém o estado Map, precisa ser do tipo Standard. Os child workflows podem ser Standard ou Express, e a fonte escolhe Express para eles porque cada um só repassa um lote para uma Lambda, uma tarefa curta e previsível. Workflows Express rodam no máximo cinco minutos e são cobrados por contagem e duração, um modelo mais barato para esse tipo de tarefa do que o modelo de transições de estado do Standard. Para quem desenha o pipeline, essa escolha já é uma decisão de custo, não só de funcionalidade.
As permissões de IAM que travam a primeira tentativa
A fonte é direta ao dizer que a maioria das primeiras tentativas falha aqui, não na lógica de negócio. A role do state machine precisa de mais do que invocar a Lambda:
states:StartExecutionna própria state machine, porque tecnicamente cada child workflow é uma nova execução dela mesma;states:DescribeExecutionpara o pai conseguir checar o estado dos filhos;s3:GetObjectrestrito à pasta de entrada e permissões de escrita (incluindo multipart upload) restritas à pasta de resultados;states:RedriveExecution, se você quiser reiniciar execuções que falharam parcialmente sem repetir tudo.
O ponto mais sutil é a dependência circular: a role precisa saber o ARN da state machine, e a state machine precisa da role. A fonte resolve isso dando um nome fixo à state machine e montando o ARN como texto simples dentro da definição da role, deixando o Serverless Framework resolver ${aws:region} e ${aws:accountId} no deploy.
Quando não vale a pena trocar o Map inline
Se o volume de dados é pequeno, cabe tranquilamente no payload de 256 KiB e não passa de 40 iterações simultâneas, o Distributed Map é complexidade sem retorno: mais permissões de IAM para gerenciar, mais um nível de indireção para depurar. A fonte ainda aponta uma alternativa específica: quando a necessidade é só despejar dados do S3 numa tabela do DynamoDB existente, sem validação própria por linha, o recurso DynamoDB Bulk Put Items resolve sem o aparato inteiro do Distributed Map. O Distributed Map compensa quando cada linha precisa de código próprio: validação, enriquecimento ou chamada a um sistema de terceiros, como no exemplo do catálogo.
O que fica em aberto
A fonte não traz números de custo específicos para comparar o Distributed Map com a fila improvisada em produção, então essa conta cabe a cada equipe fazer com o próprio volume de dados. O exemplo original roda em eu-central-1; quem precisar rodar em outra região da AWS deve validar a disponibilidade dos serviços envolvidos (Step Functions, Lambda, S3 e DynamoDB) e ajustar o serverless.yml conforme a documentação oficial da região escolhida.
Fica também em aberto, para quem for adotar o padrão, testar o comportamento de ToleratedFailurePercentage sob falha real, e não só em teoria: é o parâmetro que decide se um Map Run continua rodando com 5% de linhas rejeitadas ou para tudo com States.ExceedToleratedFailureThreshold.
Fonte: DEV Community — #aws
Serviços neste textoEventBridgeStep Functions
Leve para a sua IA
Decida com o seu assistente, com o contexto deste texto já montado.
1. O que você quer saber
Ver o prompt
Li no AWS Hub: "Distributed Map do Step Functions tira o SQS improvisado do processamento de CSV grande" (https://awshub.com.br/comunidade/distributed-map-do-step-functions-tira-o-sqs-improvisado-do-processamento-de-csv). Resumo: O recurso Distributed Map do Step Functions processa arquivos de centenas de milhares de linhas direto do S3, em paralelo, sem fila própria nem contador de progresso caseiro. O ganho real para quem opera em produção está nos limites que ele remove e nas permissões de IAM que ele exige. Serviços: EventBridge, Step Functions Minha stack: [descreva em uma linha: serviços, linguagem, volume, região] Isso muda alguma coisa na minha arquitetura? O que eu faria diferente a partir de amanhã?