Saltar a contenido

Custom Operators

Los operadores personalizados de Fracttal ETL permiten extender las capacidades de transformación más allá de los operadores JSON Logic estándar. Estos operadores están diseñados específicamente para casos de uso comunes en integraciones empresariales.

Operadores de Transformación de Datos

rename

Renombra campos y cambia su tipo de dato.

{
  "transform": {
    "rename": [
      [{"var": "old_field"}, "new_field", "string"],
      [{"var": "birth_date"}, "fecha_nacimiento", "date"],
      [{"var": "price"}, "precio", "number"]
    ]
  }
}

Parámetros: - field_path: Ruta al campo a renombrar - new_name: Nuevo nombre del campo - data_type: Tipo de dato (string, number, date, boolean)

map_values

Mapea valores de un campo usando un diccionario de reemplazo.

{
  "transform": {
    "map_values": [
      {"var": "status"},
      {
        "active": "Activo",
        "inactive": "Inactivo",
        "pending": "Pendiente"
      },
      "Desconocido"
    ]
  }
}

Parámetros: - field: Campo a mapear - mapping: Diccionario de mapeo valor->valor - default: Valor por defecto si no hay coincidencia

split_field

Divide un campo de texto en múltiples campos.

{
  "transform": {
    "split_field": [
      {"var": "full_name"},
      " ",
      ["first_name", "last_name"]
    ]
  }
}

Parámetros: - field: Campo a dividir - separator: Separador para dividir - output_fields: Array de nombres para los nuevos campos

Operadores de Validación

validate_required

Valida que campos requeridos estén presentes y no vacíos.

{
  "transform": {
    "validate_required": [
      ["name", "email", "phone"],
      "Campo requerido faltante: "
    ]
  }
}

Parámetros: - fields: Array de campos requeridos - error_prefix: Prefijo para mensaje de error

validate_email

Valida formato de email.

{
  "transform": {
    "validate_email": [
      {"var": "email"},
      "Formato de email inválido"
    ]
  }
}

validate_date

Valida formato de fecha.

{
  "transform": {
    "validate_date": [
      {"var": "birth_date"},
      "YYYY-MM-DD",
      "Fecha inválida"
    ]
  }
}

Operadores de Enriquecimiento

lookup

Busca valores en una tabla de referencia.

{
  "transform": {
    "lookup": [
      {"var": "category_id"},
      "categories",
      "id",
      "name"
    ]
  }
}

Parámetros: - search_value: Valor a buscar - table_name: Nombre de la tabla de referencia - search_field: Campo donde buscar - return_field: Campo a retornar

enrich_http

Enriquece datos llamando a una API HTTP.

{
  "transform": {
    "enrich_http": [
      "https://api.example.com/enrich",
      {"user_id": {"var": "id"}},
      "GET",
      {"Authorization": "Bearer token"},
      "data"
    ]
  }
}

Operadores de Agregación

group_by

Agrupa registros por un campo y aplica agregaciones.

{
  "transform": {
    "group_by": [
      {"var": "items"},
      "category",
      {
        "total": {"sum": {"var": "price"}},
        "count": {"count": "*"},
        "avg_price": {"avg": {"var": "price"}}
      }
    ]
  }
}

aggregate

Aplica funciones de agregación a arrays.

{
  "transform": {
    "aggregate": [
      {"var": "sales"},
      {
        "total_sales": {"sum": {"var": "amount"}},
        "avg_sale": {"avg": {"var": "amount"}},
        "max_sale": {"max": {"var": "amount"}},
        "min_sale": {"min": {"var": "amount"}}
      }
    ]
  }
}

Operadores de Texto

format_string

Formatea strings con placeholders.

{
  "transform": {
    "format_string": [
      "Bienvenido {name} {lastname}",
      {
        "name": {"var": "first_name"},
        "lastname": {"var": "last_name"}
      }
    ]
  }
}

regex_replace

Reemplaza texto usando expresiones regulares.

{
  "transform": {
    "regex_replace": [
      {"var": "phone"},
      "\\D",
      "",
      "g"
    ]
  }
}

Operadores de Fecha/Hora

date_format

Formatea fechas.

{
  "transform": {
    "date_format": [
      {"var": "created_at"},
      "DD/MM/YYYY HH:mm",
      "America/Santiago"
    ]
  }
}

date_add

Suma o resta tiempo a una fecha.

{
  "transform": {
    "date_add": [
      {"var": "due_date"},
      7,
      "days"
    ]
  }
}

Operadores de Seguridad

hash_field

Genera hash de un campo.

{
  "transform": {
    "hash_field": [
      {"var": "email"},
      "md5"
    ]
  }
}

Algoritmos soportados: md5, sha1, sha256, sha512

mask_field

Enmascara parte de un campo sensible.

{
  "transform": {
    "mask_field": [
      {"var": "credit_card"},
      4,
      "*",
      "end"
    ]
  }
}

Operadores de Control de Flujo

conditional

Ejecuta diferentes transformaciones basado en condiciones.

{
  "transform": {
    "conditional": [
      {">": [{"var": "age"}, 18]},
      {
        "status": "adult",
        "category": "A"
      },
      {
        "status": "minor",
        "category": "B"
      }
    ]
  }
}

switch

Selecciona entre múltiples opciones.

{
  "transform": {
    "switch": [
      {"var": "type"},
      {
        "premium": {"fee": 100},
        "basic": {"fee": 50},
        "free": {"fee": 0}
      },
      {"fee": 25}
    ]
  }
}

Ejemplos Prácticos

Transformación de Datos de Cliente

{
  "transform": {
    "rename": [
      [{"var": "firstName"}, "nombre", "string"],
      [{"var": "lastName"}, "apellido", "string"],
      [{"var": "birthDate"}, "fecha_nacimiento", "date"]
    ],
    "map_values": [
      {"var": "status"},
      {
        "A": "Activo",
        "I": "Inactivo",
        "P": "Pendiente"
      },
      "Desconocido"
    ],
    "validate_required": [
      ["nombre", "apellido", "email"],
      "Campo requerido faltante: "
    ]
  }
}

Enriquecimiento con Lookup

{
  "transform": {
    "lookup": [
      {"var": "department_id"},
      "departments",
      "id",
      "name"
    ],
    "lookup": [
      {"var": "manager_id"},
      "users",
      "id",
      "full_name"
    ]
  }
}

Desarrollo de Operadores Personalizados

Para crear operadores personalizados, implementa la interfaz CustomOperator:

from fracttal_etl.transform import CustomOperator

class MyCustomOperator(CustomOperator):
    def execute(self, data: dict, params: dict) -> dict:
        # Lógica del operador
        return transformed_data

Registra el operador en la configuración:

{
  "custom_operators": {
    "my_operator": "my_package.operators.MyCustomOperator"
  }
}

Referencias