gss-bi-udfs 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

gss_bi_udfs/__init__.py

@@ -0,0 +1,11 @@
+from . import io
+from . import merges
+from . import transforms
+from . import utils
+
+__all__ = [
+    "io",
+    "merges",
+    "transforms",
+    "utils",
+]

gss_bi_udfs/io.py

@@ -0,0 +1,420 @@
+from pathlib import Path
+from datetime import datetime
+from .utils import get_env, get_table_info
+
+
+class _LocalFileInfo:
+    # univamentemente para uso de la libreria en entornos locales
+    def __init__(self, path: str):
+        self.path = path
+        p = Path(path)
+        self.name = p.name
+        self.size = p.stat().st_size if p.exists() else 0
+        self.modificationTime = int(p.stat().st_mtime * 1000) if p.exists() else 0
+
+    def isFile(self) -> bool:
+        return Path(self.path).is_file()
+
+    def __repr__(self) -> str:
+        return (
+            "FileInfo("
+            f"path='{self.path}', "
+            f"name='{self.name}', "
+            f"size={self.size}, "
+            f"modificationTime={self.modificationTime}"
+            ")"
+        )
+
+def _normalize_path(path):
+    if path.startswith("dbfs:"):
+        return path.replace("dbfs:", "", 1)
+    return path
+
+
+def _ls_path(base_path):
+    try:
+        # Databricks runtime provides dbutils in globals.
+        files = dbutils.fs.ls(base_path)  # type: ignore
+        return files
+    except Exception:
+        local_path = _normalize_path(base_path)
+        p = Path(local_path)
+        if not p.exists():
+            return []
+        return [_LocalFileInfo(str(child)) for child in p.iterdir()]
+
+# def load_latest_file_bronze(spark, data_base, schema, table, env=None):
+def load_latest_parquet(spark, data_base, schema, table, env=None):
+    """
+    Carga el último archivo Parquet para la tabla especificada y retorna un DataFrame.
+    
+    Parámetros:
+      spark (SparkSession): Sesión activa de Spark.
+      data_base (str): Nombre de la base de datos.
+      schema (str): Nombre del esquema.
+      table (str): Nombre de la tabla.
+      env (str, opcional): Entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+                           Si no se proporciona, se obtiene usando get_env().
+    
+    Retorna:
+      DataFrame de Spark cargado desde el archivo Parquet más reciente.
+    """
+    env = env or get_env()
+    base_path = f"/Volumes/bronze/{data_base}_{schema}/{env}/{table}/"
+    print("Ruta base:", base_path)
+
+    try:
+        files = _ls_path(base_path)
+
+        parquet_files = [f for f in files if table in f.name]
+        
+        if not parquet_files:
+            return None
+        
+        latest_file = sorted(parquet_files, key=lambda f: f.name, reverse=True)[0]
+        df = spark.read.parquet(latest_file.path)
+        return df
+             
+    except Exception as e:
+        print("Error al procesar los archivos:", e)
+        return None
+
+    
+def return_parquets_and_register_temp_views(spark, tables_load, verbose=False, env=None):
+    """
+    Carga dataframes a partir de un diccionario de definición de tablas y materializa vistas temporales.
+    Retorna un diccionario con los dataframes.
+    
+    Parámetros:
+        spark (SparkSession): Sesión activa de Spark.
+        tables_load (dict): Diccionario que define las tablas a cargar y sus vistas temporales.
+        verbose (bool): Si es True, imprime mensajes de estado durante la carga.
+        env (str, opcional): Entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+                             Si no se proporciona, se obtiene usando get_env().
+                             
+    Retorna:
+        dict: Diccionario donde las claves son nombres completos de tablas y los valores son DataFrames.
+    """
+    dataframes = {}
+
+    for data_base, schemas in tables_load.items():
+        for schema, tables in schemas.items():
+            for t in tables:
+                table = t['table']
+                view = t['view']
+
+                # Cargar el dataframe usando la función que proveés
+                df = load_latest_parquet(spark, data_base, schema, table, env)
+                
+                # Guardar en el diccionario
+                key = f"{data_base}.{schema}.{table}"
+                dataframes[key] = df
+
+                # Materializar la vista (esto no necesita asignación en Python)
+                try:
+                    df.createOrReplaceTempView(view)
+                    if verbose:
+                        print(f'Tabla "{key}" cargada y vista "{view}" materializada')
+                except Exception as e:
+                    print(f"Error al materializar la vista '{view} tabla {key}': {e}")
+                
+    return dataframes
+
+
+def parquets_register_temp_views(spark, tables_load, verbose=False, env=None):
+    """
+    Lee los últimos parquets y materializa vistas temporales en Spark. Sin retorna nada.
+    Parámetros:
+        spark (SparkSession): Sesión activa de Spark.
+        tables_load (dict): Diccionario que define las tablas a cargar y sus vistas temporales.
+            La estructura esperada del parámetro `tables_load` es un diccionario
+            anidado con el siguiente formato:
+
+                {
+                    "<base_de_datos>": {
+                        "<schema>": [
+                            {
+                                "table": "<nombre_tabla>",
+                                "view": "<nombre_vista_temporal>"
+                            },
+                            ...
+                        ]
+                    },
+                    ...
+                }
+            Ejemplo:
+                tables_load = {
+                    "bup": {
+                        "bup": [
+                            {"table": "naturalpersons", "view": "vw_naturalpersons"},
+                            {"table": "maritalstatus", "view": "vw_maritalstatus"},
+                            {"table": "genders", "view": "vw_genders"},
+                            {"table": "legalpersons", "view": "vw_legalpersons"},
+                            {"table": "phones", "view": "vw_phones"},
+                            {"table": "emails", "view": "vw_emails"},
+                            {"table": "addresses", "view": "vw_addresses"},
+                            {"table": "persons", "view": "vw_persons"},
+                            {"table": "administrativefreezeperiods", "view": "vw_administrativefreezeperiods"},
+                            {"table": "fraudrisklevels", "view": "vw_fraudrisklevels"},
+                        ],
+                    },
+                    "oraculo": {
+                        "dbo": [
+                            {"table": "ml_segmentacion", "view": "vw_segmentacion"},
+                        ],
+                    },
+                    "timepro": {
+                        "insudb": [
+                            {"table": "logauth0user", "view": "vw_logauth0user"},
+                            {"table": "benefitprogramadhesion", "view": "vw_benefitprogramadhesion"},
+                        ],
+                    },
+                    "dwgssprotmp": {
+                        "dwo": [
+                            {"table": "int_dim_clientactive_bds", "view": "vw_int_dim_cliente_active"},
+                        ],
+                    },
+                    "odscommon": {
+                        "employee": [
+                            {"table": "vw_active_employee", "view": "vw_active_employee"},
+                        ],
+                    },
+                }
+        verbose (bool): Si es True, imprime mensajes de estado durante la carga.
+        env (str, opcional): Entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+                             Si no se proporciona, se obtiene usando get_env().
+    Retorna:
+        None
+    """
+    for data_base, schemas in tables_load.items():
+        for schema, tables in schemas.items():
+            for t in tables:
+                table = t['table']
+                view = t['view']
+                try:
+                    df = load_latest_parquet(spark, data_base, schema, table, env)
+                    df.createOrReplaceTempView(view)
+                    if verbose:
+                        print(f'Vista "{view}" materializada desde {data_base}.{schema}.{table}')
+                except Exception as e:
+                    print(f"Error al materializar la vista '{view}' desde {data_base}.{schema}.{table}: {e}")
+
+
+def load_latest_excel(spark, source_file, env=None):
+    
+    """
+    Carga el último archivo de Excel (aunque no tenga extensión visible) para la carpeta especificada
+    y retorna un DataFrame.
+    
+    Parámetros:
+      spark (SparkSession): Sesión activa de Spark.
+      source_file (str): Nombre de la carpeta.
+        env (str, opcional): Entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+                            Si no se proporciona, se obtiene usando get_env().
+    Retorna:
+      DataFrame de Spark cargado desde el archivo Excel más reciente (en formato xls).
+    """
+    
+    import pandas as pd
+    
+    env = env or get_env()
+    base_path = f"/Volumes/bronze/excel/{env}/{source_file}/"
+    print("Ruta base:", base_path)
+    
+    try:
+        files = _ls_path(base_path)
+        print("Archivos encontrados:", [f.name for f in files])     
+        excel_candidates = [f for f in files if f.isFile()]
+
+        if not excel_candidates:
+            print(f"No se encontraron archivos en la carpeta: {source_file}")
+            return None
+        
+        latest_file = sorted(excel_candidates, key=lambda f: f.name, reverse=True)[0]
+        
+        file_path = latest_file.path.replace("dbfs:", "")
+
+        pdf = pd.read_excel(file_path, header=0, engine='xlrd')
+        
+        return spark.createDataFrame(pdf)
+    
+    except Exception as e:
+        return None
+
+
+def return_excels_and_register_temp_views(spark, files_load, verbose=False, env=None):
+    """
+    Carga dataframes a partir de un diccionario de definición de excels y materializa vistas temporales.
+    Retorna un diccionario con los dataframes.
+    
+    Parámetros:
+        spark (SparkSession): Sesión activa de Spark.
+        files_load (dict): Diccionario que define las tablas a cargar y sus vistas temporales.
+            La estructura esperada del parámetro `files_load` es un diccionario
+            anidado con el siguiente formato:
+
+                {
+                    "<Dominio>": {
+                        "<SubDominio>": [
+                            {
+                                "file": "<nombre_archivo>",
+                                "view": "<nombre_vista_temporal>"
+                            },
+                            ...
+                        ]
+                    },
+                    ...
+                }
+            Ejemplo:
+        verbose (bool): Si es True, imprime mensajes de estado durante la carga.
+        env (str, opcional): Entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+                             Si no se proporciona, se obtiene usando get_env().
+    
+    Retorna:
+        dict: Diccionario donde las claves son nombres completos de tablas y los valores son DataFrames.
+            Quedando las vistas materializadas en el entorno Spark.
+    """
+    dataframes = {}
+
+    for domain, subdomain in files_load.items():
+        for subdomain, tables in subdomain.items():
+            for t in tables:
+                file = t['file']
+                view = t['view']
+
+                # Cargar el dataframe usando la función que proveés
+                source_file = f"{domain}/{subdomain}/{file}"
+                df = load_latest_excel(spark, source_file, env)
+                
+                # Guardar en el diccionario
+                key = f"{domain}.{subdomain}.{file}"
+                dataframes[key] = df
+
+                # Materializar la vista (esto no necesita asignación en Python)
+                try:
+                    df.createOrReplaceTempView(view)
+                    if verbose:
+                        print(f'El archivo "{key}" cargado y vista "{view}" materializada')
+                except Exception as e:
+                    print(f"Error al materializar la vista '{view} tabla {key}': {e}")
+                
+    return dataframes
+
+
+def excels_register_temp_views(spark, files_load, verbose=False, env=None):
+    """
+    Lee los últimos archivos excels y materializa vistas temporales en Spark. Sin retorna nada.
+    
+    Parámetros:
+        spark (SparkSession): Sesión activa de Spark.
+        files_load (dict): Diccionario que define las tablas a cargar y sus vistas temporales.
+            La estructura esperada del parámetro `files_load` es un diccionario
+            anidado con el siguiente formato:
+
+                {
+                    "<Dominio>": {
+                        "<SubDominio>": [
+                            {
+                                "file": "<nombre_archivo>",
+                                "view": "<nombre_vista_temporal>"
+                            },
+                            ...
+                        ]
+                    },
+                    ...
+                }
+            Ejemplo:
+        verbose (bool): Si es True, imprime mensajes de estado durante la carga.
+        env (str, opcional): Entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+                             Si no se proporciona, se obtiene usando get_env().
+    
+    Retorna:
+        Nada
+    """
+
+    for domain, subdomain in files_load.items():
+        for subdomain, tables in subdomain.items():
+            for t in tables:
+                file = t['file']
+                view = t['view']
+
+                # Cargar el dataframe usando la función que proveés
+                source_file = f"{domain}/{subdomain}/{file}"
+                df = load_latest_excel(spark, source_file, env)
+                
+                # Guardar en el diccionario
+                key = f"{domain}.{subdomain}.{file}"
+
+                # Materializar la vista (esto no necesita asignación en Python)
+                try:
+                    df.createOrReplaceTempView(view)
+                    if verbose:
+                        print(f'El archivo "{key}" leido y vista "{view}" materializada')
+                except Exception as e:
+                    print(f"Error al materializar la vista '{view} tabla {key}': {e}")
+
+
+def load_and_materialize_views(action, **kwargs):    
+    actions_load_bronze = {
+        # Todas las acciones aqui declaradas deberan devolver un diccionario de DataFrames
+        # 'load_notebook': load_notebook,
+        'return_parquets_and_register_temp_views': return_parquets_and_register_temp_views,
+        'parquets_register_temp_views': parquets_register_temp_views,
+        'return_excels_and_register_temp_views': return_excels_and_register_temp_views,
+        'excels_register_temp_views': excels_register_temp_views,
+        # ir agregando más acciones acá
+    }
+    results = {}
+    func = actions_load_bronze.get(action)
+    if func:
+        results = func(**kwargs)
+        # results[action] = result
+    else:
+        print(f"Acción '{action}' no está implementada.")
+    return results
+
+
+def save_table_to_delta(df, catalog, schema, table_name):
+    """
+    Guarda un DataFrame en formato Delta en la ubicación y tabla especificadas,
+    sobrescribiendo los datos existentes y el esquema si es necesario.
+
+    Parámetros:
+      df (DataFrame): DataFrame de Spark que se desea guardar.
+      db_name (str): Nombre del catálogo o base de datos destino.
+      schema (str): Nombre del esquema, capa o entorno destino (ejemplo: 'silver', 'gold').
+      table_name (str): Nombre de la tabla destino.
+
+    Retorna:
+      None
+
+    Lógica:
+      - Utiliza la función auxiliar 'get_table_info' para obtener el path
+        de almacenamiento y el nombre completo de la tabla.
+      - Escribe el DataFrame en formato Delta en la ruta especificada,
+        sobrescribiendo cualquier dato y adaptando el esquema si es necesario.
+      - Registra la tabla como tabla administrada en el metastore con el nombre completo.
+
+    Notas:
+      - El modo 'overwrite' reemplaza todos los datos existentes en la tabla.
+      - La opción 'overwriteSchema' asegura que el esquema de la tabla se actualice si cambió.
+      - Es necesario que la ruta y la tabla existan o sean accesibles en el entorno Spark.
+      - Las opciones
+        `.option("delta.columnMapping.mode", "nameMapping")` y `.option("delta.columnMapping.mode", "name")`
+        permiten especificar el modo de mapeo de columnas para Delta Lake:
+          - **"nameMapping"**: usa un mapeo explícito de columnas por nombre, útil para cambios de nombre o reordenamiento de columnas sin perder datos.
+          - **"name"**: usa el nombre de columna directamente para el mapeo, opción recomendada cuando no se necesita trazabilidad de cambios en los nombres de columna, permite utilizar los acentos en el nombre de las columnas.
+      - Si ambas opciones se usan al mismo tiempo, solo una tendrá efecto (se aplicará la última indicada).
+
+    """
+    dim_destino = get_table_info(catalog=catalog, schema=schema, table=table_name)
+    (
+        df.write
+        .format("delta")
+        .option("path", dim_destino["path"])
+        .mode("overwrite")
+        .option("overwriteSchema", "true")
+        .option("delta.columnMapping.mode", "nameMapping") \
+        .option("delta.columnMapping.mode", "name") \
+        .saveAsTable(dim_destino["full_table_name"])
+    )

