Referência dos componentes de Mapping

Como usar esta referência

O catálogo contém 36 componentes: 6 Sources, 17 Transform, 8 Quality e 5 Targets. Os nomes visíveis correspondem ao Dova; identificadores e chaves JSON não são traduzidos. Um componente disponível no editor não comprova que a conexão esteja configurada ou que qualquer worker possa executá-lo.

Cada exemplo é uma configuração parcial e sintética. Complete os campos obrigatórios do caso, as conexões autorizadas e os bindings do runtime antes de validar. Nunca coloque senhas dentro do Mapping.

Sources

Flat File input (source_csv)

Lê arquivos CSV, TSV ou TXT delimitados. O cabeçalho determina as colunas; headerMappings projeta, renomeia e converte apenas os campos mapeados. Sem cabeçalho, columns atribui nomes por posição.

Configuração: format, delimiter, hasHeader, headerRowNumber, columns, headerMappings, encoding.

format: csv, tsv, txt; encoding: utf-8, utf-8-bom.

Exemplo sintético:

{
  "format": "csv",
  "hasHeader": true,
  "delimiter": ","
}

Limites: Use um delimitador de um caractere e UTF-8. Com hasHeader=true, columns não seleciona campos. Configure a linha de cabeçalho antes de conferir os dados.

JSON input (source_json)

Lê objetos, listas JSON ou JSON Lines como registros. recordPath localiza os registros; fieldMappings seleciona caminhos de origem e nomes/tipos de saída. Sem mapeamentos preserva os campos superiores observados e serializa objetos ou listas aninhados como texto JSON.

Configuração: format, recordPath, fieldMappings, encoding.

format: json, jsonl; encoding: utf-8, utf-8-bom.

Exemplo sintético:

{
  "format": "json",
  "recordPath": "items"
}

Limites: Os caminhos usam pontos, não expressões JSONPath gerais. A ausência de um campo mapeado não anulável causa erro.

Excel input (source_excel)

Lê planilhas e intervalos de uma pasta Excel. Selecione planilhas, cabeçalho e limites de linhas/colunas; headerMappings projeta, renomeia e converte campos. includeSheetName pode acrescentar a planilha de origem.

Configuração: workbookFormat, sheetMode, sheetName, sheetNames, sheetPattern, sheetNameRegex, includeHiddenSheets, hasHeader, headerRowNumber, dataStartRowNumber, startColumn, endColumn, columns, headerMappings, skipEmptyRows, includeSheetName, sheetNameField, passwordProtected.

workbookFormat: auto, xlsx, xlsm, xls; sheetMode: single, list, pattern, regex, all.

Exemplo sintético:

{
  "sheetMode": "single",
  "sheetName": "Sheet1",
  "hasHeader": true,
  "headerRowNumber": 1,
  "dataStartRowNumber": 2
}

Limites: Os formatos de leitura são xlsx, xlsm e xls. As planilhas e os intervalos precisam existir. A senha é fornecida somente para a operação autorizada; não a armazene na configuração do Mapping.

Database input (source_database)

Lê uma tabela/view ou uma consulta somente leitura por um worker compatível. No modo table, selectedColumns projeta campos e schema/objectName identificam a relação. No modo query, as colunas vêm de sqlQuery.

Configuração: connectionId, sourceMode, schema, objectType, objectName, sqlQuery, selectedColumns, fetchSize, queryTimeoutSeconds.

sourceMode: table, query; objectType: table, view.

Exemplo sintético:

{
  "sourceMode": "table",
  "objectName": "customers",
  "selectedColumns": [
    "name",
    "amount"
  ]
}

Limites: selectedColumns não reescreve SQL arbitrário. O adaptador genérico de streaming admite tabela/view; consultas dependem do conector e do runtime. Selecionar o tipo de conexão não configura credenciais.

API input (source_api)

Lê registros com GET usando uma conexão configurada. responsePath localiza registros e fieldMappings projeta caminhos aninhados em campos lógicos tipados. A paginação pode ser none, page, offset ou cursor.

Configuração: connectionId, method, resourcePath, responsePath, fieldMappings, paginationMode, pageSize, retries, timeoutSeconds.

method: GET; paginationMode: none, page, offset, cursor.

Exemplo sintético:

{
  "method": "GET",
  "resourcePath": "/customers",
  "paginationMode": "none"
}

