Skip to main content

Tabla para configuraciones en Databricks

1. Resumen Ejecutivo y Propósito​

La tabla ctrl_config actúa como un repositorio centralizado de parámetros dinámicos y variables de control para los pipelines de datos y servicios satélite en Databricks (por ejemplo, procesos de conciliación entre Oracle Cloud y AS400, orquestación de notificaciones y jobs de sincronización).

Objetivos Principales:​

  • Desacoplar la lógica de negocio de la configuración: Evitar el hardcoding de correos, umbrales, flags de activación y endpoints dentro de los notebooks y jobs de PySpark.
  • Auditoría y trazabilidad: Registrar qué parámetros se modifican, cuándo y quién los ajusta, aprovechando las capacidades nativas de Delta Lake.
  • Flexibilidad operativa: Permitir a los ingenieros y administradores encender, pausar o modificar el comportamiento de un pipeline actualizando un registro, sin necesidad de re-desplegar código.

2. Metadatos de la Tabla​

PropiedadDetalle
Catálogocat_master_aplicaciones
Esquema / Base de Datoscatalogos
Nombre de Tablactrl_config
Formato de AlmacenamientoDelta Lake (USING DELTA)
Identificador Únicoconfig_id (Identidad autoincremental)
Change Data Feed (CDF)Habilitado ('delta.enableChangeDataFeed' = 'true')
Soporte de Valores DefaultHabilitado ('delta.feature.allowColumnDefaults' = 'supported')

3. Diccionario de Datos​

CampoTipo de DatoNulo / DefaultDescripción y Convención
config_idBIGINTNOT NULL (Identity)Identificador secuencial único generado automáticamente por Databricks Delta.
procesoSTRINGNOT NULLNombre o identificador del proceso/job que consume el parámetro (ej. alp_rep_conciliacion_databricks).
moduloSTRINGNOT NULLSubmódulo funcional o componente que utiliza el valor (ej. api_notificaciones, ingesta, conciliacion).
claveSTRINGNOT NULLNombre del parámetro o variable en minúsculas/mayúsculas estandarizadas (ej. destinatarios, batch_size).
valorSTRINGNOT NULLContenido del parámetro almacenado en formato texto (admite listas separadas por comas, URLs, JSON strings, enteros en string, etc.).
tipo_datoSTRINGDefault: 'STRING'Tipo de dato esperado para casteo en código consumidor: STRING, INT, BOOLEAN, JSON, LIST.
descripcionSTRINGOpcionalExplicación funcional del parámetro, público objetivo o consideraciones operativas.
activoBOOLEANDefault: TRUEBandera de vigencia (true = activo, false = deshabilitado). Permite pausar flujos sin borrar metadata.
fecha_creacionTIMESTAMPDefault: CURRENT_TIMESTAMP()Fecha y hora de alta del registro.
fecha_actualizacionTIMESTAMPDefault: CURRENT_TIMESTAMP()Fecha y hora del último cambio en la configuración.

4. Definición DDL y Optimización​

4.1 Script DDL (Data Definition Language)​

CREATE TABLE IF NOT EXISTS cat_master_aplicaciones.catalogos.ctrl_config (
config_id BIGINT GENERATED ALWAYS AS IDENTITY,
proceso STRING NOT NULL, -- Ej: 'alp_rep_conciliacion_databricks'
modulo STRING NOT NULL, -- Ej: 'api_notificaciones', 'pipeline'
clave STRING NOT NULL, -- Ej: 'destinatarios', 'batch_size'
valor STRING NOT NULL, -- El valor parametrizado
tipo_dato STRING DEFAULT 'STRING',-- Caseteo en PySpark: 'STRING', 'INT', 'BOOLEAN', 'JSON'
descripcion STRING, -- Nota explicativa del parámetro
activo BOOLEAN DEFAULT TRUE, -- Permite pausar una configuración sin borrarla
fecha_creacion TIMESTAMP DEFAULT CURRENT_TIMESTAMP(),
fecha_actualizacion TIMESTAMP DEFAULT CURRENT_TIMESTAMP()
)
USING DELTA
TBLPROPERTIES (
'delta.feature.allowColumnDefaults' = 'supported',
'delta.enableChangeDataFeed' = 'true',
'comment' = 'Tabla centralizada de parámetros y configuraciones para pipelines de datos Alpura'
);

4.2 Estrategia de Optimización y Z-Order​

Dado que las consultas de configuración siempre filtran por el pipeline y el módulo específico que está en ejecución, se aplica un ZORDER sobre (proceso, modulo) para optimizar el data skipping y reducir el tiempo de escaneo a nivel de micro-particiones:

OPTIMIZE cat_master_aplicaciones.catalogos.ctrl_config
ZORDER BY (proceso, modulo);

