Transformações e regras de qualidade

Objetivo e contrato dos registros

As transformações incorporadas trabalham sobre os registros recebidos de seus componentes anteriores. Uma operação pode alterar campos, valores, quantidade de linhas ou ordem. Antes de conectar um destino, defina quais propriedades precisam ser preservadas. Qualidade não significa apenas um Mapping válido: um grafo correto pode produzir um resultado de negócio incorreto se as chaves ou o tipo de junção não representarem a relação real.

O catálogo a seguir reúne os componentes das categorias Transform e Quality. Os identificadores reconhecem a configuração; os rótulos são os apresentados ao usuário. Os campos descrevem o contrato do componente, não funções de uma linguagem de programação aberta. Para fontes e destinos, consulte componentes de Mapping.

Catálogo completo

Projeção e enriquecimento

Field selector mantém a lista de campos escolhida. Field mapper relaciona nomes de origem e destino; use-o para estabelecer um esquema de saída reconhecido pelo consumidor. Verifique colisões antes de renomear: dois conceitos diferentes não devem acabar representados pelo mesmo nome lógico.

Calculated field cria um campo usando um modelo de texto. ${customer} obtém o valor de uma coluna e ${param.region} obtém um parâmetro. A substituição produz texto; não interpreta fórmulas aritméticas nem executa JavaScript ou SQL. Consulte expressões e variáveis para distinguir esse modelo de uma condição de Workflow.

Convert type oferece String, Integer, Number, Boolean, Date e Date and time. Output field vazio substitui o campo de origem; outro nome preserva o valor inicial. On conversion error permite falhar, definir nulo, manter o original ou usar um valor padrão. Manter originais pode deixar uma coluna heterogênea: valide a saída antes de gravar em uma tabela tipada.

Limpeza de texto

Clean text aplica uma lista ordenada de operações: trim, collapse_whitespace, lower, upper e remove_accents. Por padrão, remove espaços nas extremidades e reduz espaços repetidos. Aplique uma política coerente nos dois lados de uma chave de junção. Não remova acentos de um nome que precisa ser preservado legalmente apenas para facilitar uma comparação; crie um campo normalizado separado quando necessário.

Replace values distingue conteúdo, valor exato, prefixo e sufixo; Case sensitive controla maiúsculas e minúsculas. Split field divide por delimitador e atribui Output fields, com opções para manter a origem e remover espaços das partes. Concatenate fields define separador, campo de saída e tratamento de valores vazios. Esses componentes não são interpretadores de expressões regulares arbitrárias.

Quantidade, ordem e agrupamento

Row filter aceita Equals, Does not equal, Contains, Starts with, Ends with, comparações de maior ou menor com ou sem igualdade e Is not empty. A lista de operadores difere da usada nas decisões de Workflow. Converta números antes de compará-los quando a origem for texto e valide os limites com registros exatamente iguais ao valor de corte.

Limit rows combina Maximum rows e Rows to skip. É útil para uma janela controlada, mas uma amostra não valida toda a população. Row sort ordena por Field e Direction. Group aggregate agrupa por Group fields e calcula Count, Sum ou Average, com Value field e Output field conforme a operação. Medianas, percentis e várias métricas implícitas não fazem parte deste catálogo.

Deduplicate configura Match fields. Trata-se de uma regra de identidade: teste registros iguais na chave e diferentes em outros atributos. Confirme qual registro permanece antes de usar o componente na reconciliação; ele não implica uma política de “última atualização” que não foi modelada explicitamente.

Junções

Join declara Inner, Left, Right e Full, componentes esquerdo e direito, chaves e condições adicionais AND. Key type pode ser automático ou explícito. Strategy oferece Automatic hash, Hash e Sorted merge. Case sensitive, Trim strings e Match nulls alteram a equivalência das chaves. Right collision prefix, inicialmente right_, distingue nomes repetidos.

Verifique unicidade e cardinalidade antes da junção. Duas ocorrências à esquerda e três à direita podem multiplicar registros; isso não indica necessariamente uma falha do mecanismo. Prepare casos sem correspondência, com correspondência única, com duplicatas e com nulos. Um Left join preserva a intenção de manter os registros da esquerda, mas a quantidade exata depende das correspondências de cada chave.

Reestruturação, sequências, impressões digitais e classificação

Unpivot: de colunas para linhas

Unpivot transforma as colunas de fields em registros. Cada registro mantém keepFields, grava o nome da coluna em keyField e o valor em valueField. Se Keep fields estiver vazio, mantém os demais campos de entrada. Campos mantidos e colunas transformadas não podem se sobrepor; os nomes de saída precisam ser diferentes e não podem colidir com nenhum campo de entrada.

