Un catálogo que puedes probar

Unos 36 minutos de lectura, con 11 ejemplos en 12 secciones.

Edición 2026.11.31 Ejemplos verificados el 19 de nov de 2026 108 de 108 ejemplos pasan Qué ha cambiado

Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros

Traducido del libro en inglés, edición 2026.11.31. Lee el original

Al final de este capítulo podrás mantener los metadatos del catálogo como código. Cada tabla tendrá un responsable y un dominio, y cada columna una descripción y una clasificación, en un archivo que tu equipo revisa. El archivo está indexado por clave para que un cambio de nombre no pueda perder nada, se escribe en el catálogo Iceberg y lo verifica una prueba que falla cuando falta algo. También harás que un modelo local redacte borradores de descripciones y clasificaciones, y medirás con qué frecuencia sus borradores son erróneos antes de que nadie los acepte.

El catálogo de la plataforma tiene tres problemas. Su almacén, un catálogo Iceberg mantenido por una plataforma de aprendizaje en línea cuyas canalizaciones siguen añadiendo tablas, contiene ocho tablas de origen en espacios de nombres que llevan el nombre de los equipos que las gestionan, como crm.learners y support.tickets. Sus canalizaciones construyen tablas de informes a partir de estas y siguen creando tablas, y nada indica quién es el responsable de marketing.audience, la lista de estudiantes a quienes marketing puede enviar correos, ni si ai.review_corpus, el texto que lee el asistente del curso de la plataforma, contiene datos personales. Una columna renombrada en un cambio de esquema puede perder su clasificación sin que nadie lo note. Y cada tabla que añade una canalización necesita una descripción y una clasificación para cada una de sus columnas, escritas a mano, lo cual es tan lento que los equipos lo omiten.

El capítulo 1 construyó una versión preliminar de toda la plataforma gobernada. Este capítulo consolida su catálogo.

Los ejemplos del capítulo usan cinco de los módulos compartidos del libro. lib.catalog.open_catalog construye un catálogo nuevo con las tablas de la plataforma en una carpeta temporal, sobre el catálogo SQL de PyIceberg con SQLite, que la documentación de PyIceberg recomienda solo para exploración y desarrollo (configuración de PyIceberg). lib.pipelines.run ejecuta una de las canalizaciones de la plataforma y escribe su salida en el catálogo. lib.warehouse.connect abre DuckDB sobre las tablas del catálogo, de modo que una consulta puede nombrarlas como lo hace la plataforma, y lib.policy evalúa las políticas de acceso de la plataforma, que el capítulo 5 escribe. Y lib.metadata, que este capítulo va construyendo, carga los metadatos de la plataforma, los escribe en el catálogo y verifica el catálogo contra ellos.

Guarda los metadatos en un archivo revisado

Último cambio en la edición 2026.11.27

Los metadatos de un catálogo son lo que sabes de cada tabla que los datos no dicen: quién es su responsable, a qué parte del negocio pertenece, qué contiene y cómo debe protegerse cada columna. Los servidores de catálogo guardan esto en su propia base de datos y lo editan en una página web. Eso funciona para navegar, pero un cambio hecho ahí es invisible para la revisión de código, y ninguna prueba puede decir si el catálogo está completo. Guardar los metadatos en un archivo del repositorio, junto a los pipelines que crean las tablas, hace que cada cambio sea un diff que alguien aprueba, y da a una prueba algo con qué comparar el catálogo.

El archivo de la plataforma es governance/metadata.toml. Para cada tabla registra:

  • un propietario, el equipo responsable de la tabla, nunca una persona;
  • un dominio, la parte del negocio a la que pertenece la tabla;
  • una descripción de la tabla;
  • para cada columna, su nombre, una descripción y una clasificación.

Una clasificación es uno de cuatro valores, ordenados de menos a más protegido:

Clasificación Significado En la plataforma
public Puede mostrarse a cualquiera fuera de la plataforma El título de un curso
internal Para el personal de la plataforma, y no identifica por sí solo a una persona Cuándo empezó una inscripción
personal Identifica a una persona o dice algo sobre ella El correo de un alumno, o un texto que escribió
sensitive Datos cuya filtración perjudicaría directamente a alguien Un número de tarjeta, la cuenta bancaria de un instructor

El orden importa: cuando una columna se construye a partir de varias otras, como suelen serlo las columnas de salida de un pipeline, gana la clasificación más estricta, y lib.metadata.stricter la devuelve. Cargado y contado, el archivo muestra lo que cubre:

