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
| Propiedad | Detalle |
|---|---|
| Catálogo | cat_master_aplicaciones |
| Esquema / Base de Datos | catalogos |
| Nombre de Tabla | ctrl_config |
| Formato de Almacenamiento | Delta Lake (USING DELTA) |
| Identificador Único | config_id (Identidad autoincremental) |
| Change Data Feed (CDF) | Habilitado ('delta.enableChangeDataFeed' = 'true') |
| Soporte de Valores Default | Habilitado ('delta.feature.allowColumnDefaults' = 'supported') |
3. Diccionario de Datos
| Campo | Tipo de Dato | Nulo / Default | Descripción y Convención |
|---|---|---|---|
config_id | BIGINT | NOT NULL (Identity) | Identificador secuencial único generado automáticamente por Databricks Delta. |
proceso | STRING | NOT NULL | Nombre o identificador del proceso/job que consume el parámetro (ej. alp_rep_conciliacion_databricks). |
modulo | STRING | NOT NULL | Submódulo funcional o componente que utiliza el valor (ej. api_notificaciones, ingesta, conciliacion). |
clave | STRING | NOT NULL | Nombre del parámetro o variable en minúsculas/mayúsculas estandarizadas (ej. destinatarios, batch_size). |
valor | STRING | NOT NULL | Contenido del parámetro almacenado en formato texto (admite listas separadas por comas, URLs, JSON strings, enteros en string, etc.). |
tipo_dato | STRING | Default: 'STRING' | Tipo de dato esperado para casteo en código consumidor: STRING, INT, BOOLEAN, JSON, LIST. |
descripcion | STRING | Opcional | Explicación funcional del parámetro, público objetivo o consideraciones operativas. |
activo | BOOLEAN | Default: TRUE | Bandera de vigencia (true = activo, false = deshabilitado). Permite pausar flujos sin borrar metadata. |
fecha_creacion | TIMESTAMP | Default: CURRENT_TIMESTAMP() | Fecha y hora de alta del registro. |
fecha_actualizacion | TIMESTAMP | Default: 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
- 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).
- Inactivación en lugar de borrado físico: Preferir
UPDATE ... SET activo = FALSEantes queDELETE, para preservar la trazabilidad histórica de parámetros pasados. - 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íadbutils.secrets.get().