Transformações e verificações de qualidade

Escolher pelo efeito esperado

Use Row filter para remover linhas, Field selector para remover colunas e Field mapper para renomeá-las. Para trocar o valor exato jorge por Jorge, use Replace values com field=name, find=jorge, replacement=Jorge, matchMode=exact e caseSensitive=true. Nenhuma função adicional é necessária quando essa regra já está definida.

Para limpar nomes, use Clean text com trim, capitalize ou title, conforme o resultado esperado. capitalize coloca o primeiro caractere em maiúscula e o restante em minúsculas; title capitaliza cada palavra. Calculated field interpola texto: LEFT(name,1) não executa uma função.

Contrato de qualidade

Quality inclui Default value e Deduplicate, que modificam dados. As outras seis verificações são barreiras: Quality check, Required fields, Type check, Pattern check, Range check e Allowed values. Se a porcentagem inválida superar o limite, toda a execução falha. Caso contrário, todas as linhas passam, inclusive as inválidas. Não produzem saída de rejeitados. Com limite zero, uma linha inválida em entrada não vazia causa falha.

Transformações e qualidade

Row filter (filter)

Mantém as linhas que atendem à condição de um campo e preserva todas as suas colunas e valores.

Configuração: field, operator, value.

operator: equals, not_equals, contains, starts_with, ends_with, gt, gte, lt, lte, not_empty.

Exemplo sintético:

{
  "field": "status",
  "operator": "equals",
  "value": "active"
}

Limites: equals e not_equals comparam texto diferenciando maiúsculas. contains, starts_with e ends_with ignoram essa diferença. gt/gte/lt/lte convertem para número. not_empty exclui nulos e texto vazio.

Field selector (select)

Projeta cada linha e o esquema de saída somente nos campos existentes configurados, na ordem indicada. Remove os demais campos e mantém a quantidade de linhas.

Configuração: fields.

Exemplo sintético:

{
  "fields": [
    "First_name",
    "Last_name"
  ]
}

Limites: Não transforma valores, renomeia campos nem filtra linhas. Pelo menos um campo selecionado precisa existir. Campos extras exigem revisar a versão executada, o ramo conectado e os componentes seguintes.

Field mapper (rename)

Renomeia os campos de mapping e preserva seus valores, os campos não mapeados e todas as linhas.

Configuração: mapping.

Exemplo sintético:

{
  "mapping": {
    "old_name": "new_name"
  }
}

Limites: Os nomes de saída precisam ser únicos. Não substitui valores nem remove campos não mapeados; acrescente Field selector para projetar colunas.

Calculated field (derive)

Acrescenta ou substitui um campo usando texto literal e interpolação ${field} ou ${param.name}. Copia as demais colunas e linhas.

Configuração: field, template.

Exemplo sintético:

{
  "field": "label",
  "template": "ID-${id}"
}

Limites: Não executa expressões: não admite aritmética, LEFT, SUBSTR, cortes nem capitalização inicial. O resultado é texto limitado a 4.000 caracteres.

Convert type (convert)

Converte um campo para string, integer, number, boolean, date ou datetime. outputField vazio substitui a origem; um nome preserva a origem e grava o resultado nesse campo.

Configuração: field, targetType, outputField, onError, defaultValue.

targetType: string, integer, number, boolean, date, datetime; onError: fail, null, keep, default.

Exemplo sintético:

{
  "field": "amount",
  "targetType": "number",
  "outputField": "amount_number",
  "onError": "fail"
}

Limites: date exige YYYY-MM-DD; datetime usa ISO 8601. Não há formato de data personalizado. onError aceita fail, null, keep ou default; números precisam ser finitos.

Clean text (clean)

Aplica as operações na ordem configurada somente a fields. Preserva todas as linhas e colunas; campos não selecionados mantêm valores e tipos, e nulos continuam nulos.

Configuração: fields, operations. Digite pelo menos uma letra em Operations para ver as correspondências disponíveis e escolher uma operação.

