Transformaciones y controles de calidad

Elegir por el efecto esperado

Usa Row filter para quitar filas, Field selector para quitar columnas y Field mapper para renombrarlas. Para cambiar el valor exacto jorge a Jorge, usa Replace values con field=name, find=jorge, replacement=Jorge, matchMode=exact y caseSensitive=true. No preguntes por otra función cuando esa regla ya está definida.

Para limpiar nombres, usa Clean text con trim, capitalize o title, según el resultado esperado. capitalize convierte el primer carácter a mayúscula y el resto a minúsculas; title capitaliza cada palabra. Calculated field interpola texto: LEFT(name,1) no ejecuta una función.

Contrato de calidad

Quality incluye Default value y Deduplicate, que sí modifican datos. Las otras seis verificaciones son compuertas: Quality check, Required fields, Type check, Pattern check, Range check y Allowed values. Si el porcentaje inválido supera el umbral, falla toda la ejecución. Si no lo supera, pasan todas las filas, incluidas las inválidas. No crean una salida de rechazados. Con umbral cero, una sola fila inválida en una entrada no vacía provoca fallo.

Transformaciones y calidad

Row filter (filter)

Conserva las filas que cumplen una condición de un campo; mantiene todas sus columnas y valores.

Configuración: field, operator, value.

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

Ejemplo sintético:

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

Límites: equals y not_equals comparan texto distinguiendo mayúsculas. contains, starts_with y ends_with no las distinguen. Las comparaciones gt/gte/lt/lte convierten a número. not_empty excluye nulos y texto vacío.

Field selector (select)

Proyecta cada fila y el esquema de salida únicamente sobre los campos existentes indicados, en el orden configurado. Elimina los demás campos y mantiene el número de filas.

Configuración: fields.

Ejemplo sintético:

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

Límites: No transforma valores, renombra ni filtra filas. Debe existir al menos un campo seleccionado. Si aparecen otros campos al final, revisa la versión ejecutada, la rama conectada y los componentes posteriores.

Field mapper (rename)

Renombra los campos incluidos en mapping y conserva sus valores, los campos no mapeados y todas las filas.

Configuración: mapping.

Ejemplo sintético:

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

Límites: Los nombres de salida deben ser únicos. No reemplaza valores ni elimina los campos no mapeados; añade Field selector cuando necesites proyectar columnas.

Calculated field (derive)

Añade o reemplaza un campo con texto literal e interpolación ${field} o ${param.name}. Copia las demás columnas y filas.

Configuración: field, template.

Ejemplo sintético:

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

Límites: No ejecuta expresiones: no admite aritmética, LEFT, SUBSTR, cortes ni capitalización inicial. El resultado es texto limitado a 4.000 caracteres.

Convert type (convert)

Convierte un campo a string, integer, number, boolean, date o datetime. Con outputField vacío reemplaza el origen; con nombre conserva el origen y escribe el resultado en ese campo.

Configuración: field, targetType, outputField, onError, defaultValue.

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

Ejemplo sintético:

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

Límites: date exige YYYY-MM-DD; datetime usa ISO 8601. No hay formato de fecha personalizado. onError admite fail, null, keep o default; los números deben ser finitos.

Clean text (clean)

Aplica las operaciones, en el orden configurado, únicamente a fields. Conserva todas las filas y columnas; los campos no seleccionados mantienen sus valores y tipos, y los nulos siguen siendo nulos.

Configuración: fields, operations. En Operations escribe al menos una letra para ver las coincidencias disponibles y seleccionar una operación.

Para transformar jORGE en Jorge, configura:

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

El orden importa: trim elimina los espacios antes de capitalizar. Los valores seleccionados no nulos se convierten a texto; no uses capitalize si necesitas conservar las mayúsculas del resto del nombre.

Replace values (replace)

Reemplaza texto literal en un campo y conserva las demás columnas y todas las filas. Es la opción directa para cambiar exactamente jorge por Jorge.

Configuración: field, find, replacement, matchMode, caseSensitive.

matchMode: contains, exact, starts_with, ends_with.

Ejemplo sintético:

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

Límites: No usa expresiones regulares. matchMode admite exact, contains, starts_with, ends_with; caseSensitive controla mayúsculas. Ese reemplazo concreto no capitaliza cualquier nombre.