metadata-model.py Python 3.12.15 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Loads the metadata file and counts what it describes, then prints four of the learners table's columns, looked up byfield ID. The prose's point rests on the `country` and `city` lines, whose descriptions give the reason for each classification."""from collections import Counterfrom lib import metadatadescribed = metadata.load()                      # governance/metadata.tomlcolumns = [column for table in described.values() for column in table.columns.values()]print("tables described:", len(described))print("columns described:", len(columns))counts = Counter(column.classification for column in columns)for level in metadata.LEVELS:    print(f"columns classified {level}:", counts[level])owners = sorted({table.owner for table in described.values()})print("teams that own tables:", len(owners))print("owners:", ", ".join(owners))learners = described["crm.learners"]print("crm.learners owner:", learners.owner)print("crm.learners domain:", learners.domain)for field_id in (1, 3, 5, 6):                    # field IDs, which the file keys columns by, not positions in the table    column = learners.columns[field_id]    print(f"crm.learners field {field_id}:", column.name, "|", column.classification, "|", column.description)
Salidapython metadata-model.py
tables described: 10
columns described: 77
columns classified public: 6
columns classified internal: 57
columns classified personal: 12
columns classified sensitive: 2
teams that own tables: 5
owners: team-analytics, team-billing, team-crm, team-learning, team-support
crm.learners owner: team-crm
crm.learners domain: crm
crm.learners field 1: learner_id | internal | The learner's ID, which the platform's other tables use for the learner. Identifies a person through this table's personal columns.
crm.learners field 3: email | personal | The email the learner signs in with.
crm.learners field 5: country | internal | The learner's country, as an ISO 3166 two-letter code.
crm.learners field 6: city | personal | The learner's city. Identifying together with date of birth.

La mayoría de las columnas son internal, porque la mayor parte de un almacén son identificadores, fechas y conteos: 57 de sus 77 columnas lo son. Las columnas protegidas son pocas. De las columnas del archivo, 12 son personal, y sensitive guarda el número de tarjeta en billing.payments y la cuenta de pagos en crm.instructors. El archivo cubre las ocho tablas de origen y las dos tablas de informes en las que confían los analistas de la plataforma, y cada tabla pertenece a uno de 5 equipos propietarios. La idea es que cada descripción recoja la razón de su clasificación. country es internal porque un país por sí solo no identifica a nadie, mientras que city es personal porque, como dice su descripción, identifica a un alumno junto con su fecha de nacimiento.

Los cuatro valores y la regla de un solo propietario son nuestros, no de un estándar. El Open Data Contract Standard (ODCS) registra un dominio, un propietario como un rol de texto libre dentro de un equipo, y una clasificación de texto libre (ODCS v3.2.0), y su esquema JSON acepta cualquier cadena como clasificación (esquema JSON de ODCS). Los servidores de catálogo también difieren. DataHub tipifica sus propietarios (tipos de propiedad), y permite que un activo pertenezca a un solo dominio a la vez (dominios). Clasifica columnas con términos de glosario (glosario de negocio).

OpenMetadata permite que un propietario sea un equipo o varios usuarios, una regla que se aplica a nivel de instancia y que viene activada por defecto (propiedad de datos). Sus clasificaciones son un vocabulario controlado de etiquetas (clasificación), como PII.Sensitive (etiquetas PII). En Unity Catalog de Databricks, cada objeto tiene un propietario, que posee todos los privilegios sobre él (privilegios). Las tablas y las columnas llevan etiquetas (etiquetas), y una etiqueta gobernada toma valores "solo de un conjunto predefinido de valores permitidos" (etiquetas gobernadas). Un archivo como el de la plataforma se traslada a cada uno de ellos. Ninguno de estos documentos describe la comprobación que hace la prueba de este capítulo: un equipo, nunca una persona, como propietario de cada tabla, y una de las cuatro clasificaciones en cada columna.

Regla práctica: Guarda los propietarios, dominios, descripciones y clasificaciones en un archivo del repositorio, revisado igual que los pipelines. Usa una lista cerrada de clasificaciones, ordenada según cuánta protección necesita cada una, y un único equipo propietario por tabla. Si tu organización edita los metadatos en la página web de un servidor de catálogo, haz que una de las dos partes sea la fuente y genera la otra a partir de ella; dos fuentes que aceptan ediciones se desvían entre sí.

Indexa los metadatos de columna por ID de campo

Último cambio en la edición 2026.11.27

El archivo de metadatos de la plataforma indexa cada columna por un número, no por su nombre, porque los nombres cambian. Iceberg asigna a cada columna un ID de campo, un entero único dentro del esquema de la tabla, y la especificación exige que un cambio de nombre conserve ese ID: «Renaming an existing field must change the name, but not the field ID» (especificación de tablas de Iceberg). Los lectores también encuentran los valores por ese ID, ya que Iceberg selecciona las columnas de un archivo de datos por ID de campo, de modo que una columna renombrada sigue leyendo los archivos escritos antes del cambio (especificación de tablas de Iceberg). Los metadatos indexados por nombre no tienen de qué asirse: tras un cambio de nombre, el nombre antiguo no apunta a nada y el nombre nuevo no tiene entrada.

El equipo de CRM de la plataforma quiere que crm.learners.email se llame contact_email, para dejar sitio a un correo de trabajo. Preparado en un catálogo de pruebas, el cambio de nombre muestra lo que pierde una copia indexada por nombre. La columna se busca en el archivo de metadatos, indexado por ID de campo, y en una copia indexada por nombre, como suele ser una hoja de cálculo de columnas:

rename-orphans-name-keys.py Python 3.12.15 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 Superado
"""Renames crm.learners.email in a scratch catalog, then looks the column up by field ID and by name. The prose's pointrests on the two classification lines, which disagree, and on the check's `renamed from email` line."""from lib import catalog, metadata, policyplatform = catalog.open_catalog(["crm.learners"])described = metadata.load()by_id = described["crm.learners"].columns                                    # the book's metadata: keyed by field IDby_name = {column.name: column.classification for column in by_id.values()}  # a spreadsheet's: keyed by namelearners = platform.load_table("crm.learners")with learners.update_schema() as update:    update.rename_column("email", "contact_email")                           # renames in place: the field ID staysfield = learners.schema().find_field("contact_email")print("contact_email field ID:", field.field_id)values = learners.scan(selected_fields=("contact_email",)).to_arrow().column("contact_email")print("values read under the new name:", f"{len(values) - values.null_count:,} of {len(values):,}")print("classification of contact_email, looked up by name:", by_name.get("contact_email"))print("classification of contact_email, looked up by field ID:", by_id[field.field_id].classification)names = {f.name for f in learners.schema().fields}print("name-keyed entries that match no column:", ", ".join(sorted(set(by_name) - names)))for problem in metadata.problems(platform, described):    print("check:", problem)# The policies read classifications by name, generated from the file, which still says email.decision = policy.decide(policy.request("agent-a01", "crm.learners", ["contact_email"]))print("a support agent reading contact_email sees it as:", decision["column_masks"].get("contact_email", "shown"))
Salidapython rename-orphans-name-keys.py
contact_email field ID: 3
values read under the new name: 5,000 of 5,000
classification of contact_email, looked up by name: None
classification of contact_email, looked up by field ID: personal
name-keyed entries that match no column: email
check: crm.learners.contact_email: renamed from email since it was reviewed
a support agent reading contact_email sees it as: redact

Las dos búsquedas no coinciden, y solo la que está indexada por ID de campo sabe que la columna es la misma. El cambio de nombre conservó el ID de campo 3, y 5,000 of 5,000 valores llegaron con el nuevo nombre. Indexada por nombre, contact_email no tiene clasificación, y la entrada de email no coincide con ninguna columna. Indexada por ID de campo, la columna sigue siendo personal. Una comprobación construida sobre la copia indexada por nombre informaría de una columna sin clasificar y no advertiría que una columna clasificada había desaparecido.

El archivo indexado por ID sí detecta el cambio de nombre, y lib.metadata.problems, la comprobación en la que se apoya este capítulo, lo informa: contact_email: renamed from email since it was reviewed. Que los datos sobrevivan a un cambio de nombre no significa que el cambio sea inocuo: el SQL que nombra email se rompe, y también cualquier sistema que conozca las columnas solo por su nombre. Las políticas de acceso de la plataforma, que escribe el capítulo 5, reciben por nombre las columnas que lee una consulta, así que leen las clasificaciones de una vista indexada por nombre que lib.policy genera a partir de este archivo. Cuando la comprobación falla, alguien actualiza el nombre en el archivo, vuelve a leer la descripción y la vista generada se actualiza en consecuencia. Mientras tanto, la vista no tiene entrada para contact_email, y las políticas tratan una columna que no encuentran como sensitive. Un agente de soporte, que sí ve todas las demás columnas personales de crm.learners, recibe contact_email como redact: el cambio de nombre falla en modo seguro, y soporte lo nota primero.

Regla práctica: Indexa los metadatos de columna por ID de campo, con el nombre al lado para las personas. Trata un nombre que ya no coincide como motivo para revisar la descripción de la columna, no como una columna nueva. Cuando un sistema conozca las columnas solo por nombre, genera su vista indexada por nombre a partir del archivo indexado por ID, nunca la mantengas a mano.

Escribe las descripciones en el esquema de la tabla

Último cambio en la edición 2026.11.27

El archivo de metadatos es donde se revisan los metadatos de la plataforma. Sin embargo, las personas y las herramientas que leen una tabla buscan en el catálogo, así que parte de los metadatos tiene que copiarse allí. La pregunta es dónde debe ir cada dato en el catálogo, y Iceberg responde en parte: cada columna puede llevar un doc, un comentario opcional que viaja con el esquema (especificación de tablas de Iceberg). Una tabla también tiene propiedades, un mapa de cadenas, pero la especificación dice que ese mapa "se usa para controlar la configuración que afecta a la lectura y la escritura y no está pensado para metadatos arbitrarios".

Así que seguimos la especificación todo lo que podemos. Las descripciones de las columnas van en doc, y las clasificaciones se quedan en el archivo, donde las políticas y las comprobaciones las leen. El propietario y el dominio van en dos propiedades de la tabla, como un puntero para las herramientas que solo leen la tabla, de modo que cualquiera que tenga una tabla y no un repositorio pueda encontrar al equipo al que preguntar. Esa última decisión va en contra de la intención declarada de la especificación, y la mantenemos solo con esos dos valores breves.

La respuesta propia del proyecto Iceberg es un canal aparte. La especificación del catálogo REST de Iceberg 1.12.0 añade labels, la titularidad (quién es responsable) o clasificación que un catálogo devuelve junto con una tabla, por tabla y por ID de campo, y que se mantiene fuera de las propiedades a propósito (especificación del catálogo REST). El cambio llegó con la solicitud de cambios 15750. El cliente REST de PyIceberg 0.12.0 no las lee (código fuente).

lib.metadata.apply hace la copia. Para cada tabla que describe el archivo y que contiene el catálogo, escribe cada descripción en el doc de su columna, y el propietario y el dominio en las propiedades, cambiando solo lo que difiere. Frente a un catálogo nuevo con las ocho tablas de origen de la plataforma, apply muestra qué cambia:

apply-metadata.py Python 3.12.15 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Writes the metadata file into a fresh catalog of the eight source tables, then applies it again. The prose's point restson the second `tables changed` line, which is zero: applying a file the catalog already matches writes nothing."""from lib import catalog, metadataplatform = catalog.open_catalog()                # all eight source tables, with no metadata yetdescribed = metadata.load()print("crm.learners schema ID before:", platform.load_table("crm.learners").schema().schema_id)print("tables changed:", len(metadata.apply(platform, described)))learners = platform.load_table("crm.learners")print("crm.learners schema ID after:", learners.schema().schema_id)print("email's doc, in the Iceberg schema:", learners.schema().find_field("email").doc)scanned = learners.scan(selected_fields=("email",), limit=1).to_arrow()   # one row is enough: the schema comes back with it# Arrow keeps an Iceberg column's doc in the field's metadata, under the bytes key b"doc".print("email's doc, in a scan's Arrow schema:", scanned.schema.field("email").metadata[b"doc"].decode())print("crm.learners properties:", ", ".join(f"{k}={v}" for k, v in sorted(learners.properties.items())))print("tables changed by applying again:", len(metadata.apply(platform, described)))
Salidapython apply-metadata.py
crm.learners schema ID before: 0
tables changed: 8
crm.learners schema ID after: 1
email's doc, in the Iceberg schema: The email the learner signs in with.
email's doc, in a scan's Arrow schema: The email the learner signs in with.
crm.learners properties: domain=crm, owner=team-crm
tables changed by applying again: 0

