Revisa Delta Lake completo y reduce deuda P2

[IagoPL]

Objetivo

Cerrar deuda P2 de Delta Lake y convertir el manual en una introducción técnica real al formato/protocolo (Parquet + _delta_log), sin presentarlo como Databricks Lakehouse ni como motor de consultas.

Capítulos

Capítulo	Problema anterior	Mejora
01 Introducción y arquitectura	Plantilla + ejemplo genérico + código duplicado	Problema del data lake, Parquet + transaction log, snapshots, qué no es Delta (ni BD, ni motor, ni Databricks), lakehouse a alto nivel, Kernel, Iceberg solo como “otro protocolo”
02 Tablas Delta	Idem	Path-based format("delta"), catálogo opcional USING delta LOCATION, append/overwrite, particionado intro, enforcement vs evolution (WITH SCHEMA EVOLUTION / withSchemaEvolution(), no mergeSchema=true por defecto), DeltaTable
03 ACID y transaction log	Idem	Writer A / B / lector, OCC, commits/checkpoints, no editar _delta_log, conflictos, reader/writer protocol y table features, storage sin receta cloud
04 MERGE, UPDATE y DELETE	Idem	SQL + DeltaTable upsert de customers, coste/clave/duplicados en source, CDF como feature aparte (no on por defecto, retención = VACUUM)
05 Time travel	Idem	VERSION/TIMESTAMP AS OF, versionAsOf, DESCRIBE HISTORY ≠ leer snapshot, time travel ≠ backup, VACUUM defaults 7d/30d, no RETAIN 0 HOURS como práctica
06 Particionado y optimización	Idem	Small files, cardinalidad, pruning ≠ data skipping, OPTIMIZE/executeCompaction OSS, Z-Order puntual, clustering automático etiquetado como Databricks
07 Streaming	Idem	readStream/writeStream, checkpointLocation ≠ log, exactly-once acotado al sink Delta, skipChangeCommits vs CDF, foreachBatch + MERGE e idempotencia txnAppId/txnVersion
08 Buenas prácticas	Idem	Diseño, escrituras, VACUUM, protocol features, streaming, recovery; object stores a alto nivel; Spark pedagógico vs Flink/Trino/Kernel

Delta Lake OSS

Comprobado contra docs.delta.io (batch, DML, streaming, CDF, concurrency, versioning, optimizations-oss, utilities, Kernel) y delta-io/delta.

Enseñado como OSS: path tables, Spark SQL/DeltaTable, schema enforcement, MERGE/UPDATE/DELETE, time travel, VACUUM, OPTIMIZE + Z-Order, Structured Streaming, CDF opt-in, protocol/table features, skipChangeCommits.

Evitado o etiquetado como Databricks / producto: Databricks Runtime, Databricks SQL, Unity Catalog (producto; se menciona que existe un UC OSS aparte), Predictive Optimization, Auto Optimize como producto, Liquid Clustering automático gestionado. Las keys spark.databricks.delta.* que aparecen en la doc OSS se marcan como config del runtime, no como receta de plataforma.

No se documenta Iceberg en profundidad (siguiente PR).

Transaction log

• Datos habitualmente en Parquet; el estado de tabla lo define _delta_log (JSON + checkpoints).
• Snapshots versionados; lecturas aisladas; OCC al commitear.
• _delta_log es protocolo interno: no editar/borrar commits a mano.
• Activar table features puede subir reader/writer protocol y romper clientes viejos.

Operaciones

• UPDATE / DELETE / MERGE reescriben ficheros; la condición y la clave importan; duplicados en source son un problema.
• CDF ≠ MERGE; hay que habilitarlo; no es auditoría permanente.
• Time travel lee un snapshot; HISTORY lista commits; VACUUM borra data files (default 7 días) y el log se poda a ~30 días.
• OPTIMIZE OSS; Z-Order no “siempre mejora todo”.

Streaming

• writeStream + checkpointLocation; readStream con startingVersion / rate limits.
• Exactly-once del sink Delta, no de side effects externos.
• Updates/deletes en el source: el reader append-only no aplica cambios de fila; skipChangeCommits o CDF.
• Checkpoint del stream ≠ _delta_log.

Auditoría

Métrica	Antes (#10 en main)	Después
P0	0	0
P1	0	0
P2	79	71
P3	663	671
generic_template	71	63
generic_example	63	55
duplicated_code	79	71
very_short	196	196
high_freshness_risk	141	141
known_outdated_pattern	0	0
Este capitulo profundiza	71	63
Delta Lake P2	8	0

Delta Lake P2: 8 → 0
P2 global: 79 → 71

Los 8 capítulos quedan en P3, sin flags de plantilla/ejemplo/duplicado. Informes solo con npm run docs:audit.

Fuentes oficiales

• docs.delta.io
• github.com/delta-io/delta

Release estable usada para verificar compatibilidad: Delta Lake 4.4.0 (2026-08-20; Spark 4.0.1 / 4.1 / 4.2). No se copia la instalación 4.0.0 del quickstart. El manual no fija versión en cada capítulo.

Validación

Local, todo OK:

npm ci
npm run docs:audit
npm run docs:build
CI_VALIDATE_LINKS=true npm run docs:build
npm run docs:report

No fusionar este PR. El siguiente bloque (Iceberg) va en una PR independiente.