Referencia de componentes de Mapping

Cómo usar esta referencia

El catálogo contiene 36 componentes: 6 Sources, 17 Transform, 8 Quality y 5 Targets. Los nombres visibles se conservan como aparecen en Dova; los identificadores y las claves JSON no se traducen. Un componente disponible en el editor no demuestra que la conexión esté configurada o que cualquier worker pueda ejecutarlo.

La configuración propuesta en cada ejemplo es parcial y sintética. Completa los campos obligatorios del caso real, las conexiones autorizadas y los bindings del runtime antes de validar. Nunca escribas contraseñas dentro del Mapping.

Sources

Flat File input (source_csv)

Lee archivos CSV, TSV o TXT delimitados. La cabecera determina las columnas; headerMappings proyecta, renombra y convierte únicamente los campos mapeados. Sin cabecera, columns asigna nombres por posición.

Configuración: format, delimiter, hasHeader, headerRowNumber, columns, headerMappings, encoding.

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

Ejemplo sintético:

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

Límites: Usa un delimitador de un carácter y UTF-8. Con hasHeader=true, columns no selecciona campos. Configura la fila de cabecera antes de revisar los datos.

JSON input (source_json)

Lee objetos, listas JSON o JSON Lines como registros. recordPath localiza los registros; fieldMappings selecciona rutas de origen y nombres/tipos de salida. Sin mapeos conserva los campos superiores observados y serializa objetos o listas anidados como texto JSON.

Configuración: format, recordPath, fieldMappings, encoding.

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

Ejemplo sintético:

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

Límites: Las rutas son rutas con puntos, no expresiones JSONPath generales. Un campo mapeado no anulable que falta provoca un error.

Excel input (source_excel)

Lee hojas y rangos de un libro Excel. Selecciona hojas, cabecera y filas/columnas; headerMappings proyecta, renombra y convierte campos. includeSheetName puede añadir la hoja de procedencia.

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

Ejemplo sintético:

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

Límites: Los formatos de lectura son xlsx, xlsm y xls. Las hojas y los rangos deben existir. La contraseña del libro se entrega únicamente para la operación autorizada; no se guarda en la configuración del Mapping.

Database input (source_database)

Lee una tabla/vista o una consulta de solo lectura mediante un worker compatible. En modo table, selectedColumns proyecta campos y schema/objectName identifican la relación. En modo query, las columnas proceden de sqlQuery.

Configuración: connectionId, sourceMode, schema, objectType, objectName, sqlQuery, selectedColumns, fetchSize, queryTimeoutSeconds.

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

Ejemplo sintético:

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

Límites: selectedColumns no reescribe SQL arbitrario. El adaptador genérico de streaming admite tabla/vista; las consultas dependen del conector y del runtime. Seleccionar un tipo de conexión no configura sus credenciales.

API input (source_api)

Lee registros mediante GET con una conexión configurada. responsePath localiza los registros y fieldMappings proyecta rutas anidadas en campos lógicos tipados. La paginación puede ser none, page, offset o cursor.

Configuración: connectionId, method, resourcePath, responsePath, fieldMappings, paginationMode, pageSize, retries, timeoutSeconds.

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

Ejemplo sintético:

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

Límites: La compatibilidad real depende del proveedor. Los conectores SaaS usan sus recursos/entidades; no todos aceptan las mismas opciones del REST genérico.

Object storage input (source_object)

Lee CSV o JSONL de almacenamiento de objetos. resource identifica el objeto, selectedColumns proyecta campos y delimiter se aplica a CSV.

Configuración: connectionId, resource, format, selectedColumns, delimiter.

format: csv, jsonl.

Ejemplo sintético:

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

Límites: Requiere conexión y permisos de lectura compatibles y un esquema tabular estable. No presupone acceso al almacenamiento por mostrar el componente.

Transform

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.

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.

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

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.

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.

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.

Targets

Flat File output (target_csv)

Escribe filas como CSV o TXT usando las columnas de salida anteriores y su orden. Permite configurar cabecera, delimitador, comillas, nulos, codificación y saltos de línea.

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

Ejemplo sintético:

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

Límites: No tiene selector fields/columns. Usa Field selector antes del destino para eliminar campos. fileName define el nombre del archivo, no su proyección.

JSON output (target_json)

Escribe una lista JSON o JSON Lines usando únicamente las columnas de salida anteriores. includeNulls=false omite campos cuyo valor es nulo.

Configuración: format, fileName, pretty, includeNulls, lineEnding, encoding.

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

Ejemplo sintético:

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

Límites: No permite seleccionar campos arbitrarios: usa Field selector. pretty controla el formato de la lista JSON.

Database output (target_database)

Escribe campos anteriores en una tabla mediante un worker compatible. append añade filas; replace y upsert dependen de las capacidades del destino. keyColumns define claves para upsert.

Configuración: connectionId, schema, objectName, writeMode, batchSize, commitIntervalRows, keyColumns, createIfMissing, queryTimeoutSeconds.

writeMode: append, replace, upsert.

Ejemplo sintético:

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

Límites: replace puede sustituir datos existentes. No presupongas soporte universal de createIfMissing, modos de escritura ni tiempos de consulta. Verifica reintentos y claves antes de producción.

API output (target_api)

Envía registros mediante POST, PUT o PATCH. Admite append/upsert con códigos de éxito, lotes, reintentos y tiempo máximo cuando el runtime REST lo soporta.

Configuración: connectionId, method, resourcePath, writeMode, keyColumns, uniqueKeysEnforced, batchSize, successCodes, retries, timeoutSeconds.

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

Ejemplo sintético:

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

Límites: Upsert exige exactamente una clave. La idempotencia depende de la API. uniqueKeysEnforced describe la garantía del proveedor; no crea una restricción de unicidad.

Object storage output (target_object)

Escribe campos anteriores como CSV/JSONL en almacenamiento de objetos mediante sustitución condicional. Exige idempotencyKey y exactamente una precondición.

Configuración: connectionId, resource, format, writeMode, delimiter, idempotencyKey, ifAbsent, expectedEtag, expectedGeneration.

format: csv, jsonl; writeMode: replace.

Ejemplo sintético:

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

Límites: Usa ifAbsent, expectedEtag o expectedGeneration, nunca varias. Con ETag/generación configura ifAbsent=false. No hay modo append incondicional; verifica conexión y permisos.

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.