Split field (split)

Divide texto mediante un delimitador literal y escribe los fragmentos en outputFields. keepSource controla conservar el campo original; trimParts recorta espacios.

Configuración: field, delimiter, outputFields, keepSource, trimParts.

Ejemplo sintético:

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

Límites: No extrae caracteres por posición. Divide como máximo una vez menos que el número de salidas: el resto queda en la última. Los fragmentos ausentes son cadenas vacías.

Concatenate fields (concat)

Une valores como texto en outputField usando separator; conserva los campos originales y todas las filas.

Configuración: fields, outputField, separator, skipEmpty.

Ejemplo sintético:

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

Límites: No suma números. skipEmpty omite fragmentos vacíos o con espacios; los nulos se representan como texto vacío.

Join (join)

Combina exactamente dos entradas inmediatas por claves de igualdad. Admite inner, left, right, full; emite ambos esquemas y añade rightPrefix a colisiones del lado derecho.

Configuración: 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.

Ejemplo 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_"
}

Límites: Configura leftInputId, rightInputId y claves válidas. Las condiciones múltiples se combinan con AND. Coincidencias muchos-a-muchos multiplican filas. Los nulos no coinciden por defecto. Existen límites de expansión y estrategias auto, hash, sorted.

Default value (defaults)

Completa un campo cuando es nulo, vacío o ambos según when; conserva valores presentes, otras columnas y todas las filas. Puede crear un campo ausente.

Configuración: field, value, when.

when: null_or_empty, null, empty.

Ejemplo sintético:

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

Límites: Cero y false se conservan. No reemplaza valores literales no vacíos; usa Replace values para esa finalidad.

Limit rows (limit)

Conserva una ventana contigua de filas después de offset, manteniendo columnas y valores.

Configuración: count, offset.

Ejemplo sintético:

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

Límites: count: 1–250.000; offset: 0–250.000. No ordena: añade Row sort antes para obtener los primeros N según un campo.

Deduplicate (dedupe)

Conserva la primera fila de cada combinación de claves y todos sus campos. fields vacío compara todas las columnas de entrada.

Configuración: fields.

Ejemplo sintético:

{
  "fields": [
    "customer_id"
  ]
}

Límites: Elimina duplicados, pero no combina valores ni elige automáticamente el más reciente. Ordena antes si importa cuál será la primera fila. La comparación utiliza valores JSON tipados.

Row sort (sort)

Ordena filas por un campo en dirección asc o desc, conservando todas las columnas y filas.

Configuración: field, direction.

direction: asc, desc.

Ejemplo sintético:

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

Límites: Los valores convertibles a número se ordenan numéricamente; otros textos sin distinguir mayúsculas. No es ordenación por varias claves. En streaming requiere una etapa de preparación.

Group aggregate (aggregate)

Produce una fila por grupo de groupBy, únicamente con las claves del grupo y el campo de métrica. count cuenta filas; sum y avg agregan un campo.

Configuración: groupBy, metric, field, outputField.

metric: count, sum, avg.

Ejemplo sintético:

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

Límites: No calcula entre columnas de una misma fila ni ofrece min/max. sum/avg ignoran valores no convertibles a números finitos. El resultado de la métrica es texto. groupBy vacío agrupa toda la entrada no vacía.

Unpivot (unpivot)

Convierte cada columna de fields en una fila: keyField recibe el nombre original y valueField su valor. Conserva keepFields; si está vacío conserva los demás campos de entrada.

Configuración: fields, keepFields, keyField, valueField, dropNulls.

Ejemplo sintético:

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

Límites: Expande filas. Los nombres de salida no pueden sobrescribir columnas existentes. dropNulls elimina únicamente nulos: conserva cero, false y texto vacío. No realiza pivot.

Run sequence (sequence)

Añade una secuencia entera start + índice de fila × step, preservando filas, campos y orden.

Configuración: outputField, start, step.

Ejemplo sintético:

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

Límites: Se reinicia en cada ejecución: no es un identificador persistente ni globalmente único. step no puede ser cero y la salida no puede sobrescribir un campo existente. Se aplican límites de enteros seguros.

Field fingerprint (hash_fields)

