🔗 Entity Resolution

🐤 DuckDB: El motor de datos detrás del sistema

🚀 ¿Qué es DuckDB?

DuckDB es un motor de base de datos analítico (OLAP), embebido y de código abierto, diseñado para ejecutar consultas SQL rápidas sobre grandes volúmenes de datos en una sola máquina.

Es conocido como el "SQLite de los datos analíticos" porque:

✅ Sin configuración - Funciona con pip install duckdb
✅ Procesa en memoria - Acelera consultas hasta 100x
✅ SQL completo - Soporta joins, window functions, subconsultas
✅ Integración con Python - Se convierte a Pandas DataFrames fácilmente

🔧 ¿Cómo usamos DuckDB en este sistema?

Almacenamiento: Todas las tablas (raw_records, normalized_records, pairs_evaluated, golden_records) están en DuckDB
Normalización: Se ejecutan consultas SQL para limpiar y transformar datos
Evaluación de pares: DuckDB compara registros usando SQL optimizado
Generación Golden: DuckDB crea registros maestros mediante consultas agregadas
API REST: FastAPI se conecta a DuckDB para servir datos al frontend

                🔥 EJEMPLO DE CÓDIGO EN ESTE SISTEMA:

                # Conectar a DuckDB

                conn = duckdb.connect("entity_resolution.db")

                # Consulta SQL en DuckDB

                conn.execute("""

                  INSERT INTO normalized_records

                  SELECT id, LOWER(TRIM(nombre)), LOWER(TRIM(email))

                  FROM raw_records

                """)

                # Convertir a Pandas DataFrame

                df = conn.execute("SELECT * FROM golden_records").df()

📊 Ventajas de DuckDB en este sistema

⚡ Velocidad: Procesa 100,000 registros en ~76 segundos
💾 Memoria eficiente: Usa menos RAM que Pandas para grandes datasets
🔍 SQL nativo: Consultas complejas sin librerías adicionales
🔗 Integración: Se conecta directamente con FastAPI y Python
📦 Ligero: Sin necesidad de servidores externos o configuraciones

🔄 Comparativa: DuckDB en este sistema vs otras herramientas

Característica	🐤 DuckDB (este sistema)	🐼 Pandas	🔥 PySpark
Rendimiento (100k registros)	✅ 76 segundos	⚠️ ~120 segundos	✅ ~80 segundos
Rendimiento (100M registros)	⚠️ Bueno	❌ No recomendado	✅ Excelente
Uso de memoria	✅ Bajo	❌ Alto	⚠️ Alto
SQL nativo	✅ Sí	❌ No	✅ Sí
Complejidad	✅ Baja	✅ Baja	❌ Alta
Costo	✅ Gratis	✅ Gratis	⚠️ Caro (cluster)
Ideal para	✅ Datos locales	✅ Análisis exploratorio	✅ Big Data

📌 Conclusión: DuckDB es la opción perfecta para este sistema porque es rápido, sencillo y eficiente para procesar hasta 100 millones de registros en una sola máquina.

🔍 ¿Dónde se usa DuckDB en el mundo real?

📊 Data Science: Análisis exploratorio en Jupyter Notebooks
🔄 ETL/ELT: Procesamiento de datos en pipelines locales
📈 Dashboards: Backend de dashboards con grandes volúmenes de datos
🧪 Investigación: Análisis de datos académicos y científicos
🏢 Empresas: Shopify, IBM, y muchas empresas lo usan para análisis interno

🔍 ¿Qué es Entity Resolution?

Entity Resolution (también conocido como Record Linkage o Deduplicación) es el proceso de identificar y fusionar registros que se refieren a la misma entidad del mundo real (persona, empresa, producto, etc.) dentro de una o más bases de datos.

El objetivo es crear un "Golden Record" (Registro Maestro) que consolide toda la información disponible sobre una entidad, eliminando duplicados y contradicciones.

⚙️ ¿Cómo funciona este sistema?

El sistema procesa los datos en 3 fases principales:

