iterador¶

controle

executa um sub-fluxo (loop body) para cada linha de uma tabela upstream — o nó de repetição da plataforma, usado quando uma etapa do pipeline precisa rodar uma vez por item de uma lista (ex: uma chamada de api por cliente).

quando usar¶

chamar uma api uma vez por registro (ex: buscar detalhes de cada pedido individualmente, quando a api não oferece um endpoint em lote)
processar arquivos ou tabelas por item de uma lista de configuração (ex: uma tabela por schema, uma extração por filial)
lidar com fontes que exigem paginação por item específico em vez de paginação nativa do conector

como funciona¶

o iterador é um container no canvas: você arrasta outros nós para dentro dele, formando o "corpo do loop". para cada linha da tabela que chega ao iterador, a plataforma executa esse sub-fluxo uma vez, injetando os valores da linha atual como variáveis de pipeline ({{ pipeline.row.<coluna> }}).

os resultados de cada iteração são acumulados progressivamente em um único dataset de saída, conforme o modo de chunking configurado.

[fonte: lista de clientes]
      ↓
┌─── iterador ─────────────────────┐
│  [auth rest]* → [api rest: detalhes do cliente] │
└───────────────────────────────────┘
      ↓ (resultados acumulados)
[coletor / fábrica / lakehouse writer]

* opcional — apenas quando a api exige reautenticação periódica

configuração¶

campo	tipo	obrigatório	descrição
`chunk_mode`	enum	não	`none`, `rows` ou `size_mb` — ver chunking · padrão: `none`
`chunk_rows`	number	condicional	linhas acumuladas antes de liberar memória · usado quando `chunk_mode = rows`
`chunk_size_mb`	number	condicional	tamanho estimado (mb) antes de liberar memória · usado quando `chunk_mode = size_mb`
`chunk_check_interval`	number	não	a cada quantas iterações o tamanho é verificado (modo `size_mb`) · padrão: `50`
`persist_table`	string	sim	nome base usado para identificar o resultado do iterador
`compression`	enum	não	`snappy`, `zstd` ou `gzip` · padrão: `snappy`
`fail_on_item_error`	bool	não	se `true`, um erro em qualquer item interrompe o pipeline inteiro · padrão: `false`
`max_errors`	number	não	número máximo de erros tolerados antes de abortar a iteração

chunking para fontes grandes¶

quando a lista de itens é muito grande (milhares a milhões de linhas), manter tudo em memória até o fim não é viável. o chunk_mode controla quando os resultados acumulados são liberados:

modo	comportamento
`none`	mantém tudo em memória até o final — adequado para listas pequenas/médias
`rows`	libera a cada `chunk_rows` linhas acumuladas
`size_mb`	libera quando o tamanho estimado ultrapassa `chunk_size_mb`, verificado a cada `chunk_check_interval` iterações

exemplo¶

{
  "chunk_mode": "rows",
  "chunk_rows": 5000,
  "persist_table": "detalhes_pedidos",
  "compression": "zstd",
  "fail_on_item_error": false,
  "max_errors": 50
}

processa a lista de origem item a item, liberando memória a cada 5.000 linhas acumuladas, e tolera até 50 erros individuais antes de abortar a execução.

tratamento de erros¶

fail_on_item_error: false (padrão) — um erro em um item específico é registrado no log e a iteração continua para os demais itens
fail_on_item_error: true — qualquer erro interrompe o pipeline inteiro imediatamente
max_errors — funciona como um limite de tolerância: mesmo com fail_on_item_error: false, a iteração é abortada se o total de erros atingir esse número

reautenticação dentro do loop¶

quando a api chamada dentro do loop exige tokens de curta duração, coloque um nó auth rest no início do corpo do iterador. se o nó auth rest tiver expires_in_field ou token_expiry_field configurado, a reautenticação só é refeita quando o token realmente expira — não a cada iteração.

iterador vs. coletor¶

o iterador executa o loop; o coletor consolida resultados de múltiplos nós que rodaram dentro (ou em paralelo a) iterações — os dois costumam ser usados juntos em fluxos mais elaborados.

modo de amostra

ao testar o pipeline no builder, o iterador executa apenas uma iteração (mesmo que a fonte tenha milhares de linhas), o suficiente para validar a configuração do loop body sem rodar o processo inteiro.