Operadores personalizados

Fracttal ETL extiende los operadores estándar de JSON Logic con operadores propios disponibles en el bloque transform de cualquier configuración ETL.

Renombrado y cast

`rename`

Mapea campos de origen a destino, renombrándolos y opcionalmente casteando su tipo.

Firma: ["rename", [logic, "nuevo_nombre", "tipo?"], ...]

Cada elemento del array es una tupla de 2 o 3 elementos: la lógica para obtener el valor, el nombre del campo de salida y el tipo de cast opcional.

{
  "rename": [
    [{"var": "firstName"}, "nombre", "string"],
    [{"var": "age"}, "edad", "integer"],
    [{"var": "price"}, "precio", "number"],
    [{"var": "active"}, "activo", "boolean"],
    [{"var": "tags"}, "etiquetas", "array"]
  ]
}

Ver Tipos de datos para la referencia completa de tipos de cast.

Texto

`trim`

Elimina caracteres de los extremos de un string.

Firma: ["trim", logic, "caracteres", "mode"]

Parámetro	Tipo	Por defecto	Descripción
`logic`	JSON Logic	—	Expresión para obtener el string
`caracteres`	string	—	Caracteres a eliminar
`mode`	string	`"all"`	`"all"`, `"left"` o `"right"`

{"trim": [{"var": "name"}, " ", "all"]}

{"trim": [{"var": "code"}, "0", "left"]}

`split`

Divide un string por un separador y retorna el elemento en el índice indicado.

Firma: ["split", logic, "separador", indice]

{"split": [{"var": "full_name"}, " ", 0]}

{"split": [{"var": "email"}, "@", 1]}

`join`

Une los elementos de un array en un string usando un separador.

Firma: ["join", logic, "separador"]

{"join": [{"var": "tags"}, ", "]}

`substring`

Extrae una porción de un string por índice de inicio y fin.

Firma: ["substring", logic, inicio, fin]

Índices con base 0. Si fin es 0, extrae hasta el final.

{"substring": [{"var": "code"}, 0, 4]}

{"substring": [{"var": "description"}, 10, 0]}

`case`

Convierte un string a mayúsculas o minúsculas.

Firma: ["case", logic, "upper"|"lower"]

{"case": [{"var": "country"}, "upper"]}

`replace`

Reemplaza todas las ocurrencias de un substring en el string.

Firma: ["replace", logic, "original", "reemplazo"]

{"replace": [{"var": "phone"}, "-", ""]}

{"replace": [{"var": "text"}, " ", "_"]}

`switch`

Mapea un valor a otro usando pares valor,resultado separados por coma. El último elemento sin par es el valor por defecto.

Firma: ["switch", logic, "v1,r1,v2,r2,...,default"]

{"switch": [{"var": "status"}, "A,Activo,I,Inactivo,P,Pendiente,Desconocido"]}

Con un solo par y sin default:

{"switch": [{"var": "type"}, "premium,true,"]}

`replace_if_condition`

Reemplaza el valor únicamente si coincide con un valor de comparación; de lo contrario, retorna el valor original.

Firma: ["replace_if_condition", logic, "valor_comparar", "valor_reemplazo"]

{"replace_if_condition": [{"var": "status"}, "None", "Pendiente"]}

{"replace_if_condition": [{"var": "category"}, "null", "Sin categoría"]}

`string_to_array`

Divide un string en un array usando el separador indicado.

Firma: ["string_to_array", logic, "separador"]

{"string_to_array": [{"var": "tags"}, ","]}

`startsWith`

Retorna true si el string comienza con el prefijo dado.

Firma: ["startsWith", logic, "prefijo"]

{"startsWith": [{"var": "code"}, "FTL-"]}

`endsWith`

Retorna true si el string termina con el sufijo dado.

Firma: ["endsWith", logic, "sufijo"]

{"endsWith": [{"var": "filename"}, ".pdf"]}

Números

`round`

Redondea un número al número de decimales indicado. Sin decimales redondea al entero más cercano.

Firma: ["round", logic, decimales?]

{"round": [{"var": "price"}, 2]}

{"round": [{"var": "total"}, 0]}

`format_number`

Formatea un número usando plantillas de formato Python ({:,}, {:.2f}, etc.).

Firma: ["format_number", logic, "formato_entero", "formato_decimal?"]

{"format_number": [{"var": "amount"}, "{:,}"]}

Con decimales:

{"format_number": [{"var": "amount"}, "{:,}", "{:.2f}"]}

Fechas

`format_date`

Convierte fechas entre formatos, aplica zonas horarias o genera la fecha/hora actual.