1. Normalización: Limpia y estandariza los datos (mayúsculas, espacios, formato de teléfonos, etc.)
2. Evaluación de Pares: Compara todos los registros entre sí y calcula una puntuación de similitud basada en:
- Nombre (40% de peso)
- Email (30% de peso)
- Ciudad (20% de peso)
- Teléfono (10% de peso)
3. Generación Golden: Agrupa los registros que superan el umbral de similitud y crea un Registro Maestro con la mejor información de cada grupo.

                🧩 EJEMPLO DE SIMILITUD:

                Juan Carlos Perez (ID:1) vs Juan C. Perez (ID:2) = 30% (mismo teléfono)

                → ¡Match! → Golden Record: "Juan Carlos Perez" con 3 registros fusionados

🛠️ Tecnologías utilizadas

🐤 DuckDB: Motor de base de datos analítico, embebido en Python. Procesa millones de registros en memoria a alta velocidad.
⚡ FastAPI: Framework web para construir APIs REST de alto rendimiento con Python.
☁️ Cloudflare Workers: Plataforma serverless para ejecutar código en el edge (borde de la red).
🗄️ D1 SQLite: Base de datos SQLite nativa de Cloudflare para Workers.
📊 Chart.js: Librería JavaScript para crear gráficos interactivos en el frontend.

🚀 Deploy en Cloudflare:

🌐 Frontend: https://duck-antonio.pages.dev
⚡ API: https://er-api.vencedores4f.workers.dev

💼 Ejemplos de aplicación

🏦 Banca y Finanzas: Consolidar clientes que tienen múltiples cuentas con diferentes datos de contacto.
🏥 Salud: Unificar historiales médicos de pacientes en diferentes clínicas.
🛒 E-commerce: Identificar clientes duplicados que compran con diferentes emails o teléfonos.
📊 CRM: Limpiar bases de datos de contactos eliminando duplicados.
🏛️ Gobierno: Consolidar registros ciudadanos en diferentes bases de datos.
📦 Logística: Unificar direcciones de entrega de clientes.

📊 Ejemplo práctico: Datos de prueba

Con los 10 registros cargados en este sistema, el pipeline generó:

6 Matches (pares con similitud ≥ 25%)
3 Possibles (pares con similitud entre 10% y 25%)
4 Golden Records (registros maestros fusionando 9 registros originales)

Golden ID	Nombre Maestro	Teléfono	Ciudad	Registros fusionados
1	juan carlos perez	5550199	santiago	3
2	maría gonzález	5551234	valparaíso	2
3	pedro lópez	5555678	concepción	2
4	carlos ruiz	5559012	la serena	2

⚡ Procesado en 12 segundos en Cloudflare Workers.

🏗️ Arquitectura del sistema

                📄 CSV → 📤 Upload → 🗄️ raw_records → 🔧 normalized_records → 🔗 pairs_evaluated → ⭐ golden_records
                
                🔄 FLUJO: 

                [1] Carga CSV → [2] Normalización → [3] Evaluación de pares → [4] Generación Golden → [5] Dashboard

Diagrama de flujo:

📄 CSV

→

🔧 Normalizar

→

🔗 Evaluar

→

⭐ Golden

→

📊 Dashboard

🚀 Futuras mejoras

🔍 Búsqueda avanzada: Buscar registros por nombre, email o ciudad
📤 Exportar datos: Descargar Golden Records en CSV/Excel
📊 Más gráficos: Distribución por ciudad, evolución temporal
🔔 Notificaciones: Alertas cuando se detectan duplicados
🤖 Machine Learning: Usar ML para mejorar la detección de duplicados
🌐 API pública: Endpoints abiertos para integración con otros sistemas

🔗 Entity Resolution

📄 Registros Crudos (Raw Records)

🔧 Registros Normalizados

📋 Pares Evaluados

✅ Matches

🔶 Posibles

❌ No Matches

⭐ Golden Records

📊 Panel de Gráficos

📊 Distribución de Pares Evaluados

📊 Resumen de Datos

⭐ Golden Records por Confianza

⏱️ Progreso del Pipeline

✏️ Insertar Registro Manual

📚 Documentación del Sistema