Revisa Apache Iceberg completo y reduce deuda P2

[IagoPL]

Objetivo

Cerrar deuda P2 del manual Apache Iceberg y convertirlo en una introducción técnica real al open table format: catálogo, metadata JSON, snapshots, manifests y data/delete files. Spark es el motor pedagógico; Iceberg no depende de Spark.

Capítulos

Capítulo	Problema anterior	Mejora
01 Introducción y arquitectura	Plantilla + ejemplo genérico + código duplicado	Problema del listing de Parquet, jerarquía catalog→metadata→snapshot→manifests→files, OCC, multi-engine, spec v1–v3 vs v4
02 Snapshots y manifests	Idem	Cinco niveles, snapshot ≠ copia física, metadata tables, branches/tags (no Git), format-version, row-level deletes sin “reescribe toda la tabla”
03 Particionado oculto	Idem	days(event_time), transforms, spec como metadata, evolución sin rewrite automático, cardinalidad
04 Evolución de esquema	Idem	Column IDs, rename ≠ drop+add, add/drop/reorder/widening, nested struct/list/map, no reutilizar IDs
05 Spark	Idem	Runtime por línea Spark, catálogo mínimo, writeTo V2, INSERT/overwrite, MERGE/UPDATE/DELETE + extensions, time travel ≠ backup
06 Catálogos	Idem	Catálogo ≠ warehouse; Hadoop/Hive/REST/JDBC; REST como API estándar; commit atómico del puntero; OCC
07 Optimización	Idem	rewrite_data_files (binpack/sort/z-order), rewrite_manifests, expire_snapshots, remove_orphan_files + dry_run
08 Buenas prácticas	Idem	Diseño, escrituras, catálogo, mantenimiento, compatibilidad, observabilidad, recovery

Arquitectura

catalog
  → metadata.json (puntero current)
  → snapshot
  → manifest list
  → manifests
  → data files / delete files

La tabla no se descubre listando el warehouse. No se editan metadata/manifests a mano.

Evolución

• Hidden partitioning: el usuario filtra event_time; Iceberg aplica days(event_time).
• Partition evolution: specs coexisten; no reescribe el histórico solo.
• Schema: IDs de columna; rename conserva identidad; widening según spec.

Spark

• Release verificada: Iceberg 1.11.0 (runtimes Spark 4.1 / 4.0 / 3.5; Spark 3.4 deprecado).
• SparkCatalog + example local (type=hadoop de laboratorio).
• WriterV2: df.writeTo("local.analytics.events").append().
• SQL MERGE/UPDATE/DELETE requieren Iceberg Spark extensions (Spark 3.x). DataFrame mergeInto = Spark 4.0+.
• CALL procedures: nativos en Spark 4.0 (case-sensitive).

Catálogos

OSS: Hadoop, Hive, REST, JDBC. REST es la interfaz estándar motor → implementación. Glue/Snowflake/Databricks/BigQuery no son requisitos.

Mantenimiento

• rewrite_data_files — no existe OPTIMIZE genérico.
• rewrite_manifests — otro nivel.
• expire_snapshots — default ~5 días; respeta branches/tags; main no expira.
• remove_orphan_files — default ~3 días; siempre dry_run primero.

Spec

Release usada para validar: Iceberg 1.11.0 (2026-05-19)
Spec v1, v2, v3: adoptadas
Spec v4: EN DESARROLLO, no adoptada — no se documenta como estable

Evitado: cifrado, geospatial, variant shredding, deletion vectors como receta cotidiana.

Auditoría

Métrica	Antes (#11 en main)	Después
P0	0	0
P1	0	0
P2	71	63
P3	671	679
generic_template	63	55
generic_example	55	47
duplicated_code	71	63
very_short	196	196
high_freshness_risk	141	141
known_outdated_pattern	0	0
Este capitulo profundiza	63	55
Iceberg P2	8	0

Iceberg P2: 8 → 0
P2 global: 71 → 63

Informes solo con npm run docs:audit.

Fuentes oficiales

• iceberg.apache.org
• spec
• docs latest
• releases
• REST Catalog

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 (Transformers) va en una PR independiente.