Aplicar el archivo escribe los metadatos en el catálogo, y aplicarlo de nuevo no escribe nada, así que apply puede ejecutarse en cada fusión. La primera ejecución cambió 8 tablas. La descripción de email está ahora en el esquema de Iceberg y en el esquema de Arrow que devuelve un escaneo, así que el código que lee la tabla a través de PyIceberg la obtiene junto con los datos, sin saber que el archivo existe. Las propiedades contienen owner=team-crm y domain=crm. Una segunda ejecución cambió 0 tablas. El ID de esquema de crm.learners pasó de 0 a 1, aunque no cambió el ID, el nombre ni el tipo de ninguna columna, que es el tema de la siguiente subsección.

Una edición de descripción es un cambio de esquema

Último cambio en la edición 2026.11.27

La especificación de Iceberg asigna a cada cambio de esquema un nuevo esquema con su propio ID, que pasa a ser el esquema actual de la tabla y se añade a la lista de esquemas que la tabla conserva (especificación de tablas de Iceberg). En PyIceberg 0.12.0, editar únicamente la descripción de una columna doc cuenta como un cambio de este tipo. Cambia solo la descripción de learning.reviews.body, después de que lib.metadata.apply haya escrito las descripciones de la plataforma, y observa el ID del esquema:

doc-edit-schema-id.py Python 3.12.15 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Changes one column's description after the metadata is applied, then compares schema IDs with field IDs, names andtypes. The prose's point rests on the schema ID changing while the shape stays the same, which the assert checks."""from lib import catalog, metadataplatform = catalog.open_catalog(["learning.reviews"])metadata.apply(platform, metadata.load())    # the platform's descriptions go in first, so the edit below is the only changereviews = platform.load_table("learning.reviews")before = reviews.schema()print("schema ID before the edit:", before.schema_id)with reviews.update_schema() as update:                                        # change one description, nothing else    update.update_column("body", doc="The review's text, as the learner wrote it. May hold names and emails.")after = reviews.schema()assert metadata.shape(before) == metadata.shape(after), "a doc edit changed a field ID, name or type"print("schema ID after the edit:", after.schema_id)print("schemas the table keeps:", len(reviews.metadata.schemas))print("schema ID changed:", before.schema_id != after.schema_id)print("field IDs, names or types changed:", metadata.shape(before) != metadata.shape(after))
Salidapython doc-edit-schema-id.py
schema ID before the edit: 1
schema ID after the edit: 2
schemas the table keeps: 3
schema ID changed: True
field IDs, names or types changed: False

Una edición de descripción cambia el ID del esquema y nada que una revisión deba comparar. El ID pasó de 1 a 2, y la tabla conserva 3 esquemas: el original, el que escribió apply y este. Los IDs de campo, los nombres y los tipos son los mismos, algo que comprueba lib.metadata.shape. Una regla que exija una nueva clasificación cada vez que cambie el ID del esquema se activaría en cada edición de descripción, y los equipos acabarían ignorando una comprobación que se activa sin motivo.

Regla práctica: escribe las descripciones de las columnas en el doc de Iceberg, para que todas las personas que lean la tabla las vean, y conserva las clasificaciones en el archivo revisado. Pon en las propiedades de la tabla no más que un propietario y un dominio, y explica en tu código por qué. Para decidir si un cambio de esquema necesita revisión, compara los IDs de campo, los nombres y los tipos, nunca los IDs de esquema.

Prueba el catálogo contra los metadatos

Último cambio en la edición 2026.11.27

Con los metadatos aplicados al catálogo, la pregunta pendiente es si el archivo cubre todo lo que contiene el catálogo. Una prueba responde a ella, y tiene que partir del catálogo: una comprobación que recorre el archivo solo encuentra problemas en las tablas que alguien ya describió. lib.metadata.problems enumera cada tabla de cada espacio de nombres del catálogo, y señala una tabla sin entrada o sin propietario, una columna cuyo ID de campo no tiene clasificación, una clasificación que no es una de las cuatro, y una columna renombrada desde su última revisión.

En la plataforma, los huecos vienen de los pipelines. Cada pipeline es un create table ... as select ... en pipelines/, y ejecutarlo crea una tabla. Ejecuta los cuatro pipelines sobre un catálogo nuevo y comprueba el resultado, y aparecen los huecos:

metadata-gaps.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · sqlglot 30.33.0 Superado
"""Runs the platform's four pipelines on a fresh catalog, then checks every table in it against the metadata file. Theprose's point rests on the `problems found` line and the two `no metadata` lines that follow it."""from lib import catalog, metadata, pipelinesplatform = catalog.open_catalog()for name in ("course_performance", "learner_activity", "marketing_audience", "review_corpus"):   # each one a file in pipelines/    print("pipeline output:", pipelines.run(platform, name))# The eight source tables plus the four outputs the pipelines just created.tables = [f"{namespace}.{name}" for (namespace,) in platform.list_namespaces() for _, name in platform.list_tables(namespace)]print("tables in the catalog:", len(tables))found = metadata.problems(platform, metadata.load())print("problems found:", len(found))for problem in found:    print("problem:", problem)
Salidapython metadata-gaps.py
pipeline output: analytics.course_performance
pipeline output: analytics.learner_activity
pipeline output: marketing.audience
pipeline output: ai.review_corpus
tables in the catalog: 12
problems found: 2
problem: ai.review_corpus: no metadata
problem: marketing.audience: no metadata

Las dos tablas que fallan son las que más importan. El catálogo contiene 12 tablas, y la comprobación encuentra 2 problemas: ai.review_corpus: no metadata y marketing.audience: no metadata. Las dos tablas analíticas pasan, porque el archivo las describe, con IDs de campo que coinciden con el orden de sus listas de select.

marketing.audience copia nombres y correos electrónicos de los estudiantes desde crm.learners, y ai.review_corpus copia el texto libre de las reseñas, así que ambas contienen datos personales, y ninguna tiene un propietario que responda por ellos. Mientras alguien no las clasifique, la política de acceso de la plataforma, governance/policies/access.rego, trata como sensitive toda columna para la que no encuentra una clasificación, de modo que el hueco falla de forma segura (cerrada) y no abierta. El capítulo 4 propone sus clasificaciones a partir del linaje, de las columnas de las que se construyó cada columna de salida.

La prueba se reduce entonces a una sola línea, assert not metadata.problems(catalog, metadata.load()), que se ejecuta cada vez que cambia el catálogo: en la solicitud de cambios que añade un pipeline, la que configura el capítulo 10, y de forma programada contra el catálogo de producción, lo que detecta las tablas creadas fuera de cualquier solicitud de cambios.

Regla práctica: Recorre el catálogo, no el archivo de metadatos, para que aparezca una tabla que nadie describió. Haz fallar la prueba ante cualquier tabla sin propietario y ante cualquier columna sin una de las cuatro clasificaciones, y nunca asignes a una clasificación faltante otro valor que no sea el más protegido. Un pipeline que crea una tabla se entrega junto con los metadatos de esa tabla, en la misma solicitud de cambios.

Detecta los cambios de esquema antes de que los metadatos queden desactualizados

Último cambio en la edición 2026.11.27

La prueba contra el catálogo detecta las tablas nuevas. Las tablas también cambian por debajo de sus metadatos, y cada tipo de cambio requiere su propia respuesta. Un cambio de nombre conserva el ID de campo, así que la entrada sobrevive, pero su descripción puede haber quedado incorrecta. Una columna añadida recibe un ID de campo que nadie ha revisado. Una columna eliminada deja una entrada que no describe nada. Y eliminar una columna y añadir otra con el mismo nombre no restaura la columna anterior: la especificación asigna a cada campo añadido un ID nuevo (especificación de tablas de Iceberg), así que la columna vuelta a añadir es otra columna distinta.

Los cambios de esquema son lo bastante frecuentes para que esto importe. En un estudio de diez aplicaciones de código abierto, "el 80% de los cambios de esquema ocurrieron en el 20-30% de las tablas" (Qiu, Li y Su, 2013). Ese estudio abarca bases de datos de aplicaciones, no almacenes de datos. Si los cambios de un almacén se concentran de la misma manera, sus tablas más activas son las primeras en quedar con metadatos desactualizados.

Dos cambios preparados en crm.learners muestran que ambas comprobaciones funcionan: uno añade preferred_name, con una descripción pero sin clasificación, y el otro elimina country y lo vuelve a añadir. problems y lib.metadata.dropped: la segunda informa de las entradas cuyo ID de campo la tabla ya no tiene, y lee los valores de la columna eliminada tal como lo hace el viaje en el tiempo de Iceberg, indicando una instantánea:

schema-changes-checked.py Python 3.12.15 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Adds an unreviewed column, drops a column and adds it back, then runs both checks and reads the dropped values by timetravel. The prose's point rests on the two field IDs, and on the time-travel line, which still returns every country."""from pyiceberg.types import StringTypefrom lib import catalog, metadataplatform = catalog.open_catalog(["crm.learners"])described = metadata.load()learners = platform.load_table("crm.learners")written = learners.current_snapshot()                                        # the snapshot the rows were written inprint("country field ID, before it was dropped:", learners.schema().find_field("country").field_id)with learners.update_schema() as update:                                     # a column nobody has reviewed    update.add_column("preferred_name", StringType(), doc="What the learner asks to be called.")with learners.update_schema() as update:                                     # drop a column, then add it back    update.delete_column("country")with learners.update_schema() as update:    update.add_column("country", StringType())                               # an added field gets a new ID, never the old onecountry = learners.schema().find_field("country")print("country field ID, after it was added back:", country.field_id)values = learners.scan(selected_fields=("country",)).to_arrow().column("country")print("country values after it was added back:", f"{values.null_count:,} nulls of {len(values):,}")# Minus the one snapshot that wrote the rows: the schema changes wrote none of their own.print("snapshots the schema changes wrote:", len(learners.metadata.snapshots) - 1)old = learners.scan(snapshot_id=written.snapshot_id, selected_fields=("country",)).to_arrow().column("country")print("country values, read by time travel to that snapshot:", f"{len(old) - old.null_count:,} of {len(old):,}")for problem in metadata.problems(platform, described):    print("problems():", problem)for problem in metadata.dropped(platform, described):    print("dropped():", problem)
Salidapython schema-changes-checked.py
country field ID, before it was dropped: 5
country field ID, after it was added back: 17
country values after it was added back: 5,000 nulls of 5,000
snapshots the schema changes wrote: 0
country values, read by time travel to that snapshot: 5,000 of 5,000
problems(): crm.learners.preferred_name: not classified
problems(): crm.learners.country: not classified
dropped(): crm.learners.country: field 5 is described but no longer in the table