Firma: ["format_date", logic_o_"now", "formato_entrada", "formato_salida", "timezone?"]

Formato de salida especial	Descripción
`"timestamp"`	Unix timestamp como string
`"microsoft_json_date"`	Formato `/Date(milisegundos)/`

Conversión de formato:

{"format_date": [{"var": "created_at"}, "%Y-%m-%d", "%d/%m/%Y"]}

Con zona horaria:

{"format_date": [{"var": "date"}, "%Y-%m-%dT%H:%M:%S", "%d/%m/%Y %H:%M", "America/Santiago"]}

Fecha y hora actual:

{"format_date": ["now", "", "%Y-%m-%dT%H:%M:%S", "Europe/Madrid"]}

A timestamp:

{"format_date": [{"var": "date"}, "%Y-%m-%d", "timestamp"]}

`add_timedelta`

Suma un intervalo de tiempo a una fecha en formato ISO 8601 (%Y-%m-%dT%H:%M:%S.%f%z).

Firma: ["add_timedelta", "fecha_iso", numero, "tipo"]

`tipo`	Descripción
`"hour"` (defecto)	Horas
`"day"`	Días (equivale a 24 horas)
`"second"`	Segundos

{"add_timedelta": ["2024-01-15T00:00:00.000+0000", 24, "hour"]}

{"add_timedelta": ["2024-01-15T00:00:00.000+0000", 7, "day"]}

`substract_timedelta`

Resta un intervalo de tiempo a una fecha en formato ISO 8601.

Firma: ["substract_timedelta", "fecha_iso", numero, "tipo"]

{"substract_timedelta": ["2024-01-15T00:00:00.000+0000", 1, "day"]}

`substract_datetime`

Calcula la diferencia entre dos fechas y la retorna en segundos.

Firma: ["substract_datetime", logic, "fecha_referencia_o_now", "formato"]

Usando "now" como referencia (fecha actual en UTC):

{"substract_datetime": [{"var": "start_date"}, "now", "%Y-%m-%dT%H:%M:%S%z"]}

Entre dos fechas concretas:

{"substract_datetime": [{"var": "end_date"}, "2024-01-01T00:00:00+0000", "%Y-%m-%dT%H:%M:%S%z"]}

Booleanos

`set_boolean`

Convierte un valor a true/false/null comparándolo con valores de referencia.

Firma: ["set_boolean", logic, "valor_true", "valor_false?"]

Caso	Comportamiento
Sin `valor_false`	`true` si coincide con `valor_true`, `false` en cualquier otro caso
Con `valor_false`	`true`, `false` o `null` si no coincide con ninguno

{"set_boolean": [{"var": "status"}, "active"]}

Con valor false explícito:

{"set_boolean": [{"var": "flag"}, "SI", "NO"]}

Arrays

`in`

Retorna true si un valor está contenido en el resultado de la lógica.

Firma: ["in", "valor", logic]

{"in": ["admin", {"var": "roles"}]}

`flatmap`

Aplana un array de objetos añadiendo campos del contexto padre a cada elemento.

Firma: ["flatmap", logic_array, context_fields?]

context_fields es una lista de especificaciones de campos del objeto padre a inyectar en cada item:

{
  "flatmap": [
    {"var": "items"},
    [
      {"field": {"var": "order_id"}, "as": "order_id"},
      {"field": {"var": "customer_name"}, "as": "customer"}
    ]
  ]
}

Sin campos de contexto (solo aplana el array):

{"flatmap": [{"var": "lines"}]}

Ejemplo completo

Transformación de un pedido: renombrado, formato de fecha, cálculo de diferencia y cast de tipo.

{
  "merge": [
    {
      "rename": [
        [{"var": "orderId"}, "id_pedido", "string"],
        [{"var": "totalAmount"}, "total", "number"],
        [{"var": "customerName"}, "cliente", "string"]
      ]
    },
    {
      "fecha_creacion": {
        "format_date": [{"var": "createdAt"}, "%Y-%m-%dT%H:%M:%S", "%d/%m/%Y", "America/Bogota"]
      }
    },
    {
      "estado": {
        "switch": [{"var": "status"}, "pending,Pendiente,confirmed,Confirmado,cancelled,Cancelado,Desconocido"]
      }
    },
    {
      "nombre_cliente": {
        "trim": [{"var": "customerName"}, " ", "all"]
      }
    }
  ]
}

Operadores personalizados

Renombrado y cast

rename

Texto

trim

split

join

substring

case

replace

switch

replace_if_condition

string_to_array

startsWith

endsWith