gss_bi_udfs/merges.py

@@ -0,0 +1,191 @@
+from pyspark.sql import functions as F
+from .io import save_table_to_delta
+from .utils import get_table_info
+from .transforms import add_hashid
+
+def merge_scd2(
+    spark,
+    df_dim_src,
+    table_name,
+    business_keys,
+    surrogate_key,
+    eow_date="9999-12-31"
+):
+    """
+    Aplica Slowly Changing Dimension Tipo 2 (SCD2) sobre una tabla Delta.
+
+    El DataFrame de entrada (`df_dim_src`) debe representar el estado actual de la dimensión
+    a nivel de negocio, con el MISMO esquema lógico que la tabla destino,
+    excluyendo únicamente la PK física (surrogate key) del Data Warehouse.
+    `df_dim_src` NO debe incluir la clave primaria física (surrogate key).
+    Esta se genera internamente como un hash de (business_keys + valid_from).
+
+    La lógica implementa versionado histórico de registros utilizando fechas de vigencia
+    (valid_from, valid_to), manteniendo una única versión activa por entidad de negocio.
+
+    CONCEPTOS CLAVE Y SUPUESTOS DEL MODELO
+    -------------------------------------
+    1. Clave de negocio (Business Keys):
+       - El parámetro `business_keys` DEBE representar la clave de negocio que identifica
+         unívocamente a la entidad (por ejemplo: nbranch, nproduct).
+       - Esta clave NO debe cambiar en el tiempo.
+       - El merge se realiza exclusivamente contra esta clave de negocio
+         y contra el registro activo (valid_to = eow_date).
+
+    2. Clave primaria física del Data Warehouse:
+       - La dimensión DEBE tener una clave primaria física (surrogate key) propia del DW
+         para identificar cada versión histórica del registro.
+       - Esta PK física NO participa de la lógica de comparación ni del merge funcional,
+         y su generación queda fuera del alcance de esta función.
+
+    3. Columnas comparadas (detección de cambios):
+       - La función compara TODAS las columnas del DataFrame de entrada
+         EXCEPTO:
+           - la clave de negocio (`business_keys`)
+           - las columnas de vigencia (`valid_from`, `valid_to`)
+       - Si cualquiera de las columnas comparadas cambia, se genera una nueva versión
+         del registro (SCD Tipo 2).
+       - Esto implica que cualquier nueva columna agregada al esquema será
+         automáticamente considerada para versionado.
+
+       IMPORTANTE:
+       - Por este motivo, se recomienda que el DataFrame NO incluya columnas técnicas
+         o volátiles (timestamps de carga, ids de proceso, metadatos, etc.),
+         ya que provocarían versionado innecesario.
+
+       - El DataFrame de entrada PUEDE incluir las columnas `valid_from` y `valid_to`;
+         en caso de existir, serán ignoradas para la detección de cambios y
+         recalculadas internamente por la función.
+
+    4. Manejo de fechas de vigencia:
+       - valid_from: DATE inclusiva
+       - valid_to:    DATE inclusiva
+       - El registro activo siempre tiene valid_to = eow_date (por defecto 9999-12-31).
+       - Ante un cambio:
+           * la versión anterior se cierra con valid_to = current_date() - 1
+           * la nueva versión se inserta con valid_from = current_date()
+       - Esto garantiza que no existan solapamientos de vigencia.
+
+       - Si el DataFrame de entrada no contiene `valid_from` y `valid_to`,
+         la función las generará automáticamente durante la carga inicial
+         o incremental.
+
+    5. Carga inicial:
+       - Si la tabla destino no existe, se realiza un full load inicial,
+         asignando valid_from = '1900-01-01' y valid_to = eow_date
+         a todos los registros.
+
+    PARÁMETROS
+    ----------
+    spark : SparkSession
+        SparkSession activo.
+    df_dim_src : DataFrame
+        DataFrame de Spark que contiene los datos a mergear.
+        Debe incluir TODAS las columnas de negocio de la dimensión
+        (clave(s) de negocio + atributos versionables),
+        con el mismo esquema lógico que la tabla destino.
+        NO debe incluir la clave primaria física (surrogate key).
+    table_name : str
+        Nombre completo (catalogo.esquema.tabla) de la tabla Delta destino. 
+    business_keys : str or list[str]
+        Nombre(s) de la(s) columna(s) que representa(n) la clave de negocio.
+        Puede ser una clave simple (str) o compuesta (lista de str).
+    surrogate_key : str
+        Nombre de la clave primaria física (surrogate key) de la dimensión.
+        Se genera internamente como un hash de (business_keys + valid_from).
+    eow_date : str, opcional
+        Fecha de fin de vigencia para registros activos.
+        Por defecto: '9999-12-31'.
+
+    RETORNO
+    -------
+    None
+        La función ejecuta el merge directamente sobre la tabla Delta.
+    """
+
+    # Normalize business_keys to a list (support single column or composite key)
+    if isinstance(business_keys, str):
+        business_keys = [business_keys]
+
+    missing_bk = [c for c in business_keys if c not in df_dim_src.columns]
+    if missing_bk:
+        raise ValueError(f"Columnas de business key inexistentes en df_dim_src: {missing_bk}")
+
+    exclude_cols = set(business_keys) | {"valid_from", "valid_to"}
+    compare_cols = [c for c in df_dim_src.columns if c not in exclude_cols]
+
+    info_table = get_table_info(spark,full_table_name=table_name)
+
+    if not spark.catalog.tableExists(table_name):
+        df_nov = (
+            df_dim_src
+            .withColumn("valid_from", F.to_date(F.lit("1900-01-01")))
+            .withColumn("valid_to",   F.to_date(F.lit(eow_date)))
+        )
+        pk_cols = business_keys + ["valid_from"]
+        df_nov = add_hashid(df_nov, pk_cols, surrogate_key)
+        
+        save_table_to_delta(spark, df_nov, info_table["catalog"], info_table["schema"], info_table["table"])
+        df_nov.write \
+            .format("delta") \
+            .mode("overwrite") \
+            .option("overwriteSchema", "true") \
+            .saveAsTable(table_name)
+        print(f"[FULL LOAD] {table_name} creado con SCD-2")
+        return
+
+    df_nov = (
+        df_dim_src
+        .withColumn("valid_from", F.current_date().cast("date"))
+        .withColumn("valid_to",   F.to_date(F.lit(eow_date)))
+    )
+    pk_cols = business_keys + ["valid_from"]
+    df_nov = add_hashid(df_nov, pk_cols, surrogate_key)
+
+    delta_tgt = info_table["full_table_name"]
+    bk_cond = " AND ".join([f"t.{k} = s.{k}" for k in business_keys])
+    merge_cond = f"{bk_cond} AND t.valid_to = date('{eow_date}')"
+    t_hash = "xxhash64(concat_ws('', " + ", ".join(f"t.{c}" for c in compare_cols) + "))"
+    s_hash = "xxhash64(concat_ws('', " + ", ".join(f"s.{c}" for c in compare_cols) + "))"
+    diff_cond = f"{t_hash} <> {s_hash}"
+
+    (delta_tgt.alias("t")
+        .merge(df_nov.alias("s"), merge_cond)
+        .whenMatchedUpdate(
+            condition=diff_cond,
+            set={"valid_to": "date_sub(current_date(), 1)"}
+        )
+        .whenNotMatchedInsertAll()
+        .whenNotMatchedBySourceUpdate(
+            condition=f"t.valid_to = date('{eow_date}')",
+            set={"valid_to": "date_sub(current_date(), 1)"}
+        )
+        .execute()
+    )
+
+    closed_count = delta_tgt.toDF() \
+        .filter(F.col("valid_to") == F.date_sub(F.current_date(), 1)) \
+        .count()
+    if closed_count > 0:
+        print(f"Se cerraron {closed_count} versiones en {table_name}")
+
+    t_active = (
+        delta_tgt.toDF()
+        .filter(F.col("valid_to") == F.to_date(F.lit(eow_date)))
+    )
+    join_conds = [F.col(f"s.{k}") == F.col(f"t.{k}") for k in business_keys] + [
+        F.col(f"s.{c}") == F.col(f"t.{c}") for c in compare_cols
+    ]
+    df_to_app = df_nov.alias("s").join(
+        t_active.alias("t"), on=join_conds, how="left_anti"
+    )
+
+    new_count = df_to_app.limit(1).count()
+    if new_count > 0:
+        df_to_app.write \
+            .format("delta") \
+            .mode("append") \
+            .saveAsTable(table_name)
+        print(f"Se insertaron nuevas versiones en {table_name}")
+    else:
+        print(f"No hay nuevas versiones para {table_name}")