Para transformar jORGE em Jorge, configure:

{
  "fields": ["first_name"],
  "operations": ["trim", "capitalize"]
}

A ordem importa: trim remove os espaços antes da capitalização. Valores selecionados não nulos viram texto; não use capitalize se precisar manter as maiúsculas do restante do nome.

Replace values (replace)

Substitui texto literal em um campo e preserva as demais colunas e todas as linhas. É a opção direta para trocar exatamente jorge por Jorge.

Configuração: field, find, replacement, matchMode, caseSensitive.

matchMode: contains, exact, starts_with, ends_with.

Exemplo sintético:

{
  "field": "name",
  "find": "jorge",
  "replacement": "Jorge",
  "matchMode": "exact",
  "caseSensitive": true
}

Limites: Não usa expressões regulares. matchMode aceita exact, contains, starts_with, ends_with; caseSensitive controla maiúsculas. Essa substituição específica não capitaliza qualquer nome.

Split field (split)

Divide texto por um delimitador literal em outputFields. keepSource controla manter o campo original; trimParts remove espaços das partes.

Configuração: field, delimiter, outputFields, keepSource, trimParts.

Exemplo sintético:

{
  "field": "full_name",
  "delimiter": " ",
  "outputFields": [
    "first_name",
    "last_name"
  ],
  "keepSource": true,
  "trimParts": true
}

Limites: Não extrai caracteres por posição. Divide no máximo uma vez menos que o número de saídas, deixando o restante no último campo. Partes ausentes viram strings vazias.

Concatenate fields (concat)

Une valores como texto em outputField usando separator; preserva os campos originais e todas as linhas.

Configuração: fields, outputField, separator, skipEmpty.

Exemplo sintético:

{
  "fields": [
    "first_name",
    "last_name"
  ],
  "outputField": "full_name",
  "separator": " ",
  "skipEmpty": true
}

Limites: Não soma números. skipEmpty ignora partes vazias ou com espaços; nulos viram texto vazio.

Join (join)

Combina exatamente duas entradas imediatas por chaves de igualdade. Admite inner, left, right, full; emite ambos os esquemas e usa rightPrefix nas colisões do lado direito.

Configuração: joinType, leftInputId, rightInputId, leftKey, rightKey, conditions, keyType, strategy, caseSensitive, trimStrings, nullsEqual, rightPrefix.

joinType: inner, left, right, full; keyType: auto, string, integer, number, boolean, date, datetime; strategy: auto, hash, sorted.

Exemplo sintético:

{
  "joinType": "left",
  "leftInputId": "customers",
  "rightInputId": "orders",
  "leftKey": "id",
  "rightKey": "customer_id",
  "keyType": "auto",
  "strategy": "auto",
  "caseSensitive": true,
  "trimStrings": true,
  "nullsEqual": false,
  "rightPrefix": "right_"
}

Limites: Configure leftInputId, rightInputId e chaves válidas. Condições múltiplas usam AND. Correspondências muitos-para-muitos multiplicam linhas. Nulos não coincidem por padrão. Há limites de expansão e estratégias auto, hash, sorted.

Default value (defaults)

Preenche um campo nulo, vazio ou ambos conforme when; preserva valores presentes, outras colunas e todas as linhas. Pode criar um campo ausente.

Configuração: field, value, when.

when: null_or_empty, null, empty.

Exemplo sintético:

{
  "field": "name",
  "value": "Unknown",
  "when": "null_or_empty"
}

Limites: Zero e false são preservados. Não substitui valores literais não vazios; use Replace values para isso.

Limit rows (limit)

Mantém uma janela contígua de linhas após offset, preservando colunas e valores.

Configuração: count, offset.

Exemplo sintético:

{
  "count": 10,
  "offset": 0
}

Limites: count: 1–250.000; offset: 0–250.000. Não ordena: acrescente Row sort antes para obter os primeiros N por um campo.

Deduplicate (dedupe)