Añade una huella hexadecimal SHA-256 sobre nombres de campos seleccionados y valores JSON tipados canónicos. Conserva los datos originales.

Configuración: fields, outputField.

Ejemplo sintético:

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

Límites: Nulo y texto vacío producen valores distintos. No cifra ni anonimiza. Los campos de entrada deben existir y la salida no puede sobrescribirlos; profundidad JSON máxima 20 y números finitos.

Partition rank (rank)

Añade una posición numérica por grupos partitionBy y conserva el orden original de las filas. dense comparte posiciones consecutivas; rank deja huecos; row_number asigna posiciones únicas.

Configuración: partitionBy, field, direction, mode, outputField.

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

Ejemplo sintético:

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

Límites: El campo ordenado debe ser número finito en cada fila; nulo, vacío y booleano fallan. No sobrescribe columnas existentes. partitionBy vacío trata toda la entrada como grupo. No ordena la salida final.

Quality check (validate)

Verifica el porcentaje de valores vacíos de un campo. Falla la ejecución si supera maxNullPercent; de lo contrario deja pasar todas las filas y campos sin cambios.

Configuración: field, maxNullPercent.

Ejemplo sintético:

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

Límites: Nulo y texto con solo espacios cuentan como vacíos; cero y false no. El umbral está entre 0 y 100. No completa ni elimina valores.

Required fields (quality_required)

Marca una fila inválida si cualquiera de los campos obligatorios es nulo o vacío. Si el porcentaje supera maxInvalidPercent, falla la ejecución.

Configuración: fields, maxInvalidPercent.

Ejemplo sintético:

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

Límites: Si pasa el umbral, conserva incluso las filas inválidas. No completa datos ni descarta registros.

Type check (quality_type)

Comprueba si los valores se pueden convertir a expectedType sin convertirlos. Conserva filas y valores cuando no supera el umbral.

Configuración: field, expectedType, allowEmpty, maxInvalidPercent.

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

Ejemplo sintético:

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

Límites: Para transformar usa Convert type. allowEmpty controla ausencias. Un texto numérico puede pasar y seguir siendo texto.

Pattern check (quality_pattern)

Comprueba coincidencia del campo completo con una expresión regular segura. Conserva los datos si no supera maxInvalidPercent.

Configuración: field, pattern, allowEmpty, maxInvalidPercent.

Ejemplo sintético:

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

Límites: Se aplican límites de seguridad a pattern. No extrae, reemplaza ni filtra valores. allowEmpty controla ausencias por separado.

Range check (quality_range)

Comprueba valores numéricos finitos frente a minimum y/o maximum, con límites inclusivos o exclusivos. Mantiene datos si pasa el umbral.

Configuración: field, minimum, maximum, inclusive, allowEmpty, maxInvalidPercent.

Ejemplo sintético:

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

Límites: Debe haber al menos un límite. No recorta ni reemplaza valores fuera de rango. allowEmpty controla ausencias.

Allowed values (quality_domain)

Comprueba pertenencia textual exacta a allowedValues, respetando caseSensitive. Conserva datos si pasa el umbral.

Configuración: field, allowedValues, caseSensitive, allowEmpty, maxInvalidPercent.

Ejemplo sintético:

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

Límites: La lista no puede estar vacía. No mapea ni reemplaza valores; usa Replace values para transformarlos. allowEmpty controla ausencias.

Compatibilidad de ejecución

El adaptador genérico de streaming exige una ruta lineal, con un origen y un destino compatibles. Join y los gráficos con varias entradas necesitan una ruta de ejecución que soporte ese grafo; no cambies el algoritmo para silenciar un error de compatibilidad. Row sort, Group aggregate, Partition rank y las verificaciones de calidad pueden preparar datos antes de emitir resultados. Streaming no significa memoria ilimitada ni salida inmediata para cada componente.

Comprobar el resultado

Valida el grafo, guarda y publica deliberadamente. Ejecuta una muestra sintética mediante el runtime autorizado y compara esquema, filas, orden y valores. Si el CSV contiene campos de más tras Field selector, comprueba su configuración guardada, la versión del Mapping usada por la Session y los componentes posteriores: el selector sí elimina campos del esquema y de las filas.