Limites: O suporte efetivo depende do provedor. Conectores SaaS usam seus próprios recursos/entidades; nem todos aceitam as mesmas opções do REST genérico.

Object storage input (source_object)

Lê CSV ou JSONL de armazenamento de objetos. resource identifica o objeto, selectedColumns projeta campos e delimiter se aplica a CSV.

Configuração: connectionId, resource, format, selectedColumns, delimiter.

format: csv, jsonl.

Exemplo sintético:

{
  "resource": "input/customers.csv",
  "format": "csv",
  "selectedColumns": [
    "name",
    "amount"
  ],
  "delimiter": ","
}

Limites: Exige conexão compatível, permissão de leitura e esquema tabular estável. A presença do componente não comprova acesso ao armazenamento.

Transform

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.

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.

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

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.

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.

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.

Targets

Flat File output (target_csv)

Grava linhas como CSV ou TXT usando as colunas anteriores e sua ordem. Permite configurar cabeçalho, delimitador, aspas, nulos, codificação e quebras de linha.

Configuração: format, fileName, delimiter, includeHeader, textQualifier, quoteMode, escapeCharacter, lineEnding, encoding, nullValue.

format: csv, txt; textQualifier: double, single, none; quoteMode: minimal, all; lineEnding: lf, crlf; encoding: utf-8, utf-8-bom.

Exemplo sintético:

{
  "fileName": "output.csv",
  "format": "csv",
  "delimiter": ",",
  "includeHeader": true
}

Limites: Não possui seletor fields/columns. Use Field selector antes do destino para remover campos. fileName define o nome do arquivo, não a projeção.

JSON output (target_json)

Grava uma lista JSON ou JSON Lines usando apenas as colunas de saída anteriores. includeNulls=false omite campos com valor nulo.

Configuração: format, fileName, pretty, includeNulls, lineEnding, encoding.

format: json, jsonl; lineEnding: lf, crlf; encoding: utf-8, utf-8-bom.

Exemplo sintético:

{
  "fileName": "output.jsonl",
  "format": "jsonl",
  "includeNulls": true
}

Limites: Não seleciona campos arbitrários: use Field selector. pretty controla a formatação da lista JSON.

Database output (target_database)

Grava os campos anteriores em uma tabela por um worker compatível. append acrescenta linhas; replace e upsert dependem das capacidades do destino. keyColumns define chaves de upsert.

Configuração: connectionId, schema, objectName, writeMode, batchSize, commitIntervalRows, keyColumns, createIfMissing, queryTimeoutSeconds.

writeMode: append, replace, upsert.

Exemplo sintético:

{
  "objectName": "customers",
  "writeMode": "append",
  "batchSize": 5000
}

Limites: replace pode substituir dados existentes. Não presuma suporte universal a createIfMissing, modos de escrita ou tempos de consulta. Verifique tentativas e chaves antes de produção.

API output (target_api)

Envia registros por POST, PUT ou PATCH. Admite append/upsert com códigos de sucesso, lotes, tentativas e tempo limite quando suportados pelo runtime REST.

Configuração: connectionId, method, resourcePath, writeMode, keyColumns, uniqueKeysEnforced, batchSize, successCodes, retries, timeoutSeconds.

method: POST, PUT, PATCH; writeMode: append, upsert.

Exemplo sintético:

{
  "method": "POST",
  "resourcePath": "/customers",
  "writeMode": "append",
  "batchSize": 100
}

Limites: Upsert exige exatamente uma chave. A idempotência depende da API. uniqueKeysEnforced descreve a garantia do provedor; não cria restrição de unicidade.

Object storage output (target_object)

Grava os campos anteriores como CSV/JSONL em armazenamento de objetos por substituição condicional. Exige idempotencyKey e exatamente uma precondição.

Configuração: connectionId, resource, format, writeMode, delimiter, idempotencyKey, ifAbsent, expectedEtag, expectedGeneration.

format: csv, jsonl; writeMode: replace.

Exemplo sintético:

{
  "resource": "output/customers.csv",
  "format": "csv",
  "writeMode": "replace",
  "idempotencyKey": "example-run",
  "ifAbsent": true
}

Limites: Use ifAbsent, expectedEtag ou expectedGeneration, nunca várias. Com ETag/geração configure ifAbsent=false. Não há append incondicional; verifique conexão e permissões.

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.