Frecuencia recomendada: Ejecutar este comando semanalmente o posterior a cargas batch/mantenimientos masivos en entornos productivos.


5. Casos de Uso y Ejemplos de Implementación​

5.1 Registro de Destinatarios para Reporte de Conciliación​

Inserción inicial para configurar la lista de distribución del reporte integral de conciliación (Oracle Cloud vs. AS400):

INSERT INTO cat_master_aplicaciones.catalogos.ctrl_config
(
proceso,
modulo,
clave,
valor,
tipo_dato,
descripcion
)
VALUES
(
'alp_rep_conciliacion_databricks',
'api_notificaciones',
'destinatarios',
'correo1@alpura.com, correo2@alpura.com, correo3@alpura.com, correo4@alpura.com, correo5@alpura.com',
'STRING',
'Lista de correos para Reporte Integral de Conciliación: Clientes y Artículos (Oracle vs AS400)'
);

5.2 Patrón de Consumo en PySpark​

A continuación se muestra el patrón estándar para consultar el parámetro en un pipeline de Databricks, castearlo y convertirlo en una lista Python limpia de destinatarios:

from pyspark.sql import functions as F

def obtiene_ctrl_config(proceso_nombre: str, clave: str):

tabla_ruta = "cat_master_aplicaciones.catalogos.ctrl_config"

# 1. Leer de la tabla buscando la combinación exacta de proceso y clave
df_config = spark.table(tabla_ruta) \
.filter((col("proceso") == proceso_nombre) & (col("clave") == clave) & (col("activo") == True)) \
.select("valor", "tipo_dato")

fila = df_config.first() # Obtenemos solo el primer registro que coincida

# Si no encuentra la configuración, retornamos None
if not fila:
print(f"⚠️ Advertencia: No se encontró la clave '{clave}' para el proceso '{proceso_nombre}'.")
return None

valor_raw = fila["valor"]
tipo = fila["tipo_dato"].upper()

# 2. Casteo del tipo de dato
if tipo == "INT":
return int(valor_raw)
elif tipo == "BOOLEAN":
return valor_raw.lower() in ("true", "1", "t", "yes")
else:
return valor_raw

# --- Ejemplo de uso en el módulo de notificaciones ---
proceso_id = "alp_rep_conciliacion_databricks"
modulo_id = "api_notificaciones"
clave_param = "destinatarios"

# 1. Recuperar string de destinatarios
destinatarios_raw = obtiene_ctrl_config(proceso_id, clave_param)

# 2. Parsear a lista limpia (quitando espacios en blanco accidentales)
lista_destinatarios = [email.strip() for email in destinatarios_raw.split(",") if email.strip()]

print(f"Total destinatarios configurados: {len(lista_destinatarios)}")
print(f"Destinatarios: {lista_destinatarios}")

5.3 Actualizaciones y Auditoría con Delta Change Data Feed (CDF)​

Actualización de valores​

Cuando se requiera añadir o modificar correos:

UPDATE cat_master_aplicaciones.catalogos.ctrl_config
SET
valor = 'email_1@alpura.com, email_2@alpura.com, nuevo.usuario@alpura.com',
fecha_actualizacion = CURRENT_TIMESTAMP()
WHERE proceso = 'alp_rep_conciliacion_databricks'
AND modulo = 'api_notificaciones'
AND clave = 'destinatarios';

Consulta de Auditoría (Trazabilidad)​

Gracias a 'delta.enableChangeDataFeed' = 'true', se puede inspeccionar el historial completo de quién y cuándo modificó los parámetros:

-- Consultar cambios realizados a partir de una versión de tabla específica
SELECT
config_id,
proceso,
modulo,
clave,
valor,
_change_type,
_commit_version,
_commit_timestamp
FROM table_changes('cat_master_aplicaciones.catalogos.ctrl_config', 1)
WHERE clave = 'destinatarios';

6. Convenciones y Buenas Prácticas​

  1. Nomenclatura Estandarizada:
    • proceso: Nombrado en minúsculas snake_case consistente con el nombre del workflow/job (ej. alp_rep_conciliacion_databricks).
    • modulo: Componente funcional (api_notificaciones, conciliacion_clientes, conciliacion_articulos).
    • clave: Corto y específico (destinatarios, api_endpoint, retries_max, umbral_diferencia_pct).
  2. Inactivación en lugar de borrado físico: Preferir UPDATE ... SET activo = FALSE antes que DELETE, para preservar la trazabilidad histórica de parámetros pasados.
  3. Manejo de Secretos: Si la configuración involucra tokens, llaves de API o contraseñas, no deben almacenarse en texto plano en valor. En su lugar, almacenar la referencia del secreto de Databricks (ej. dbx_scope:notif_secret_key) y resolverlo en runtime vía dbutils.secrets.get().