Pipeline ETL Medallón: Jikan API (MyAnimeList) en Databricks

Este proyecto implementa un pipeline ETL (Extracción, Transformación y Carga) modular y automatizado que extrae datos de anime de la API pública de Jikan (MyAnimeList), los limpia, los estandariza y genera agregaciones de negocio listas para análisis de Business Intelligence.

El proyecto está diseñado bajo la Arquitectura Medallón (Bronze, Silver y Gold) y se empaqueta como un Python Wheel (.whl) listo para ser desplegado de manera ágil y eficiente en Databricks.

---

Arquitectura Medallón

El pipeline procesa los datos de manera secuencial a través de tres capas diferenciadas:

graph LR
    API[Jikan API] -->|Extracción Cruda| Bronze[(bronze.anime_raw)]
    Bronze -->|Limpieza e Integridad| Silver[(silver.anime_cleaned)]
    Silver -->|Agregaciones de Negocio| Gold[(gold.studios_performance)]
    Silver -->|Tendencias y Métricas| Gold2[(gold.demographics_trends)]

Loading

1. Capa Bronze (bronze.py)

• Propósito: Extracción cruda y almacenamiento a nivel físico ("Source of Truth").
• Acciones:
  • Llama de manera paginada a la API de Jikan descargando 250 registros (10 páginas).
  • Pausa de 0.5s por request para respetar los límites de la API (Evita errores HTTP 429).
  • Aplana campos clave estructurados manteniendo una columna especial _raw_json (Schema-on-read) con el payload completo para resiliencia ante futuros cambios.
  • Guarda el resultado en formato Delta en bronze.anime_raw.

2. Capa Silver (silver.py)

• Propósito: Garantizar la integridad, calidad y estandarización del dato.
• Acciones:
  • Valida claves primarias (limpia registros con mal_id nulo).
  • Elimina registros duplicados.
  • Convierte campos de fecha ISO (aired_from) a timestamps reales (aired_from_date).
  • Limpia textos: recorta valores complejos (ej. "PG-13 - Teens 13 or older" pasa a ser "PG-13").
  • Feature Engineering: Genera la columna booleana has_trailer basada en la existencia de la URL del trailer.
  • Guarda en formato Delta optimizado en silver.anime_cleaned.

3. Capa Gold (gold.py)

• Propósito: Generar agregaciones e información de valor de negocio lista para reportes (PowerBI, Tableau, Dashboards).
• Tablas Generadas:
  • gold.studios_performance: Ránking de los mejores estudios de animación según puntuación promedio de sus animes (filtrando para evitar sesgos con animes de menos de 1000 votos).
  • gold.demographics_yearly_trends: Histórico anual del volumen de lanzamientos por categoría demográfica (Shounen, Seinen, etc.).
  • gold.rating_performance: Rendimiento analítico y de popularidad según la clasificación por edades de los animes.
  • gold.source_material_success: Análisis de puntaje promedio para identificar si las adaptaciones de Manga, Novelas Ligeras o formatos Originales son más exitosas.

---

Estructura del Proyecto

etl_project/
├── .gitignore
├── pyproject.toml             # Configuración del paquete y dependencias (backend hatchling)
├── uv.lock                    # Árbol de dependencias bloqueado
├── README.md                  # Documentación global del proyecto
└── src/
    └── libreria_egon/
        ├── __init__.py        # Inicializador (API pública v0.4.0)
        ├── bronze.py          # Script de extracción cruda
        ├── silver.py          # Script de transformación y calidad
        └── gold.py            # Script de agregaciones analíticas

---

💻 Configuración en Desarrollo Local

Este proyecto utiliza uv como gestor rápido de dependencias.

1. Instalar dependencias del entorno virtual:

   uv sync

2. Construir el Python Wheel:

   uv run python -m build

   Esto generará el archivo empaquetado en la carpeta de compilación: dist/libreria_egon-0.4.0-py3-none-any.whl

---

Despliegue en Databricks

Para usar tu paquete en producción y orquestar el flujo dentro de un Notebook de Databricks:

1. Subir el Wheel

Sube el archivo .whl generado a tu Workspace de Databricks mediante la interfaz web de Databricks (sección "Catalog" o directo a tu workspace /Workspace/Users/.../libs/).

2. Ejecutar e Instalar en un Notebook

Crea un Notebook y ejecuta las siguientes celdas para instalar, limpiar el caché y ejecutar el ETL secuencialmente:

• Celda 1: Instalar librería

  %pip install --force-reinstall --no-cache-dir /Workspace/Users/TU_CORREO/libs/libreria_egon-0.4.0-py3-none-any.whl

• Celda 2: Limpiar caché del kernel

  dbutils.library.restartPython()

• Celda 3: Orquestar Pipeline Completo

  from libreria_egon import bronze, silver, gold
  
  print("--- Corriendo Bronze ---")
  bronze.run()
  
  print("--- Corriendo Silver ---")
  silver.run()
  
  print("--- Corriendo Gold ---")
  gold.run()
  
  print("¡ETL Completado!")

---

Automatización y Calendarización (Jobs)

Para automatizar la ejecución periódica del pipeline:

1. Dirígete a Workflows en la barra lateral de Databricks.
2. Haz clic en Create Job.
3. Configura una tarea tipo Notebook y apunta al notebook orquestador que creaste en el paso anterior.
4. En el menú derecho, añade un Trigger de tipo Scheduled para calendarizar la ejecución (ej: todos los días a las 2:00 AM).
5. En la sección Notifications, añade alertas de correo en caso de fallos (Failure).

---

Consultas de Comprobación (SQL)

Una vez ejecutado, puedes crear celdas mágicas %sql en Databricks para comprobar el estado de las tablas:

• Comparación de volumen (Embudo de datos):

  SELECT '1. Bronze (Crudos)' as Capa, COUNT(*) as Total_Filas FROM bronze.anime_raw
  UNION ALL
  SELECT '2. Silver (Limpios)' as Capa, COUNT(*) as Total_Filas FROM silver.anime_cleaned
  UNION ALL
  SELECT '3. Gold (Estudios)' as Capa, COUNT(*) as Total_Filas FROM gold.studios_performance;

• Analizar el éxito según el material original (Capa Gold):

  SELECT 
    source AS Material_Original, 
    ROUND(average_score, 2) AS Score_Promedio, 
    animes_produced AS Cantidad_De_Animes
  FROM gold.source_material_success
  ORDER BY average_score DESC;

• Verificar la limpieza de clasificación de edad (Capa Silver):

  SELECT title, rating, rating_clean, has_trailer FROM silver.anime_cleaned LIMIT 10;