Mantém a primeira linha de cada combinação de chaves com todos os campos. fields vazio compara todas as colunas de entrada.

Configuração: fields.

Exemplo sintético:

{
  "fields": [
    "customer_id"
  ]
}

Limites: Remove duplicatas, mas não combina valores nem escolhe automaticamente o registro mais recente. Ordene antes se a primeira linha importar. A comparação usa valores JSON tipados.

Row sort (sort)

Ordena linhas por um campo na direção asc ou desc, preservando todas as colunas e linhas.

Configuração: field, direction.

direction: asc, desc.

Exemplo sintético:

{
  "field": "amount",
  "direction": "desc"
}

Limites: Valores conversíveis para número são ordenados numericamente; outros textos ignoram maiúsculas. Não ordena por várias chaves. Em streaming exige uma etapa de preparação.

Group aggregate (aggregate)

Produz uma linha por grupo de groupBy, somente com os campos do grupo e a saída da métrica. count conta linhas; sum e avg agregam um campo.

Configuração: groupBy, metric, field, outputField.

metric: count, sum, avg.

Exemplo sintético:

{
  "groupBy": [
    "region"
  ],
  "metric": "sum",
  "field": "amount",
  "outputField": "total"
}

Limites: Não calcula entre colunas da mesma linha e não oferece min/max. sum/avg ignoram valores não conversíveis para números finitos. A métrica resulta em texto. groupBy vazio agrupa toda entrada não vazia.

Unpivot (unpivot)

Transforma cada coluna de fields em uma linha: keyField recebe o nome original e valueField, o valor. Preserva keepFields; vazio mantém os demais campos de entrada.

Configuração: fields, keepFields, keyField, valueField, dropNulls.

Exemplo sintético:

{
  "fields": [
    "jan",
    "feb"
  ],
  "keepFields": [
    "id"
  ],
  "keyField": "month",
  "valueField": "amount",
  "dropNulls": false
}

Limites: Expande linhas. Nomes de saída não podem sobrescrever colunas existentes. dropNulls remove apenas nulos: mantém zero, false e texto vazio. Não realiza pivot.

Run sequence (sequence)

Acrescenta uma sequência inteira start + índice da linha × step, preservando linhas, campos e ordem.

Configuração: outputField, start, step.

Exemplo sintético:

{
  "outputField": "sequence",
  "start": 1,
  "step": 1
}

Limites: Reinicia a cada execução: não é identidade persistente nem globalmente única. step não pode ser zero e a saída não pode sobrescrever um campo existente. Aplicam-se limites de inteiros seguros.

Field fingerprint (hash_fields)

Acrescenta uma impressão digital hexadecimal SHA-256 sobre nomes de campos selecionados e valores JSON tipados canônicos. Preserva os dados originais.

Configuração: fields, outputField.

Exemplo sintético:

{
  "fields": [
    "id",
    "name"
  ],
  "outputField": "fingerprint"
}

Limites: Nulo e texto vazio são distintos. Não cifra nem anonimiza. Os campos de entrada precisam existir e a saída não pode sobrescrevê-los; profundidade JSON máxima 20 e números finitos.

Partition rank (rank)

Acrescenta uma posição numérica nos grupos partitionBy e mantém a ordem original das linhas. dense compartilha posições consecutivas; rank deixa lacunas; row_number atribui posições únicas.

Configuração: partitionBy, field, direction, mode, outputField.

direction: asc, desc; mode: dense, rank, row_number.

Exemplo sintético:

{
  "partitionBy": [
    "region"
  ],
  "field": "amount",
  "direction": "desc",
  "mode": "dense",
  "outputField": "rank"
}

Limites: O campo ordenado precisa ser número finito em cada linha; nulo, vazio e booleano falham. Não sobrescreve colunas existentes. partitionBy vazio trata toda a entrada como um grupo. Não ordena a saída final.

Quality check (validate)