Una columna vuelta a añadir es una columna nueva: country volvió como el campo 17, no como 5, y una lectura normal, que usa el esquema actual donde el campo antiguo ya no existe, devuelve 5,000 nulls of 5,000 para ella. Ambas columnas añadidas están sin clasificar, y la descripción dada a preferred_name no cuenta: una descripción es un doc en el esquema, y una clasificación es una línea revisada en el archivo.

Los países de los estudiantes no han desaparecido. Un cambio de esquema no escribe ninguna instantánea (0 aquí), así que la instantánea actual de la tabla sigue siendo aquella en la que se escribieron sus filas. Una instantánea registra el ID del esquema actual de la tabla en el momento de su creación (especificación de tablas de Iceberg), y en PyIceberg 0.12.0, una lectura que indica una instantánea usa ese esquema. Por tanto, el viaje en el tiempo a esa instantánea devuelve 5,000 of 5,000 países. Eliminar una columna no borra ninguno de sus valores: el capítulo 7 es donde la plataforma borra los datos de forma definitiva. dropped informa de que la entrada revisada del campo antiguo ahora no describe nada. El cambio de nombre de la sección sobre el ID de campo es el tercer tipo de cambio, que problems señala como una columna que hay que revisar.

Regla práctica: Ejecuta ambas comprobaciones en cada cambio de esquema: problems para las columnas que nadie ha clasificado o las columnas renombradas que nadie ha vuelto a leer, y dropped para las entradas que no describen nada. Elimina la entrada de una columna eliminada en la misma solicitud de cambios que la elimina. Eliminar una columna personal no elimina sus valores, que el viaje en el tiempo sigue leyendo hasta que caducan las instantáneas que los contienen y se borran sus archivos. Nunca elimines y vuelvas a añadir una columna para renombrarla: renómbrala en su lugar, para que conserve su ID de campo y sus datos.

Clasifica los identificadores pseudonimizados para unirlos

Último cambio en la edición 2026.11.31

El archivo de metadatos clasifica algunas columnas que apuntan a personas como internal, y la más común de ellas es learner_id. Es un número sin significado propio, y los analistas y científicos de datos de la plataforma lo necesitan para unir entre sí las inscripciones, los eventos, los pagos y los tickets. Un identificador sin significado propio, como learner_id, es un identificador seudonimizado: no nombra a nadie, pero conduce a alguien a través de otra tabla. Un identificador llega más lejos de lo que sugiere su clasificación. El código cuenta las tablas que lo contienen, une las inscripciones con los alumnos y consulta a la política de acceso quién puede realizar esa unión y ver los nombres:

pseudonymous-learner-id.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 Superado
"""Counts the tables that carry learner_id and how many enrollments one join resolves to an email, then asks the accesspolicy who sees learners' names and also reads another table's learner_id. The prose's point rests on the enrollmentsline and the last line's list of users."""from lib import catalog, metadata, policy, warehousedescribed = metadata.load()carrying = {name: table.column("learner_id") for name, table in described.items() if table.column("learner_id")}   # column() gives None when absentprint("tables with a learner_id column:", len(carrying))print("learner_id classified as:", ", ".join(sorted({column.classification for column in carrying.values()})))personal = [c.name for c in described["crm.learners"].columns.values() if c.classification == "personal"]print("personal columns in crm.learners:", ", ".join(personal))con = warehouse.connect(catalog.open_catalog(["crm.learners", "learning.enrollments"]))found, total = con.execute("""    -- the left join keeps every enrollment; count(l.email) counts only those whose learner has an email    select count(l.email), count(*)    from learning.enrollments e left join crm.learners l on l.learner_id = e.learner_id""").fetchall()[0]                              # fetchall returns a list of rows, and this query has exactly oneprint("enrollments whose learner_id leads to an email:", f"{found:,} of {total:,}")# Who can put a name on another table's learner_id: users who read that table and see crm.learners' names unmasked.rego, seeing, naming = policy.interpreter(), [], []for user in policy.data_document()["platform"]["users"]:    names = policy.decide(policy.request(user, "crm.learners", ["full_name"]), rego)    if names["allow"] and "full_name" not in names["column_masks"]:          # allowed, and not masked: the name shows in clear        seeing.append(user)        tables = [t for t in carrying if t != "crm.learners"                 # the other tables with learner_id this user may read                  and policy.decide(policy.request(user, t, ["learner_id"]), rego)["allow"]]        naming += [f"{user} ({', '.join(tables)})"] if tables else []print("users who see learners' names in crm.learners:", ", ".join(seeing))print("of them, users who read learner_id in another table:", ", ".join(naming))
Salidapython pseudonymous-learner-id.py
tables with a learner_id column: 7
learner_id classified as: internal
personal columns in crm.learners: full_name, email, phone, city, street_address, date_of_birth, notes
enrollments whose learner_id leads to an email: 20,000 of 20,000
users who see learners' names in crm.learners: agent-a01, agent-a05, agent-a09, marketing-1
of them, users who read learner_id in another table: agent-a01 (support.tickets), agent-a05 (support.tickets), agent-a09 (support.tickets)

Una unión llega a una persona: 20,000 of 20,000 inscripciones conducen a un correo electrónico, y con el correo llegan el nombre, el número de teléfono, la dirección y la fecha de nacimiento del alumno, que están entre las personal columnas de la tabla. Sin embargo, learner_id es internal en las 7 tablas que lo contienen.

El Reglamento General de Protección de Datos (RGPD) de la UE trata datos como estos en el considerando 26: «Los datos personales sometidos a seudonimización, que podrían atribuirse a una persona física mediante la utilización de información adicional, deben considerarse información sobre una persona física identificable» (RGPD, considerando 26). Lo que el considerando significa para una plataforma concreta es una cuestión para sus abogados, y aquí no la respondemos.

Lo que sí decidimos es cómo trata el código del libro al identificador. internal describe lo que la columna revela en la tabla que la contiene, y la descripción de cada learner_id en el archivo de metadatos explica el resto, nombrando a crm.learners como la tabla que lo resuelve, como ocurre también con la de learning.enrollments: «El alumno que se inscribió. Identifica a una persona cuando se une con crm.learners.». La protección recae sobre la tabla que resuelve el identificador. El capítulo 5 decide quién puede leer las columnas personales de crm.learners, y las últimas líneas del ejemplo preguntan a su política quién ve allí los nombres de los alumnos: agent-a01, agent-a05, agent-a09, marketing-1. De ellos, solo los agentes de soporte también leen un learner_id en otra tabla: agent-a01 (support.tickets), agent-a05 (support.tickets), agent-a09 (support.tickets). Pueden poner un nombre a cada ticket de su región, y eso es su trabajo. Marketing ve nombres, pero no lee ninguna otra tabla que contenga el identificador.

Así pues, es la política, no la clasificación del identificador, la que decide quién puede realizar la unión. Clasificar support.tickets.learner_id como personal no cambiaría nada para soporte, el único grupo que lee la tabla, porque la política ya muestra a soporte todas las columnas personales. El borrado, en el capítulo 7, tiene que llegar a cada tabla que contenga el learner_id de un alumno, sea cual sea su clasificación. A estos identificadores los llamamos seudonimizados, nunca anonimizados.

Regla práctica: Clasifica un identificador pseudonimizado según lo que revela su propia tabla, para que las uniones que necesitan tus analistas sigan funcionando, y explica en su descripción a través de qué tabla se resuelve. Protege la tabla que lo resuelve e incluye el identificador en cada supresión. Quién puede resolver el identificador es una decisión de acceso: haz una lista de los usuarios que pueden leer sin enmascarar tanto el identificador como las columnas personales de la tabla que lo resuelve, y concede ese par solo a quienes tienen como trabajo vincular filas con personas.

Redactar metadatos con un modelo local

Último cambio en la edición 2026.11.27

La prueba contra el catálogo te indica qué columnas nadie ha descrito, pero no escribe las descripciones. Redactar una descripción y elegir una clasificación para cada columna es la parte más lenta de mantener un catálogo, y ese trabajo vuelve con cada tabla que añade un pipeline. Un modelo de lenguaje puede redactar ambas cosas a partir de lo que una herramienta de catálogo puede mostrarle: el nombre de una columna, su tipo y algunos de sus valores. La investigación respalda tanto la ayuda como sus límites. En un benchmark, con instrucciones y un pipeline de dos pasos, ChatGPT etiquetó los tipos semánticos de columnas de tablas con "puntuaciones F1 superiores al 85 % en configuraciones zero-shot y one-shot" (Korini y Bizer, 2023). Un estudio de descripciones de columnas generadas encontró que los modelos tienen dificultades con las columnas cuyo significado es ambiguo, y que esas columnas necesitan la aportación manual de un experto (Wretblad et al., 2024). Por eso el borrador de un modelo es una propuesta que una persona acepta, corrige o rechaza en la pull request. Lo primero es medir cuánto se equivocan los borradores, para que la revisión sepa dónde mirar.

Los borradores del libro, que los ejemplos llaman las sugerencias de metadatos, fueron registrados una vez por recordings/metadata_suggestions.py, y los ejemplos leen ese registro, de modo que ninguno de ellos llama a un modelo. El script ejecuta Qwen3-1.7B en una revisión fijada. El modelo es abierto, bajo la licencia Apache-2.0, así que cualquiera puede descargar los mismos pesos. Con 1.700 millones de parámetros se ejecuta en una CPU, sin GPU, lo que mantiene los valores de muestra en la máquina que lo ejecuta. Además, está ajustado a instrucciones, con un interruptor que desactiva su "pensamiento", el razonamiento que de otro modo escribe antes de responder. El script decodifica de forma voraz, tomando el siguiente token más probable, aunque la ficha del modelo sugiere muestreo en este modo: "Temperature=0.7, TopP=0.8, TopK=20, and MinP=0" (Qwen3-1.7B). Un registro debe salir igual cuando alguien lo vuelve a registrar, y una respuesta muestreada es una extracción entre muchas.