gss_bi_udfs/transforms.py

@@ -0,0 +1,56 @@
+from pyspark.sql import DataFrame
+from pyspark.sql.functions import xxhash64
+from pyspark.sql.functions import concat_ws, col
+
+
+from .utils import get_default_value_by_type
+
+def add_hashid(
+        df: DataFrame,
+        columns: list[str],
+        new_col_name: str = "hashid"
+    ) -> DataFrame:
+        """
+        Agrega una columna hash (PK) a partir de la concatenación de columnas
+        y reordena el DataFrame dejando el hash como primera columna.
+
+        Parametros:
+            df: DataFrame de Spark de entrada
+            columns: Lista de columnas a concatenar
+            new_col_name: Nombre de la columna hash (default: hashid)
+            
+        Retorna:
+            DataFrame con hash agregado
+        """
+
+        if not columns:
+            raise ValueError("La lista de columnas no puede estar vacía")
+
+        # Concatenación segura
+        concatenated = concat_ws("|", *[col(c).cast("string") for c in columns])
+
+        # Hash rápido y determinístico (ideal para PK técnica)
+        df_with_hash = df.withColumn(new_col_name, xxhash64(concatenated))
+
+        # Reordenar columnas
+        original_cols = [c for c in df.columns if c != new_col_name]
+        new_cols = [new_col_name] + original_cols
+
+        return df_with_hash.select(*new_cols)
+    
+
+def get_default_record(spark, df: DataFrame) -> DataFrame:
+    """
+    Crea un DataFrame con un único registro de valores por defecto según el esquema de df:
+    Parámetros:
+        spark: SparkSession activo.
+        df (DataFrame): DataFrame de Spark del cual se tomará el esquema.
+        
+    Retorna:
+        DataFrame: DataFrame con un único registro con valores por defecto.
+    """
+    defaults = {}
+    for field in df.schema.fields:
+        defaults[field.name] = get_default_value_by_type(field.dataType)
+    
+    return spark.createDataFrame([defaults], schema=df.schema)