Verifica a porcentagem de valores vazios em um campo. Falha a execução se superar maxNullPercent; caso contrário, mantém todas as linhas e campos sem alterações.

Configuração: field, maxNullPercent.

Exemplo sintético:

{
  "field": "name",
  "maxNullPercent": 0
}

Limites: Nulo e texto com apenas espaços contam como vazios; zero e false não. O limite vai de 0 a 100. Não preenche nem remove valores.

Required fields (quality_required)

Marca uma linha como inválida quando qualquer campo obrigatório é nulo ou vazio. A execução falha se a porcentagem superar maxInvalidPercent.

Configuração: fields, maxInvalidPercent.

Exemplo sintético:

{
  "fields": [
    "id",
    "name"
  ],
  "maxInvalidPercent": 0
}

Limites: Se passar pelo limite, até as linhas inválidas permanecem. Não preenche dados nem descarta registros.

Type check (quality_type)

Verifica se os valores podem ser convertidos para expectedType sem convertê-los. Preserva linhas e valores quando o limite não é excedido.

Configuração: field, expectedType, allowEmpty, maxInvalidPercent.

expectedType: string, integer, number, boolean, date, datetime.

Exemplo sintético:

{
  "field": "amount",
  "expectedType": "number",
  "allowEmpty": false,
  "maxInvalidPercent": 0
}

Limites: Use Convert type para transformar. allowEmpty controla valores ausentes. Texto numérico pode passar e continuar sendo texto.

Pattern check (quality_pattern)

Verifica a correspondência do campo inteiro com uma expressão regular segura. Preserva os dados quando maxInvalidPercent não é excedido.

Configuração: field, pattern, allowEmpty, maxInvalidPercent.

Exemplo sintético:

{
  "field": "code",
  "pattern": "[A-Z]{3}",
  "allowEmpty": false,
  "maxInvalidPercent": 0
}

Limites: Aplicam-se limites de segurança a pattern. Não extrai, substitui nem filtra valores. allowEmpty controla ausências separadamente.

Range check (quality_range)

Verifica números finitos contra minimum e/ou maximum, com limites inclusivos ou exclusivos. Mantém os dados se passar pelo limite.

Configuração: field, minimum, maximum, inclusive, allowEmpty, maxInvalidPercent.

Exemplo sintético:

{
  "field": "age",
  "minimum": "18",
  "maximum": "100",
  "inclusive": true,
  "allowEmpty": false,
  "maxInvalidPercent": 0
}

Limites: Pelo menos um limite é obrigatório. Não ajusta nem substitui valores fora do intervalo. allowEmpty controla ausências.

Allowed values (quality_domain)

Verifica pertencimento textual exato a allowedValues, respeitando caseSensitive. Preserva os dados se passar pelo limite.

Configuração: field, allowedValues, caseSensitive, allowEmpty, maxInvalidPercent.

Exemplo sintético:

{
  "field": "status",
  "allowedValues": [
    "active",
    "inactive"
  ],
  "caseSensitive": true,
  "allowEmpty": false,
  "maxInvalidPercent": 0
}

Limites: A lista não pode ser vazia. Não mapeia nem substitui valores; use Replace values para transformá-los. allowEmpty controla ausências.

Compatibilidade de execução

O adaptador genérico de streaming exige um caminho linear, com origem e destino compatíveis. Join e grafos com várias entradas precisam de uma rota de execução que suporte essa topologia; não altere o algoritmo apenas para ocultar um erro de compatibilidade. Row sort, Group aggregate, Partition rank e verificações de qualidade podem preparar dados antes de emitir resultados. Streaming não significa memória ilimitada nem saída imediata em todo componente.

Conferir o resultado

Valide o grafo, salve e publique deliberadamente. Execute uma amostra sintética no runtime autorizado e compare esquema, linhas, ordem e valores. Se o CSV tiver campos extras após Field selector, confira a configuração salva, a versão do Mapping usada pela Session e os componentes seguintes: o seletor remove campos do esquema e das linhas.