Para cada columna de las ocho tablas de origen de la plataforma, el modelo vio el nombre de la tabla, el nombre de la columna y su tipo Iceberg, cinco valores de la columna elegidos con una semilla fija, y las cuatro clasificaciones con los significados de la tabla de clasificaciones. Cada significado viene con dos ejemplos, y ninguno de ellos es una columna de la plataforma. Para sensitive, son "un número de identificación gubernamental o una condición de salud". Se pidió al modelo una descripción de una frase y una clasificación, en JSON. El manifiesto del registro indica el modelo, su revisión, un hash de los prompts y la configuración, y la fecha, de modo que cualquiera puede volver a registrar y comparar.

Esos cinco valores son datos personales siempre que la columna lo sea: en el caso de support.tickets.body, los tickets que leyó el modelo contenían nombres de estudiantes, direcciones postales, un número de teléfono, una fecha de nacimiento y un número de cuenta bancaria. Un modelo que se ejecuta en tu propia máquina los conserva allí. Enviar el mismo prompt a un modelo alojado en la nube envía los datos personales de la plataforma a otra empresa, lo que exige la misma decisión que cualquier otra transferencia de ellos.

Frente al archivo revisado, la clasificación de cada borrador muestra si coincide:

suggestion-agreement.py Python 3.12.15 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Compares the recorded model's classification of each source column with the reviewed one, and counts how many agree.The prose's point rests on the agreement line and on the two lines counting personal and sensitive columns."""from collections import Counterfrom lib import metadatareviewed = metadata.load()                                   # governance/metadata.toml, reviewed by peoplesuggested = metadata.suggestions()                           # the recorded answers under the book's prompt: no model runs hereassert all(reviewed[s.table].columns[s.field_id].name == s.column for s in suggested)   # each answer names the file's column at its field IDprint("columns the model was asked about:", len(suggested))print("answers that parse as the JSON asked for:", sum(s.description is not None for s in suggested))   # None when the answer isn't that JSONprint("answers with one of the four classifications:", sum(s.classification in metadata.LEVELS for s in suggested))pairs = Counter((reviewed[s.table].columns[s.field_id].classification, s.classification) for s in suggested)agree = sum(n for (was, said), n in pairs.items() if was == said)print("classifications that agree with the review:", f"{agree} of {len(suggested)} ({agree / len(suggested):.0%})")for level in metadata.LEVELS:    said = sorted(((s, n) for (was, s), n in pairs.items() if was == level), key=lambda p: -p[1])    print(f"reviewed {level}, the model said:", ", ".join(f"{s} {n}" for s, n in said))for level in ("personal", "sensitive"):    reviewed_as = sum(n for (was, _), n in pairs.items() if was == level)    print(f"{level} columns the model called {level}:", f"{pairs[level, level]} of {reviewed_as}")
Salidapython suggestion-agreement.py
columns the model was asked about: 64
answers that parse as the JSON asked for: 64
answers with one of the four classifications: 64
classifications that agree with the review: 40 of 64 (62%)
reviewed public, the model said: internal 3, public 3
reviewed internal, the model said: internal 37, public 5, sensitive 2
reviewed personal, the model said: internal 9, public 3
reviewed sensitive, the model said: internal 2
personal columns the model called personal: 0 of 12
sensitive columns the model called sensitive: 0 of 2

Todas las 64 respuestas son JSON válido con una de las cuatro clasificaciones, lo que demuestra que el formato funcionó y no dice nada sobre si las respuestas son correctas. Coinciden con la revisión en 40 of 64 (62%) columnas, y ese número único oculta dónde están los fallos. La mayor parte de la coincidencia corresponde a columnas internal que se clasificaron como internal. De las columnas personales de la plataforma, el modelo clasificó 0 of 12 como personal, y de sus sensitive columnas, el número de tarjeta y la cuenta de pago, 0 of 2: clasificó ambas como internal.

Los ejemplos de un prompt pueden revelar la respuesta

Último cambio en la edición 2026.11.27

Los ejemplos de un prompt forman parte de la medición. El script también registra el mismo modelo sobre las mismas columnas con un segundo prompt, idéntico salvo por sus ejemplos. Ese prompt da ejemplos solo para personal y sensitive, y son las propias columnas de la plataforma. Para personal, son "un nombre, datos de contacto, una dirección o un texto que escribieron", y para sensitive, un número de tarjeta o una cuenta bancaria. Esas dos son billing.payments.card_number y crm.instructors.payout_iban, las únicas columnas sensibles. Puestas una junto a otra, las respuestas muestran lo que cambian los ejemplos:

suggestions-with-platform-examples.py Python 3.12.15 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Scores the recorded answers under two prompts against the reviewed classifications: the book's prompt, whose examplescome from outside the platform, and one whose examples are the platform's own columns. The prose's point rests onthe sensitive-column lines and the agreement counts."""from lib import metadatareviewed = metadata.load()prompts = {"the book's prompt": metadata.SUGGESTIONS,           "the prompt with the platform's columns as examples": metadata.SUGGESTIONS_WITH_PLATFORM_EXAMPLES}for name, path in prompts.items():    # Each recorded answer, paired with the classification the file reviewed for its column.    suggested = [(s, reviewed[s.table].columns[s.field_id].classification) for s in metadata.suggestions(path)]    agree = sum(s.classification == was for s, was in suggested)    print(f"{name}, classifications that agree with the review:", f"{agree} of {len(suggested)}")    for level in ("personal", "sensitive"):        reviewed_as = [s for s, was in suggested if was == level]        print(f"{name}, {level} columns called {level}:",              f"{sum(s.classification == level for s in reviewed_as)} of {len(reviewed_as)}")    for s, was in suggested:        if was == "sensitive":            print(f"{name}, {s.table}.{s.column}:", s.classification)
Salidapython suggestions-with-platform-examples.py
the book's prompt, classifications that agree with the review: 40 of 64
the book's prompt, personal columns called personal: 0 of 12
the book's prompt, sensitive columns called sensitive: 0 of 2
the book's prompt, crm.instructors.payout_iban: internal
the book's prompt, billing.payments.card_number: internal
the prompt with the platform's columns as examples, classifications that agree with the review: 41 of 64
the prompt with the platform's columns as examples, personal columns called personal: 0 of 12
the prompt with the platform's columns as examples, sensitive columns called sensitive: 2 of 2
the prompt with the platform's columns as examples, crm.instructors.payout_iban: sensitive
the prompt with the platform's columns as examples, billing.payments.card_number: sensitive

Un prompt que nombra las columnas propias de la plataforma acierta con las sensibles, y el prompt del libro no. Con las columnas de la plataforma como ejemplos, el modelo acierta 2 of 2 columnas sensibles. El prompt del libro acierta 0 of 2, y llama a ambas internal.

El acuerdo general apenas se mueve, 41 of 64 frente a 40 of 64, así que un solo número nunca mostraría la diferencia. Las columnas personales no ganaron nada con sus ejemplos: 0 of 12 salió personal también con ese prompt.

"Un número de tarjeta" nombra card_number casi palabra por palabra, mientras que "un nombre" deja que el modelo decida que full_name es uno, y no lo hizo. Un prompt cuyos ejemplos coinciden con el catálogo hace que un modelo parezca mejor de lo que es, en las columnas que más necesitan protección, por eso el prompt del libro toma sus ejemplos de fuera de los datos de la plataforma.

