Transformações

Tipo

Referência

Para

Engenharia de dados, Desenvolvedor

Na tela

HorusETL › Dataflows › editor do Dataflow

Um nó de transformação recebe as linhas de um ou mais nós e devolve outras linhas. Os do grupo Transformações e Inteligência Artificial da biblioteca são estes:

Na biblioteca	kind no YAML	Entradas	Para quê
Join	Join	2	Trazer colunas de um lado para o outro por chave. Referência
Concatenar	Union	2	Empilhar as linhas de duas entradas. Referência
SQL (DuckDB)	SQLProcessor	1 ou mais	Transformar com SQL. Referência
Python (Pandas)	PythonProcessor	0 ou mais	Transformar com pandas. Referência
Map C#	Map	0 ou mais	Transformar com código C#. Referência
Classificar com IA	AIExtract	1	Preencher colunas novas com um modelo de IA. Referência

Para filtrar, calcular, agrupar e juntar, prefira o SQL (DuckDB): ele faz tudo isso e é mais fácil de ler depois.

Join

O Join devolve todas as colunas da entrada primária mais as colunas escolhidas da secundária, casando as linhas pelas chaves. A primária é a primeira entrada ligada ao nó; no YAML, inputs[0].

Na tela	No YAML (options)	Tipo	Padrão	Regra
Tipo de Join	TipoJoin	texto	Left na tela; INNER se a chave faltar no YAML	Left (LEFT): mantém todas as linhas da primária. Inner (INNER): mantém só as que casaram dos dois lados. O Agente ETL só reconhece LEFT em maiúsculas: qualquer outro valor, inclusive left, vira INNER
Chaves, Coluna primária	ChavesPrimario	lista de colunas	nenhuma	Obrigatória. Uma ou mais colunas
Chaves, Coluna secundária	ChavesSecundario	lista de colunas	nenhuma	Obrigatória. Mesma quantidade e mesma ordem de ChavesPrimario
Colunas do resultado	ColunasATrazer	lista de colunas	todas da secundária	As colunas da secundária que entram na saída. A tela já tira as que são chave

• As chaves são comparadas como texto. Um 1 número de um lado e um "1" texto do outro não casam, porque o número vira 1.0. Deixe as chaves com o mesmo tipo dos dois lados.
• Não há limite de colunas na chave.
• Com Left, as colunas da secundária ficam vazias nas linhas que não casaram.
• Se a secundária tiver mais de uma linha para a mesma chave, a linha da primária se repete uma vez para cada. Para trazer um valor só, agrupe a secundária antes num SQL (DuckDB).
• Coluna com o mesmo nome nos dois lados fica duas vezes, e a tela avisa. Renomeie uma delas no nó de origem.

- internalId: join_itens
  kind: Join
  inputs: [ext_itens, ext_pedidos]   # o primeiro é o primário
  options:
    TipoJoin: LEFT
    ChavesPrimario: [PEDIDO_ID]
    ChavesSecundario: [PEDIDO_ID]
    ColunasATrazer: [CLIENTE_ID, DATA_EMISSAO]

O nó precisa das duas entradas executadas para mostrar as colunas: "Execute os dois nós de entrada antes de executar o join."

Concatenar

O Concatenar empilha as linhas da segunda entrada embaixo das da primeira. Não tem campo para configurar, e no YAML options fica vazio.

• As colunas casam pelo nome.
• Coluna que só existe numa entrada fica na saída. Nas linhas da outra entrada, ela vem com 0 se for de número e vazia nos outros tipos. Some uma coluna de número que só existe de um lado e o 0 entra na conta.
• A ordem das colunas é a da primeira entrada, seguida das que só a segunda tem.
• A mesma coluna com tipos diferentes nas duas entradas (número de um lado, texto do outro) não tem resultado garantido. Converta antes para o mesmo tipo.
• São exatamente duas entradas. Para empilhar três, encadeie dois nós Concatenar.

Para saber de que entrada veio cada linha, crie antes uma coluna fixa em cada lado (SELECT *, '2025' AS ORIGEM FROM input_0, num SQL (DuckDB)).

Map C#

O Map roda um trecho de C# que recebe as entradas e devolve uma lista de linhas. Use quando a lógica não cabe em SQL nem em Python.

Na tela	No YAML (options)	Tipo	Regra
editor de código	Sourcecode	texto	O corpo do método Run. Precisa terminar com return de um DataList

O código vira o corpo deste método:

public DataList Run(DataList input, ETLLogger logger, DataList input0, DataList input1 /* uma por entrada */)
{
    // seu código
}

Nome	O que é
input	A primeira entrada (o mesmo que input0)
input0, input1...	Uma por entrada, na ordem em que foram ligadas
logger	logger.Log("texto") escreve no log da execução
DataList	Uma tabela. Dá para percorrer com foreach; GetSchema() devolve as colunas
DataRow	Uma linha. linha["COLUNA"] lê e grava; o nome não diferencia maiúscula de minúscula
DataSchema.Create("...")	Monta colunas novas, uma por linha no formato NOME TIPO, com tipo NUMBER, STRING ou DATE
Helpers.ToDouble(valor), Helpers.ToDate(valor)	Convertem um valor para número ou data, devolvendo nulo quando não dá

As variáveis do Dataflow chegam como variáveis C# declaradas antes do seu código, com o mesmo nome: número como número, data como DateTime, texto como object com o texto dentro. Variável com nome inválido em C# fica de fora. O {NOME} não é trocado dentro do código.

var schema = DataSchema.Create(@"
    PEDIDO_ID NUMBER
    CLIENTE STRING
    PROCESSADO_EM DATE
");

IEnumerable<DataRow> Linhas()
{
    foreach (var linha in input)
    {
        var nova = new DataRow(schema);
        nova["PEDIDO_ID"] = Helpers.ToDouble(linha["PEDIDO_ID"]);
        nova["CLIENTE"] = linha["NOME_CLIENTE"]?.ToString().ToUpper();
        nova["PROCESSADO_EM"] = DateTime.Now;
        yield return nova;
    }
}

return new DataList(Linhas(), schema);

Com yield return, as linhas passam uma de cada vez e não ficam todas na memória. Um erro de compilação ou de execução falha o nó com a mensagem do C#. Se o código não devolver um DataList, o nó falha com "O código não retornou um dataList válido."

Relacionado

• Índice dos nós
• SQL (DuckDB)
• Python

Pelo Lumo CLI

O nó também pode ser escrito e versionado em YAML. Veja a referência de flow.