Por exemplo, a entrada {"region":"SUR","jan":10,"feb":null} com Value columns jan,feb, Keep fields region, Column name field month e Value field amount produz {"region":"SUR","month":"jan","amount":10} e {"region":"SUR","month":"feb","amount":null}. Drop null values elimina somente o segundo registro: zero, falso e texto vazio são mantidos. Confira o aumento esperado de linhas; a execução em memória deste operador rejeita uma saída com mais de 250000 registros.

Run sequence: numeração de uma execução

Run sequence adiciona um inteiro a cada registro conforme start + index × step, com o primeiro índice igual a zero. Start 100 e Step 10 atribuem 100, 110 e 120 a três linhas. Step não pode ser zero e o cálculo precisa permanecer no intervalo seguro de inteiros de ±9007199254740991. O campo de saída não pode colidir com um existente.

A sequência reinicia em cada execução. Ela não é um identificador global, uma sequência persistida no banco de dados nem uma garantia de unicidade entre tentativas. Se a ordem dá significado ao número, ordene os registros antes e documente o critério de desempate.

Field fingerprint: detectar mudanças em campos escolhidos

Field fingerprint calcula uma impressão digital SHA-256 a partir dos nomes e valores tipados de fields e a grava em outputField, inicialmente fingerprint. O cálculo usa JSON canônico com nomes ordenados e valores que mantêm seus tipos; nulo, texto vazio e a string "1" em comparação com o número 1 são diferentes. Use um campo de saída novo. A impressão digital compara versões dos atributos escolhidos; ela não criptografa nem anonimiza os dados.

Para comparar duas extrações de clientes, escolha os mesmos campos de negócio, normalize o texto antes do cálculo e relacione os registros por uma chave de cliente independente. Exclua horários de extração que mudam em cada execução quando não representam mudanças de negócio. Não use a impressão digital como substituta do controle de acesso nem como prova de autenticidade de um arquivo externo.

Partition rank: posições dentro de grupos

Partition rank classifica o campo numérico field dentro de cada grupo de partitionBy; uma lista vazia classifica toda a entrada. Direction é ascendente ou descendente. Para os valores 100,100,80 em ordem descendente, Dense rank produz 1,1,2; Rank with gaps produz 1,1,3; Row number produz 1,2,3. Os empates de Row number seguem a ordem de entrada.

O componente adiciona as posições preservando a ordem original das linhas; acrescente Row sort para apresentar a saída em ordem de classificação. Ele aceita números finitos e suas representações textuais válidas; rejeita nulos, vazios e booleanos. Exige classificação com armazenamento intermediário e não faz qualquer grafo usar memória constante. Teste partições diferentes, empates e um valor inválido antes de aceitar a saída.

Regras de qualidade

Default value preenche um campo nulo, vazio ou ambos, conforme Apply when. Quality check controla o percentual máximo de nulos. Required fields verifica o preenchimento de uma lista. Type check valida o tipo declarado e pode permitir vazios. Pattern check aplica um padrão. Range check define mínimo, máximo e inclusão dos limites. Allowed values restringe o domínio e permite distinguir maiúsculas de minúsculas.

Os percentuais são limites de aceitação; eles não definem uma saída automática de quarentena. Não apresente uma regra como separação de registros válidos e inválidos se o projeto não fizer isso. Use zero quando nenhuma violação for aceitável e teste o comportamento com uma linha inválida conhecida.

Prova de conceito de limpeza e controle

Prepare um CSV com id,name,amount: dois registros válidos e um terceiro com amount vazio. Conecte Flat File input → Clean text em name → Convert type em amount → Required fields em id e amount → Flat File output. Use trim e upper; configure Set null na conversão e Maximum invalid percent igual a zero na regra de qualidade.

A expectativa é uma falha de qualidade causada pelo terceiro registro; essa execução não deve ser considerada uma carga aceita. Corrija o dado sintético, repita e confira três registros, nomes normalizados e valores numéricos compatíveis com a saída. Se houver um destino remoto, use um recurso descartável e verifique efeitos parciais antes de tentar novamente.

Para ampliar o exercício, prepare outra fonte com duas chaves e uma descrição, adicione Join e confira o resultado esperado manualmente. Registre as quantidades antes e depois, as chaves sem correspondência e as duplicatas. É um teste de aceitação a executar no seu ambiente; ele não comprova a validação prévia de um destino real.