Regla práctica: Redacta metadatos con un modelo solo a partir de entradas que tengas permiso para enviarle, preferiblemente a un modelo en tus propias máquinas. Registra cada respuesta con el modelo, su revisión, el prompt y la configuración, para que un revisor pueda ver qué produjo cada borrador, y analiza y valida cada respuesta antes de que nada la use. Toma los ejemplos del prompt de fuera de las tablas sobre las que lo mides. Informa del acuerdo con los metadatos revisados por clasificación, nunca como un único número.

Mide dónde fallan los borradores del modelo

Último cambio en la edición 2026.11.27

Los borradores registrados, las descripciones y clasificaciones de un modelo local para las tablas de origen de la plataforma, coinciden con las clasificaciones revisadas en la mayoría de las columnas. Para la gobernanza, la dirección de los fallos importa más. Una clasificación más protegida de lo que debería ser le cuesta a un revisor un minuto y a un analista una columna enmascarada. Una menos protegida de lo que debería ser deja datos personales donde las políticas los tratan como datos del personal, o como datos que cualquiera puede ver. Separar los fallos según su dirección muestra en qué sentido falla el modelo:

suggestion-mistakes.py Python 3.12.15 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Counts the recorded classifications that protect a column less than the review does, and those that protect it more,then lists each kind of miss. The prose's point rests on the two counts and on the `personal columns the model calledinternal` line."""from lib import metadatareviewed = metadata.load()rank = metadata.LEVELS.index                                   # a column's position in LEVELS: a larger rank is more protectedweaker, stronger = [], []for s in metadata.suggestions():    if s.classification not in metadata.LEVELS:                    # an answer nobody can act on goes to a person        continue    column = reviewed[s.table].columns[s.field_id]    if rank(s.classification) < rank(column.classification):        weaker.append((s, column.classification))    elif rank(s.classification) > rank(column.classification):        stronger.append((s, column.classification))print("columns the model protects less than the review:", len(weaker))print("columns the model protects more than the review:", len(stronger))# Each kind of miss, the most protected review first.for misses in (weaker, stronger):    for was, said in sorted({(was, s.classification) for s, was in misses}, key=lambda p: (-rank(p[0]), -rank(p[1]))):        names = [f"{s.table}.{s.column}" for s, w in misses if (w, s.classification) == (was, said)]        print(f"{was} columns the model called {said}:", len(names))        print(f"which, {was} called {said}:", ", ".join(names))
Salidapython suggestion-mistakes.py
columns the model protects less than the review: 19
columns the model protects more than the review: 5
sensitive columns the model called internal: 2
which, sensitive called internal: crm.instructors.payout_iban, billing.payments.card_number
personal columns the model called internal: 9
which, personal called internal: crm.learners.full_name, crm.learners.email, crm.learners.phone, crm.learners.date_of_birth, crm.learners.notes, crm.instructors.full_name, crm.instructors.email, learning.events.ip_address, support.tickets.body
personal columns the model called public: 3
which, personal called public: crm.learners.city, crm.learners.street_address, learning.reviews.body
internal columns the model called public: 5
which, internal called public: learning.events.event_type, learning.events.occurred_at, learning.events.user_agent, learning.reviews.posted_at, support.tickets.opened_at
internal columns the model called sensitive: 2
which, internal called sensitive: crm.learners.marketing_consent, crm.learners.ai_training_consent
public columns the model called internal: 3
which, public called internal: learning.courses.course_id, learning.courses.title, learning.courses.price_usd

Los fallos del modelo recaen en las columnas que más necesitan protección. Protegió 19 columnas menos de lo que lo hizo la revisión, y 5 más. Todas las columnas personales y sensibles están entre las menos protegidas. Clasificó 9 columnas personales como internal, entre ellas los nombres y correos electrónicos tanto de crm.learners como de crm.instructors, los números de teléfono, las fechas de nacimiento y las notas de los alumnos, las direcciones IP de los eventos y el texto de los tickets de soporte. Clasificó 3 de ellas como public: las ciudades y direcciones postales de los alumnos, y el texto de sus reseñas. El significado que el prompt da a personal empieza por "identifica a una persona o dice algo sobre ella", y un nombre o un correo electrónico hacen ambas cosas.

Las otras columnas menos protegidas son marcas de tiempo, el tipo de un evento y su agente de usuario, que el modelo clasificó como public donde la revisión eligió internal: un error menor, pero uno que el revisor aún tiene que detectar. Los fallos en sentido contrario cuestan menos. El modelo clasificó 2 marcas de consentimiento como sensitive, y clasificó como internal el identificador público, el título y el precio del catálogo de cursos.

Las descripciones fallan de otra manera, y cuatro de las del modelo lo muestran junto a las revisadas:

suggestion-descriptions.py Python 3.12.15 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Prints the recorded description beside the reviewed one for four columns, where the review knows what a name, a typeand five values can't say. The prose's point rests on the pairs themselves, read one after another."""from lib import metadatareviewed = metadata.load()suggested = {(s.table, s.column): s for s in metadata.suggestions()}   # keyed by name, so the four columns below can be named# Four columns where the platform knows more than a name, a type and five values say.for table, column in [("crm.learners", "ai_training_consent"), ("crm.learners", "support_region"),                      ("crm.learners", "notes"), ("billing.payments", "card_number")]:    print(f"{table}.{column}, the model:", suggested[table, column].description)    print(f"{table}.{column}, the review:", reviewed[table].column(column).description)   # looked up by name: the file keys columns by field ID, but `column()` finds one by name
Salidapython suggestion-descriptions.py
crm.learners.ai_training_consent, the model: This column indicates whether a learner has consented to receive AI training.
crm.learners.ai_training_consent, the review: Whether the learner agreed to their text training the platform's AI. Unknown for sign-ups before the question was asked.
crm.learners.support_region, the model: The 'support_region' column indicates the regional support area for learners in the online learning platform.
crm.learners.support_region, the review: The support team that serves the learner: americas, emea or apac.
crm.learners.notes, the model: Stores notes from learners about their move, billing address, or preferences.
crm.learners.notes, the review: Free text from support agents. May hold anything, so it is treated as personal.
billing.payments.card_number, the model: Stores the card numbers of customers for payment processing.
billing.payments.card_number, the review: The full card number, from a legacy export. Should not be stored at all.

Cada descripción es fluida y verosímil, y tres de las cuatro omiten algo que solo podría escribir alguien que sabe cómo la plataforma llena la columna. ai_training_consent indica si el texto del alumno puede entrenar la IA de la plataforma, no si el alumno quiere que se entrene, y un valor nulo significa que nunca se hizo la pregunta. notes los escriben agentes de soporte sobre los alumnos, como sugieren los valores, con una nota sobre las facturas de la empresa del alumno, y no los alumnos. Y card_number es una columna heredada que no debería existir, lo más útil que su descripción puede decir. La cuarta es correcta en el fondo: la plataforma asigna a cada alumno el support_region del equipo de soporte que atiende a su país, y el modelo lo llama su "área regional de soporte". Nada en una descripción fluida indica si es correcta o si omite algo, así que un revisor lee cada una. Los autores de un método para generar descripciones de columnas señalan el mismo fallo en los modelos de un solo prompt, que escriben descripciones alucinadas o incompletas (Cai et al., 2026).

Son las respuestas de un modelo pequeño, decodificadas de forma codiciosa (greedy), a dos prompts. El registro no permite saber si el modelo falla en las columnas personales por su tamaño, o porque redacta con solo un nombre, un tipo y cinco valores como base. Un modelo más grande o un prompt mejor pueden acertar más columnas, y la forma de comprobarlo es medirlo del mismo modo, contra el archivo revisado, antes de confiarle tablas que nadie ha revisado.

Regla práctica: Deja que un modelo suba la clasificación de una columna, nunca que la baje: solo un revisor la baja, en la solicitud de cambios, con el motivo en la descripción de la columna. Trata las descripciones del modelo como primeros borradores que alguien que conozca la columna debe reescribir. Antes de que un modelo redacte metadatos de tablas que nadie ha revisado, mídelo contra tus metadatos revisados, por clasificación y por dirección del error, y vuelve a medirlo cada vez que cambien el modelo o el prompt.

Qué sale mal en producción

Último cambio en la edición 2026.11.27

Nada da error cuando los metadatos quedan desactualizados, y cada uno de los fallos siguientes parece completo hasta que alguien confía en él.

  • Los propietarios quedan desactualizados. Los equipos se renombran, se fusionan y se disuelven, y el propietario que aparece en el archivo les sobrevive. Un equipo, a diferencia de una persona, sobrevive a la salida de un miembro, pero el archivo aún necesita una comprobación de que cada propietario es un equipo que existe, ejecutada contra la lista de equipos de tu organización. Si conservas la propiedad en ODCS, sus miembros del equipo llevan un dateOut y un replacedByUsername (ODCS v3.2.0), que una comprobación puede leer para encontrar un equipo sin ningún miembro actual con el rol owner.
  • Las descripciones describen el esquema del año pasado. El significado de una columna cambia mientras su nombre y su tipo permanecen igual: amount empieza a contener reembolsos como números negativos, o status gana un valor. Ninguna comprobación del esquema lo detecta. Los comentarios en el código fallan de la misma manera. La investigación sobre ellos encontró que un detector identifica las inconsistencias con más precisión cuando ve un cambio antes de que se confirme que cuando solo ve el código resultante (Panthaplackel et al., 2021). En el caso de las columnas, la comparación solo funciona cuando una solicitud de cambios muestra el cambio. El código de un pipeline cambia en un diff, pero un sistema de origen puede cambiar lo que escribe sin que aparezca ningún diff. Cuando existe un diff, haz que la solicitud de cambios que modifica la lógica de un pipeline muestre las descripciones de las columnas que escribe, para que quien revisa lea ambas cosas.
  • Los metadatos indexados por nombre quedan desactualizados al renombrar. Una hoja de cálculo de columnas, el diccionario de datos de un panel o una política escrita con nombres de columna pierde una columna en cada renombrado, como muestra la sección sobre los ID de campo, y no informa de ello. Genera todas las vistas indexadas por nombre a partir del archivo indexado por ID, y ejecuta problems en cada cambio de esquema.
  • Dos fuentes de metadatos se sobrescriben entre sí. La página web de un servidor de catálogo y un archivo en un repositorio aceptan ediciones, y una sincronización en cualquiera de los dos sentidos pierde los cambios del otro. DataHub mantiene separadas las ediciones hechas en su interfaz de los metadatos ingeridos, de modo que los pipelines de ingesta no sobrescriban lo que introdujeron los usuarios (entidad de conjunto de datos de DataHub). Elige una sola fuente, y haz que la otra sea de solo lectura o generada.
  • Las ediciones de descripción provocan revisiones que nadie necesita. En PyIceberg, cada edición de documentación asigna un nuevo ID al esquema, como muestra la edición de documentación anterior, así que una revisión basada en los ID de esquema se activa sin motivo. Compara en su lugar los ID de campo, los nombres y los tipos.
  • Las clasificaciones propuestas se aprueban en bloque. Una solicitud de cambios que añade cuarenta columnas con borradores generados por un modelo recibe una lectura de sus descripciones y una revisión superficial de sus clasificaciones, y los borradores registrados muestran adónde lleva eso. Enumera cada clasificación propuesta por separado de las descripciones, empezando por la menos protegida, para que quien revisa vea qué dejaría sin protección cada borrador.
  • Una tabla creada fuera de los pipelines se escapa de la prueba. Un cuaderno o un backfill puntual crea una tabla que nadie añadirá al archivo. Ejecuta problems de forma programada contra el catálogo de producción, no solo en las solicitudes de cambios.

Lo que decidió este capítulo

Último cambio en la edición 2026.11.27
  • Los metadatos son un archivo revisado: los propietarios, los dominios, las descripciones y las clasificaciones viven en governance/metadata.toml, y solo se cambian mediante una solicitud de extracción (pull request).
  • Cuatro clasificaciones, ordenadas: public, internal, personal y sensitive, prevaleciendo la más estricta cuando una columna se construye a partir de varias. Una columna sin clasificación se trata como sensitive.
  • Un solo equipo propietario por tabla, nunca una persona, y un dominio junto a él.
  • Las columnas se identifican por el ID de campo de Iceberg, conservando el nombre junto a él para que un cambio de nombre aparezca en la revisión.
  • Las descripciones se almacenan en el doc de Iceberg, escritas por lib.metadata.apply. El propietario y el dominio se guardan como propiedades de la tabla a modo de referencia, y las clasificaciones permanecen en el archivo.
  • El catálogo se prueba contra el archivo: problems recorre cada tabla del catálogo, y dropped encuentra entradas de columnas que ya no existen. Los cambios de esquema se comparan por ID de campo, nombres y tipos, no por los ID de esquema.
  • learner_id es internal en todas las tablas, con una descripción que indica que se resuelve a través de crm.learners. La protección recae sobre esa tabla, y la política de acceso decide quién puede unir ambas con los nombres a la vista.
  • apply y problems se ejecutan con cada cambio: apply escribe el archivo en el catálogo en cada fusión, y problems se ejecuta en cada solicitud de extracción y de forma programada contra el catálogo de producción.
  • El modelo que redacta los metadatos se ejecuta en las máquinas propias de la plataforma, porque los valores de muestra que se le muestran son datos personales siempre que la columna lo sea.
  • Los metadatos redactados por el modelo son una propuesta. Los borradores se registran con su modelo, se miden contra el archivo revisado y una persona los reescribe. Un modelo puede elevar una clasificación, pero nunca rebajarla. Un prompt que menciona las columnas propias del catálogo favorece al modelo, así que los ejemplos de un prompt proceden de fuera de los datos de la plataforma. Una descripción desactualizada se convierte en una prueba fallida.

Este capítulo, en esta edición

Edición 2026.11.31Ejemplos verificados el 19 de nov de 2026Superan la prueba 11 de 11 ejemplos ejemplos de este capítulo

Traducido del libro en inglés, edición 2026.11.31.

Cita esta sección

Formato

Cada formato cita el libro en inglés, que esta traducción sigue.

Cada formato nombra esta edición. Su enlace abre la edición actual, donde el encabezado de cada sección indica cuándo cambió su texto por última vez. Las fechas de acceso y de recuperación son el día en que lo abres.

En esta página

Capítulo 2 de 10: Un catálogo que puedes probar

  1. Guarda los metadatos en un archivo revisado
  2. Indexa los metadatos de columna por ID de campo
  3. Escribe las descripciones en el esquema de la tabla
  4. Una edición de descripción es un cambio de esquema
  5. Prueba el catálogo contra los metadatos
  6. Detecta los cambios de esquema antes de que los metadatos queden desactualizados
  7. Clasifica los identificadores pseudonimizados para unirlos
  8. Redactar metadatos con un modelo local
  9. Los ejemplos de un prompt pueden revelar la respuesta
  10. Mide dónde fallan los borradores del modelo
  11. Qué sale mal en producción
  12. Lo que decidió este capítulo

Volver arribaTodos los capítulos