Gobernanza de extremo a extremo
Unos 28 minutos de lectura, con 6 ejemplos en 8 secciones.
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
En esta página
- Cataloga una tabla con su propietario y sus clasificaciones
- Capture one pipeline's column lineage
- Hacer cumplir una decisión de acceso en una consulta
- Haz fallar el pull request que añade una columna sin clasificar
- Qué sale mal en producción
- Una hoja de gobernanza que nadie actualiza
- Una política que una herramienta aplica y otra elude
- Lo que decidió este capítulo
Al final de este capítulo podrás gobernar, con código y de extremo a extremo, una tabla de una plataforma de datos. La catalogarás con un equipo propietario y una clasificación para cada columna, capturarás el linaje de un pipeline que la copia, decidirás quién puede leer cuáles de sus filas y harás cumplir esa decisión en una consulta, y verás fallar una pull request porque añadió una columna que nadie clasificó. Cada parte es pequeña y se ejecuta en segundos, y cinco capítulos posteriores consolidan cada una de ellas.
Este libro está dirigido a ingenieros de datos, analítica y plataformas que ya construyen pipelines y almacenes, y a quienes se les ha pedido que los gobiernen. Conoces SQL, Python y Parquet o una tabla de lakehouse, y no necesitas teoría de gobernanza: necesitas una gobernanza que funcione, que se pruebe y que se revise en pull requests como el resto de tu código. Al terminar el libro, podrás gobernar una plataforma de datos con código que se ejecuta en CI:
- un catálogo donde cada tabla tiene un propietario y cada columna una clasificación;
- datos personales encontrados automáticamente, con medición de lo que el detector no detecta;
- linaje capturado desde los pipelines;
- políticas de acceso como código probado, aplicadas como filtros de filas y máscaras de columnas;
- retención y borrado que eliminan datos;
- un registro de auditoría;
- comprobaciones que hacen fallar una pull request;
- las mismas reglas aplicadas a los datos que entrenan o fundamentan la IA.
Este libro sigue un único caso de principio a fin: una plataforma de aprendizaje en línea que vende cursos profesionales a adultos, a la que llamamos la plataforma. Su almacén es un catálogo de tablas Iceberg, cada una bajo el espacio de nombres del equipo que la gestiona: alumnos e instructores bajo crm, cursos, inscripciones, eventos de aprendizaje y reseñas de cursos bajo learning, pagos bajo billing, y tickets de soporte bajo support. Los pipelines SQL construyen a partir de ellas tablas de informes. Los agentes de soporte, los instructores, marketing, finanzas, los científicos de datos y el asistente de cursos de la plataforma, su IA, necesitan cada uno algo distinto de esas tablas, y eso es lo que hace que la plataforma merezca ser gobernada.
Los datos de la plataforma, que leen todos los ejemplos de este libro, están generados. Un script los crea una vez a partir de semillas fijas con Faker, una biblioteca de datos falsos, y los archivos se confirman junto con una ficha de datos que explica cómo se generaron. No hay ninguna persona real en los datos. Sus direcciones de correo están en dominios reservados para ejemplos, de modo que no pueden llegar a nadie, y sus direcciones IP están en rangos reservados para documentación, de modo que no apuntan a nadie. Sus números de teléfono, números de tarjeta e IBAN son aleatorios con un formato válido, así que uno podría coincidir con un número o una cuenta en servicio: nunca llames, envíes mensajes, cobres ni pagues a ninguno. La ficha de datos también enumera lo que se ha incluido intencionadamente para que los ejemplos lo encuentren, como números de tarjeta completos en una columna heredada y datos personales en texto libre.
Cada ejemplo se ejecuta sin conexión, en un único proceso de Python 3.12.15, con bibliotecas fijadas en versiones concretas: PyIceberg 0.12.0 para el catálogo Iceberg y sus tablas, DuckDB 2.0.0 para las consultas, sqlglot 30.33.0 para analizar SQL, openlineage-python 1.55.0 para el linaje, y regopy 1.5.2 para las políticas escritas en Rego, el lenguaje de políticas de Open Policy Agent (OPA). Seis servicios que una plataforma de producción ejecuta no funcionan aquí, y cada uno tiene un sustituto:
- Trino, el motor SQL a través del cual consultan las herramientas: DuckDB detrás de la capa de aplicación del libro, que reescribe cada consulta antes de ejecutarla.
- El servidor de OPA, al que Trino le pide decisiones de acceso (Trino 484, control de acceso con OPA): regopy, que evalúa el mismo Rego dentro del proceso de Python.
- Spark, o cualquier motor que ejecute los pipelines a escala: DuckDB, ejecutando el archivo SQL de cada pipeline.
- Un servidor de catálogo o un catálogo en la nube, que sirve los metadatos de las tablas a través de una API como la del catálogo REST de Iceberg (especificación del catálogo REST, 1.12.0): el catálogo SQL de PyIceberg, respaldado por un archivo SQLite que registra dónde están los metadatos de cada tabla, con los metadatos junto a los datos en disco local.
- Un servidor de linaje: un archivo de eventos de OpenLineage, que el código del libro lee para construir un grafo.
- El servicio de CI y git: dos carpetas, una para la rama principal y otra para la rama de una pull request.
Lo que aprendes aquí son los estándares abiertos con los que trabajan esos servicios: los metadatos de tabla de Iceberg, OpenLineage y Rego. Lo que construyes se corresponde con ellos.
La gobernanza de la plataforma empieza con una hoja de cálculo. Alguien enumeró las columnas de crm.learners, que contiene el nombre, el correo, el teléfono y la dirección de cada alumno, con una clasificación junto a cada una, y eso es todo. Ningún equipo figura como propietario de la tabla. Un pipeline nocturno copia nombres y correos de alumnos a una tabla para marketing, y nada registra que lo haga. Cada agente de soporte atiende una región, pero una consulta en el almacén devuelve los alumnos de todas las regiones. Y el equipo de CRM está a punto de añadir una columna. Este capítulo responde a cada una de esas situaciones con el código que los capítulos posteriores construyen, a la menor escala que funciona: una tabla, un pipeline, una regla y una comprobación. Solo una de las cuatro es un motor de políticas; las otras son metadatos, eventos de linaje y una prueba, guardados en el mismo repositorio y revisados de la misma manera.
El capítulo 2 mantiene el catálogo al día con los cambios de esquema y mide los metadatos redactados por un modelo local. El capítulo 4 usa el linaje para el análisis de impacto y para proponer clasificaciones. El capítulo 5 escribe la política completa, con sus pruebas, y el capítulo 6 la aplica en cada consulta. El capítulo 10 ejecuta en CI las comprobaciones de los capítulos 2 a 7, con las aprobaciones de los propietarios y las excepciones.
Cuatro capítulos añaden lo que este deja fuera. El capítulo 3 encuentra los datos personales que los metadatos no recogen. El capítulo 7 trata la retención, el consentimiento y el borrado. El capítulo 8 mantiene un registro de auditoría, y el capítulo 9 aplica las mismas reglas a los datos que entrenan o fundamentan la IA.
Los módulos compartidos, archivos de examples/lib/ que contienen el código que necesitan muchos ejemplos, son tuyos para abrirlos y leerlos, y cada sección indica cuáles usa.
Cataloga una tabla con su propietario y sus clasificaciones
El primer problema de la plataforma es su hoja de cálculo, una lista de columnas que nadie verifica. Un catálogo enumera las tablas de una plataforma y sus esquemas, y la gobernanza necesita dos datos que los datos por sí solos no contienen: quién responde por cada tabla y cómo debe protegerse cada columna. Guardados en una hoja de cálculo o en la página web de un servidor de catálogo, esos datos cambian sin revisión, y ninguna prueba puede decir si están completos. Guardados en un archivo del repositorio, junto a los pipelines, cada cambio es una diferencia que alguien aprueba, y una prueba puede comparar el archivo con el catálogo.
El archivo de la plataforma es governance/metadata.toml. Asigna a cada tabla un propietario, un dominio, es decir, la parte del negocio a la que pertenece la tabla, y una descripción, y a cada columna una descripción y una clasificación. Las herramientas de catálogo entienden cosas distintas por propietario, como compara el capítulo 2, y nosotros usamos un único significado en todo el libro: el equipo responsable de la tabla, nunca una persona, de modo que la respuesta sobreviva a la salida de alguien. Una clasificación es uno de cuatro valores, de menor a mayor protección:
public: puede mostrarse a cualquiera fuera de la plataforma;internal: para el personal de la plataforma, y no identifica por sí solo a una persona;personal: identifica a una persona o revela algo sobre ella;sensitive: datos cuya filtración dañaría directamente a alguien, como un número de tarjeta.
Las columnas se identifican por su ID de campo de Iceberg, que sobrevive a un cambio de nombre, con el nombre junto a él para las personas:
[tables."crm.learners"]
owner = "team-crm"
domain = "crm"
description = "Every learner who has signed up, with their contact details and consents. One row per learner."
[tables."crm.learners".columns]
3 = { name = "email", classification = "personal", description = "The email the learner signs in with." }
Tres de los módulos compartidos del libro hacen el trabajo. lib.catalog.open_catalog construye un catálogo Iceberg nuevo con las tablas de la plataforma en una carpeta temporal, que elimina cuando el ejemplo termina. lib.metadata carga el archivo, lo escribe en el catálogo con apply y comprueba el catálogo frente a él con problems, que informa de cualquier tabla sin metadatos o sin propietario, y de cualquier columna sin clasificación.
Cargar el archivo y catalogar crm.learners con él requiere unas pocas líneas, y la comprobación se ejecuta sobre lo que construye:
1"""Apply governance/metadata.toml to crm.learners: write its owner, domain and descriptions into the catalog, then run the2check on the catalog. The point rests on the last line, the problems the check finds once the file is applied."""3from collections import Counter45from lib import metadata6from lib.catalog import open_catalog78platform = open_catalog(["crm.learners"]) # a fresh Iceberg catalog holding the learners table9described = metadata.load()10learners = described["crm.learners"]11print("owner:", learners.owner)12print("domain:", learners.domain)13counts = Counter(column.classification for column in learners.columns.values())14print("columns classified personal:", counts["personal"])15print("personal columns:", ", ".join(c.name for c in learners.columns.values() if c.classification == "personal"))16print("columns classified internal:", counts["internal"])1718# Write the descriptions into the table's schema, where readers see them, and the owner and domain into its properties.19metadata.apply(platform, described)20table = platform.load_table("crm.learners")21print("table properties:", ", ".join(f"{key}={value}" for key, value in sorted(table.properties.items())))22print("email's description, in the Iceberg schema:", table.schema().find_field("email").doc)2324# The check: every table in the catalog has an owner, and every column one of the four classifications.25print("problems the check finds:", len(metadata.problems(platform, described)))
python catalog-the-learners.pyowner: team-crm
domain: crm
columns classified personal: 7
personal columns: full_name, email, phone, city, street_address, date_of_birth, notes
columns classified internal: 8
table properties: domain=crm, owner=team-crm
email's description, in the Iceberg schema: The email the learner signs in with.
problems the check finds: 0
El archivo asigna crm.learners a team-crm, en el dominio crm, y clasifica 7 de sus columnas como personales: full_name, email, phone, city, street_address, date_of_birth, notes. notes está entre ellas aunque su nombre no diga nada, porque los agentes de soporte escriben en ella lo que quieren. Las columnas restantes son internal: el ID del alumno, dos fechas, su país, sus dos indicadores de consentimiento, el estado de su cuenta y su región de soporte.
Aplicar el archivo también coloca el propietario y las descripciones donde todo lector las ve. Las propiedades de la tabla dicen domain=crm, owner=team-crm, y la descripción de email está en el esquema Iceberg, donde cualquier lector de la tabla la encuentra: "The email the learner signs in with." Las clasificaciones permanecen en el archivo, porque ahí las leen la política de acceso y las comprobaciones. Después de apply, la comprobación encuentra 0 problemas.
Una hoja de cálculo no puede darte ese cero. La comprobación recorre el catálogo, así que una columna que el archivo no describe aparecería como un problema, como le ocurre a work_email en la sección sobre hojas de cálculo.
Regla práctica: Guarda los propietarios, los dominios, las descripciones y las clasificaciones en un único archivo revisado dentro del repositorio, con un equipo como propietario de cada tabla y uno de una lista cerrada de clasificaciones en cada columna. Escribe las descripciones en el catálogo, para que todo lector de una tabla las vea, y prueba el catálogo contra el archivo recorriendo el catálogo, nunca el archivo. Si las ediciones se hacen en la página web de un catálogo, elige uno de los dos lados como fuente y genera el otro a partir de él (capítulo 2).
Esta parte aún no está traducida, así que está en inglés.
Capture one pipeline's column lineage
The catalog says what a table holds. Lineage says where its data came from and where it went, and governance needs both: a table built from crm.learners may or may not copy its emails. OpenLineage, an open specification for lineage, describes a job, such as a pipeline, its runs, and the datasets each run reads and writes. A run reports itself in events: a START when it begins, then one that ends it, such as COMPLETE or FAIL. Events carry facets, OpenLineage's name for blocks of metadata attached to a run, a job or a dataset.
The column lineage facet, on the output of a COMPLETE event, lists for each output column the input columns it came from, each marked DIRECT or INDIRECT. DIRECT means the output is derived from the input. INDIRECT means the input shapes the output without being copied: the output column value is "impacted by the value of inputField column, but it's not derived from it" (column lineage facet). The columns of a join or a filter condition are INDIRECT inputs, since they decide which rows exist, and so are those of a grouping, sort, window or condition.
The client library computes no lineage of its own, as chapter 4 finds in its source: it sends what you give it. So the book's module lib.lineage does the work. It parses each pipeline's SQL with sqlglot and adds the INDIRECT inputs that sqlglot's own lineage leaves out. It also wraps lib.pipelines.run, which runs one of the platform's SQL pipelines on DuckDB and writes its output to the catalog: START before the run, COMPLETE with the lineage after it. The events go through OpenLineage's file transport to one file, with a fixed time and a run ID derived from that time and the job's name, so the example writes the same bytes every time.
The platform's marketing_audience pipeline is one create table ... as select ... statement that writes marketing.audience, the list of learners marketing may email. It selects each learner's ID, name, email and country from crm.learners, joins each learner to their favourite course category, ranked from their enrollments, and keeps the learners for whom l.marketing_consent and l.status = 'active' holds.
Run the pipeline with events on, read its lineage back from the events alone, and count the rows through lib.warehouse.connect, which gives DuckDB a view of each catalog table:
1"""Run the marketing_audience pipeline with OpenLineage events, then read its column lineage back from the events alone.2The point rests on the two INDIRECT lines: the filter and the joins decide which rows the audience table holds."""34from lib import lineage, metadata, warehouse5from lib.catalog import open_catalog6from lib.platform import scratch78platform = open_catalog(["crm.learners", "learning.courses", "learning.enrollments"])9events_file = scratch() / "events.jsonl" # the file that stands in for a lineage server: one event per line10lineage.run(platform, "marketing_audience", lineage.client(events_file))11events = lineage.read_events(events_file)1213print("events:", ", ".join(f"{e['eventType']} of {e['job']['name']}" for e in events))14print("the run read:", ", ".join(dataset["name"] for dataset in events[0]["inputs"])) # the START event lists the inputs15print("the run wrote:", events[-1]["outputs"][0]["name"]) # the last event, COMPLETE, names the output1617graph = lineage.graph(events) # built from the COMPLETE events' column lineage, not from the SQL18for column in ("full_name", "email"):19 inputs = [e for e in graph.edges if e.target == f"marketing.audience.{column}"]20 print(f"marketing.audience.{column} comes from:", ", ".join(f"{e.source} ({e.type} {e.subtype})" for e in inputs))21# The INDIRECT inputs of each kind: the inputs that decide which rows exist, not the ones copied into them.22for subtype in ("FILTER", "JOIN"):23 shaping = [e.source for e in graph.edges if e.target == "marketing.audience" and e.subtype == subtype]24 print(f"its rows are shaped by, INDIRECT {subtype}:", ", ".join(shaping))25duckdb = warehouse.connect(platform) # DuckDB on the catalog's tables, to count what the join dropped26# The learners the filter keeps, counted on crm.learners before any join drops one.27consenting = "select count(*) from crm.learners where marketing_consent and status = 'active'"28print("consenting, active learners in crm.learners:", f"{duckdb.sql(consenting).fetchall()[0][0]:,}") # one row, one column29print("rows in marketing.audience:", f"{duckdb.sql('select count(*) from marketing.audience').fetchall()[0][0]:,}") # one row, one column30# Every column a change to email can reach, at any depth of the graph.31reached = lineage.columns_reached(graph, lineage.downstream(graph, "crm.learners.email"))32print("a change to crm.learners.email reaches:", ", ".join(reached))3334# The catalog check, run on the catalog the pipeline wrote to.35for problem in metadata.problems(platform, metadata.load()):36 print("the catalog check finds:", problem)
python audience-pipeline-lineage.pyevents: START of marketing_audience, COMPLETE of marketing_audience
the run read: crm.learners, learning.courses, learning.enrollments
the run wrote: marketing.audience
marketing.audience.full_name comes from: crm.learners.full_name (DIRECT IDENTITY)
marketing.audience.email comes from: crm.learners.email (DIRECT IDENTITY)
its rows are shaped by, INDIRECT FILTER: crm.learners.marketing_consent, crm.learners.status
its rows are shaped by, INDIRECT JOIN: crm.learners.learner_id, learning.courses.category, learning.courses.course_id, learning.enrollments.course_id, learning.enrollments.learner_id
consenting, active learners in crm.learners: 1,861
rows in marketing.audience: 1,829
a change to crm.learners.email reaches: marketing.audience.email
the catalog check finds: marketing.audience: no metadata
Read from the events alone, the lineage shows what the table's name leaves out. marketing.audience.email comes from crm.learners.email (DIRECT IDENTITY), and full_name from crm.learners.full_name (DIRECT IDENTITY), both unchanged copies of personal columns.
The filter and the joins decide which rows the table holds. The filter's inputs are crm.learners.marketing_consent, crm.learners.status, so every row says its learner consented. The joins' inputs are crm.learners.learner_id, learning.courses.category, learning.courses.course_id, learning.enrollments.course_id, learning.enrollments.learner_id. A learner with no enrollment has no favourite category, so the join to it drops them. crm.learners holds 1,861 consenting, active learners, and marketing.audience holds 1,829.
A change to crm.learners.email reaches only marketing.audience.email in this pipeline's table, so renaming the column, or changing its format, touches that column alone. With all four of the platform's pipelines sending lineage, chapter 4 finds that it reaches no other.
The catalog check, from the section before and run on the same catalog, finds marketing.audience: no metadata. The pipeline created a table nobody has described, and lineage changes what that gap means: from a table the platform knows nothing about to a copy of two personal columns, chosen by consent. Until someone describes it, the platform's access policy treats every column it can't find a classification for as sensitive. So anyone who reads the copy through the platform's enforcement layer, which a later section introduces, gets no value from it, as chapter 6's who-sees-what test shows.
Working rule: Emit lineage from the code that runs each job, never after it (chapter 4): a START event, then a COMPLETE or FAIL event, with the output's column lineage in the COMPLETE event, parsed from the job's SQL, and the inputs that join and filter rows as well as those that supply values. Read lineage back from the events, never from the SQL, so the graph shows what ran. Where a job isn't SQL that a parser can read, such as a Python script, write its lineage in the same code, and review the two together.
Hacer cumplir una decisión de acceso en una consulta
Con las tablas de la plataforma catalogadas, la siguiente pregunta es quién puede leer qué. La política como código parte de la premisa de OPA de que la política puede desacoplarse del software que gobierna, de modo que las personas responsables de ella puedan escribirla, analizarla, versionarla y distribuirla por separado (filosofía de OPA). Una política responde a una solicitud con una decisión. La política de la plataforma responde con un documento y no con un sí o un no: si permitir la lectura, los filtros de filas que dejan solo las filas que el usuario puede ver, y las máscaras de columnas que cambian la forma en que se muestra una columna. Los filtros y las máscaras son datos, nunca SQL. Una decisión no hace nada por sí misma. Algo entre el usuario y el motor tiene que aplicarla a cada tabla que lee una consulta.
Los agentes de soporte de la plataforma atienden cada uno una región, americas, emea o apac, y necesitan los datos de contacto de los alumnos para responder los tickets. La política, governance/policies/access.rego, deniega cada solicitud por defecto. Permite a cada grupo, el rol que un usuario tiene en governance/users.toml, las tablas que necesita su trabajo, y lee la región del agente del mismo archivo. Esta regla limita a un agente a su región:
row_filters contains {"column": "support_region", "equals": user.region} if {
"support" in groups
table in {"crm.learners", "support.tickets"}
}
lib.policy.decide evalúa la política con regopy. lib.enforce contiene la capa de aplicación: su Enforcer pregunta a la política por cada tabla que lee una consulta, sustituye cada una por una subconsulta que aplica la decisión, y ejecuta la reescritura en DuckDB. lib.enforce.answer es la única función a la que llama un servicio, y devuelve filas, nunca la conexión del motor.
agent-a05, un agente de soporte en EMEA, pide tres columnas de crm.learners y cuenta alumnos por región a través de la capa. A continuación, los correos se comprueban con los archivos generados que lee lib.platform.load:
1"""One access decision from the platform's Rego policy, and the same agent's query enforced in the layer. The point rests on2the emea line: the query names no region, yet only EMEA learners come back."""3import json45from lib import policy6from lib.catalog import open_catalog7from lib.enforce import Enforcer, answer8from lib.platform import load910# agent-a05, a support agent in EMEA, asks to read three columns of crm.learners.11request = policy.request("agent-a05", "crm.learners", ["learner_id", "email", "support_region"]) # the shape Trino's OPA plugin sends12decision = policy.decide(request)13assert decision["allow"] is True # support may read crm.learners; a policy that denies it fails this run14print("allow:", decision["allow"])15print("row filters:", json.dumps(decision["row_filters"]))16print("column masks:", json.dumps(decision["column_masks"]))17print("reasons:", "; ".join(decision["reasons"]))1819# The enforcement layer asks the policy about every table a query reads, then rewrites the query to apply the answer.20layer = Enforcer(open_catalog(["crm.learners"]))21query = "select support_region, count(*) as learners from crm.learners group by support_region order by support_region"22for region, learners in answer(layer, query, "agent-a05"): # the layer adds the agent's region to the query before the engine runs it23 print(f"learners agent-a05 sees in {region}:", f"{learners:,}")2425# Compare the emails the agent gets with the platform's data, without printing any.26stored = load("crm.learners") # the generated data, not the catalog's copy27emails = dict(zip(stored.column("learner_id").to_pylist(), stored.column("email").to_pylist()))28seen = answer(layer, "select learner_id, email from crm.learners", "agent-a05") # the agent's own query, with no region in it29print("emails agent-a05 sees, as stored:", f"{sum(email == emails[learner] for learner, email in seen):,} of {len(seen):,}")30print("learners in the platform's data:", f"{stored.num_rows:,}")
python support-region-enforced.pyallow: True
row filters: [{"column": "support_region", "equals": "emea"}]
column masks: {}
reasons: support may read crm.learners
learners agent-a05 sees in emea: 1,581
emails agent-a05 sees, as stored: 1,581 of 1,581
learners in the platform's data: 5,000
La capa aplicó la región dentro de la consulta, de modo que el SQL del agente no tuvo que hacerlo, y no podía evitarlo. La decisión permite la lectura, con el filtro de filas [{"column": "support_region", "equals": "emea"}] sobre la región propia del agente y las máscaras de columnas {}, ya que soporte es el grupo que necesita los datos de contacto. Su motivo es support may read crm.learners. La consulta del agente no filtra por región, y aun así devuelve 1,581 alumnos, todos en EMEA, de los 5,000 que tiene la plataforma. Sus correos llegan tal como están almacenados, 1,581 of 1,581, porque la decisión no enmascara nada.
regopy es el enlace en Python de rego-cpp, la implementación en C++ de Rego de Microsoft, que es compatible con Rego v1.18.1 tal como lo define OPA (README de rego-cpp en v1.5.2). regopy difiere de OPA en aspectos que enumera el capítulo 5, así que OPA sigue siendo la referencia para cualquier cosa en producción. El capítulo 6 muestra por qué la capa sustituye tablas completas en lugar de enmascarar columnas allí donde una consulta las nombra.
Regla práctica: Escribe las reglas de acceso como una única política en el repositorio que deniegue por defecto y devuelva su decisión como datos: permiso, filtros de filas y máscaras de columnas. Aplica esa decisión en una sola capa que reescriba cada consulta antes de que el motor la ejecute, y entrega a los usuarios las respuestas de esa capa, nunca la conexión del motor. Cuando un motor puede consultar la política por sí mismo, como Trino puede consultar a OPA, deja que el motor sea esa capa.
Haz fallar el pull request que añade una columna sin clasificar
La comprobación del catálogo demuestra que el catálogo está completo el día en que se ejecuta, y la plataforma cambia cada semana. Una comprobación que depende de que alguien se acuerde de ejecutarla se ejecuta pocas veces y se lee menos. Ejecutada en cada pull request, donde su código de salida puede hacerlo fallar, la misma comprobación se convierte en una puerta de control, y sus hallazgos aparecen donde los ingenieros ya trabajan. Los autores de Tricorder, la plataforma de análisis de código de Google, comprobaron una y otra vez que, cuando los desarrolladores tienen que abrir un panel o ejecutar una herramienta de línea de comandos aparte, su uso del análisis disminuye (Sadowski et al., 2015). Es la experiencia de una empresa con el análisis de código, no un dato, pero las comprobaciones de gobernanza se enfrentan a las mismas personas. Además, una puerta de control hace fallar un pull request solo por lo que este cambia, de modo que un hallazgo que ya existe en main se informa con su responsable y no hace fallar ningún pull request que lo deje como está.
El módulo del libro para esto es lib.ci, el trabajo de gobernanza de la plataforma. Un cambio de esquema en la plataforma es una migración, una sentencia alter table en un archivo de la carpeta migrations/ de la rama. Cada lado de un pull request es una copia de trabajo en su propia carpeta, una de main y otra de la rama. Para cada lado, lib.ci.run construye una plataforma temporal, un catálogo nuevo creado de la forma en que funciona la plataforma. Contiene las tablas de origen, las migraciones de ese lado, sus metadatos escritos en el catálogo y sus pipelines. Ejecuta las comprobaciones que se le indican sobre la plataforma de la rama, las ejecuta solo sobre la de main para saber qué hay ya, y compara los hallazgos por ID.
Esta sección ejecuta una comprobación, coverage. La comprobación de cobertura es la comprobación del catálogo, lib.metadata.problems, ejecutada sobre la plataforma de la rama, y para cada columna que nadie clasificó añade lo que sugiere una regla sobre los nombres de columna, de las reglas que el capítulo 3 escribe.
El pull request del equipo de CRM añade en una migración una columna para el correo de trabajo de los estudiantes y olvida los metadatos de la columna, así que la comprobación de cobertura tiene algo que encontrar:
1"""The CRM team's pull request adds a column to crm.learners and no metadata for it; the coverage check runs on its branch and2on main. The point rests on the exit code line: the pull request's own finding fails the job, and the findings on main don't."""3from lib import ci45main = ci.checkout() # the main branch: the governance files and pipelines, and no migrations yet6branch = ci.checkout(main) # the pull request's branch, starting from main7# The pull request's only change: a migration that adds the column, with no metadata for it.8(branch / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")9print("files the pull request changes:", ", ".join(ci.changed(main, branch)))1011# Build a scratch platform from each side, run the coverage check on both, and compare their findings by ID.12report = ci.run(main, branch, checks=["coverage"])13for line in ci.lines(report):14 if not line.startswith("change "): # schema changes are chapter 10's report15 print(line)16for line in ci.totals(report):17 if line.startswith(("findings the pull request introduces", "findings already on main", "exit code")):18 print(line)
python unclassified-column-fails.pyfiles the pull request changes: migrations/0001-add-work-email.sql
coverage: failed, findings 3, new 1, on main 2, waived 0, 12 tables checked
coverage/ai.review_corpus: no metadata; on main, owner team-platform
coverage/crm.learners.work_email: not classified; its name suggests personal
coverage/marketing.audience: no metadata; on main, owner team-platform
job: failed
findings the pull request introduces: 1
findings already on main: 2
exit code: 1
El pull request falla por 1 hallazgo propio, la columna que nadie clasificó. El archivo que cambia es migrations/0001-add-work-email.sql, y la comprobación de cobertura informa de failed, findings 3, new 1, on main 2, waived 0, 12 tables checked, que cuenta las ocho tablas de origen de la plataforma y las cuatro que escriben sus pipelines. El nuevo hallazgo es crm.learners.work_email, informado como not classified; its name suggests personal. La regla por nombre coincide con email, que sugiere la clasificación, y su ID, coverage/crm.learners.work_email, se mantiene igual de una ejecución a otra, así que puede discutirse y contarse.
Los hallazgos que ya había en main estaban antes del pull request: coverage/ai.review_corpus, y coverage/marketing.audience, la tabla que la sección de linaje encontró sin descripción. Ninguna de las dos tablas tiene responsable, así que el trabajo nombra al equipo de la plataforma, el equipo que responde por las tablas sin responsable. El trabajo termina con el código de salida 1, de modo que el pull request falla hasta que la columna tenga una clasificación, y los hallazgos de main no hacen fallar ningún pull request que los deje como están. El trabajo del capítulo 10 ejecuta las comprobaciones de los capítulos 2 a 7 sobre el mismo pull request, 11 de ellas.
Regla práctica: Ejecuta cada comprobación de gobernanza como un único trabajo en cada pull request, exigido por la protección de la rama, y haz que falle por código de salida ante cualquier hallazgo que el pull request introduzca. Informa de los hallazgos que ya existen en la rama main con sus responsables, sin hacer fallar el pull request por ellos. Pon cada hallazgo en el propio pull request, bajo un ID que se mantenga igual de una ejecución a otra, con lo que hay que hacer al respecto. Ejecuta también las mismas comprobaciones de forma programada contra el catálogo de producción, para lo que cambia fuera de los pull requests.
Qué sale mal en producción
La gobernanza falla sin producir ningún error de dos maneras, y las piezas anteriores dan respuesta a ambas: una hoja de cálculo que nadie actualiza, y una política que otra herramienta se salta. La primera es la razón por la que los metadatos son código, y la segunda, por la que el cumplimiento obligatorio de las políticas se concentra en un solo lugar.
Una hoja de gobernanza que nadie actualiza
La hoja de cálculo de la que partió este capítulo enumera tablas y columnas, con una clasificación junto a cada una, y una hoja de cálculo describe el esquema el día en que se escribió. Los esquemas no permanecen quietos. Un estudio de diez aplicaciones de bases de datos de código abierto, con más de 160,000 revisiones entre ellas, señala como primer hallazgo importante que los esquemas de bases de datos evolucionan con frecuencia a lo largo de la vida de una aplicación (Qiu, Li y Su, 2013). El estudio abarca bases de datos de aplicaciones, no almacenes de datos, pero cada cambio que añade una columna añade una que su hoja de cálculo no enumera.
Toma la hoja de cálculo de la plataforma, un inventario de crm.learners exportado como CSV, con una fila por columna. Luego, la migración del equipo de CRM de la solicitud de cambios de arriba añade work_email. Compárala con el catálogo después de la migración para encontrar lo que le falta:
1"""A governance inventory kept as a spreadsheet, exported before a schema change, then compared with the catalog after it.2The point rests on the two work_email lines: the spreadsheet doesn't list the column, and the check finds it unclassified."""3import csv4import io56from lib import ci, metadata7from lib.catalog import open_catalog89platform = open_catalog(["crm.learners"])10described = metadata.load()1112# The inventory: one row per column of crm.learners, exported on the day someone was asked for one.13inventory = io.StringIO()14writer = csv.writer(inventory)15writer.writerow(["table", "column", "classification"])16for field in platform.load_table("crm.learners").schema().fields:17 # Metadata is keyed by Iceberg field ID, not by name, so the lookup survives a rename.18 writer.writerow(["crm.learners", field.name, described["crm.learners"].columns[field.field_id].classification])1920# Later, the CRM team's migration adds a column for learners' work email, applied as an Iceberg schema change.21ci.migrate(platform, "alter table crm.learners add column work_email varchar;")2223rows = list(csv.DictReader(io.StringIO(inventory.getvalue())))24print("columns the spreadsheet lists:", len(rows))25print("of them without a classification, by the spreadsheet:", sum(not row["classification"] for row in rows)) # a blank classification cell: a column the spreadsheet never classified26live = [field.name for field in platform.load_table("crm.learners").schema().fields]27print("columns crm.learners has:", len(live))28print("columns the spreadsheet doesn't list:", ", ".join(sorted(set(live) - {row["column"] for row in rows})))29for problem in metadata.problems(platform, described):30 print("the check against the catalog finds:", problem)
python spreadsheet-misses-new-column.pycolumns the spreadsheet lists: 15
of them without a classification, by the spreadsheet: 0
columns crm.learners has: 16
columns the spreadsheet doesn't list: work_email
the check against the catalog finds: crm.learners.work_email: not classified
La hoja de cálculo parece completa y le falta una columna. Según su propio recuento, enumera 15 columnas, y 0 de ellas carecen de clasificación. La tabla tiene 16 columnas, y la columna que la hoja no enumera es work_email. Nada en la hoja de cálculo puede mostrar eso, porque nada la compara con el catálogo. lib.metadata.problems, la comprobación contra el catálogo, recorre el catálogo y encuentra crm.learners.work_email: not classified, el mismo hallazgo que hace fallar la solicitud de cambios del equipo de CRM. En nuestra experiencia, una copia de los metadatos mantenida a mano, ya sea una hoja de cálculo, una página de wiki o un diccionario de datos, queda desactualizada en el primer cambio de esquema, y nada lo advierte.
Regla práctica: Nunca guardes metadatos de gobernanza en un documento que nadie verifique. Guárdalos en un archivo revisado que una prueba compare con el catálogo activo, en cada solicitud de cambios y de forma programada. Si las personas necesitan una hoja de cálculo, genérala a partir del archivo e indica en ella cuándo se generó.
Una política que una herramienta aplica y otra elude
Una política solo protege las lecturas que pasan por el componente que la aplica. Trino aplica filtros de filas solo cuando se le indica dónde obtenerlos, así que sin su ajuste opa.policy.row-filters-uri no aplica ningún filtrado de filas (Trino 484, control de acceso con OPA). La especificación del catálogo REST de Iceberg, en la versión 1.12.0, permite que un catálogo devuelva restricciones de lectura junto con una tabla, y establece que "Un lector que admita restricciones de lectura debe fallar cualquier lectura contra la tabla cargada que no pueda aplicar por completo una restricción devuelta" (especificación del catálogo REST, 1.12.0). La especificación ofrece a un lector una señal para el acceso delegado, la cabecera X-Iceberg-Access-Delegation, pero ninguna para las restricciones de lectura. Por eso un catálogo no puede saber qué lectores aplicarán sus restricciones. El cliente REST de PyIceberg 0.12.0 no lee ninguna (código fuente). Recomendamos que un catálogo que devuelva restricciones de lectura conceda acceso al almacenamiento solo a los motores que las apliquen.
La capa de aplicación de políticas limita agent-a05 a EMEA. Sin embargo, la capa tiene rutas que la evitan, porque cualquiera con el acceso del catálogo puede leer los archivos de la tabla. Lee la tabla evitando la capa de dos maneras: con DuckDB a través de lib.warehouse.connect, que la propia capa usa, como lo haría un cuaderno, y con el escaneo propio de PyIceberg, como lo haría cualquier lector que tenga el acceso del catálogo:
1"""The same table, read three ways: through the enforcement layer, and around it with DuckDB and with PyIceberg. The point2rests on the two lines around the layer, which return every region where the layer returns only EMEA's."""3from collections import Counter45from lib import warehouse6from lib.catalog import open_catalog7from lib.enforce import Denied, Enforcer, answer89platform = open_catalog(["crm.learners"])10query = "select support_region, count(*) from crm.learners group by support_region order by support_region"111213def show(rows):14 return ", ".join(f"{region} {learners:,}" for region, learners in rows)151617layer = Enforcer(platform)18print("through the enforcement layer, as agent-a05:", show(answer(layer, query, "agent-a05")))1920# A notebook with DuckDB on the same catalog: the same SQL, and no policy in the way.21print("DuckDB on the same catalog:", show(warehouse.connect(platform).sql(query).fetchall()))2223# Any reader that holds the catalog's access, here PyIceberg's own scan: no SQL to rewrite at all.24scan = platform.load_table("crm.learners").scan(selected_fields=("support_region", "email")).to_arrow()25print("PyIceberg's scan of the table:", show(sorted(Counter(scan.column("support_region").to_pylist()).items())))26print("emails PyIceberg's scan returns:", f"{scan.num_rows - scan.column('email').null_count:,}") # rows whose email isn't null2728# lib.warehouse builds each table's view on a scan it registers under a name of its own. Through the layer, it's denied.29try:30 answer(layer, "select count(*) from scan_crm_learners", "agent-a05")31except Denied as reason:32 print("the layer, asked for the raw scan:", reason)
python read-around-the-layer.pythrough the enforcement layer, as agent-a05: emea 1,581
DuckDB on the same catalog: americas 2,276, apac 1,143, emea 1,581
PyIceberg's scan of the table: americas 2,276, apac 1,143, emea 1,581
emails PyIceberg's scan returns: 5,000
the layer, asked for the raw scan: not a table in the catalog: scan_crm_learners
Un lector fuera de la capa obtiene todas las regiones, porque nunca se consultó la política. A través de la capa, la consulta del agente devuelve emea 1,581. La misma SQL en DuckDB, sin la capa delante, devuelve americas 2,276, apac 1,143, emea 1,581. El escaneo de PyIceberg, que no tiene SQL que reescribir, devuelve americas 2,276, apac 1,143, emea 1,581, con 5,000 correos electrónicos. El mismo rodeo ocurre en producción siempre que un segundo motor, un trabajo de Spark o un script con credenciales de almacenamiento lee los archivos que lee el motor gobernado.
lib.warehouse construye la vista de cada tabla sobre un escaneo que registra con un nombre propio, scan_crm_learners para esta tabla, así que la conexión de la capa también contiene el escaneo sin procesar. La última línea de la salida muestra la respuesta de la capa cuando una consulta nombra ese escaneo: not a table in the catalog: scan_crm_learners. Ese es el diseño que sigue el capítulo 6, que aplica la política en un único lugar y deniega todo lo demás que lea datos, lo que no sea una tabla del catálogo. En producción, ese lugar es el motor al que se conectan las herramientas, como argumenta el capítulo 6. Y como los permisos de almacenamiento forman parte del cumplimiento, solo ese motor y los trabajos que escriben las tablas deberían poder leer los archivos.
Regla práctica: Elige un único lugar que aplique la política, el motor al que consultan todas las herramientas, y concede las credenciales de almacenamiento solo a él y a los trabajos que escriben las tablas, nunca a personas ni a cuadernos. Deniega en ese lugar toda consulta que lea datos sin pasar por una tabla del catálogo. Antes de considerar protegida una tabla, enumera todo lo que puede leer sus archivos, y trata como un rodeo a cualquier lector que no consulte la política, salvo que sea un trabajo cuyas salidas estén catalogadas y clasificadas como las tablas que lee.
Lo que decidió este capítulo
- La gobernanza son cuatro tipos de código en un mismo repositorio: un archivo de metadatos, el código que envía los eventos de linaje de cada trabajo, una política de acceso en Rego y comprobaciones que se ejecutan en cada pull request. Solo uno de ellos es un motor de políticas.
- Cada tabla tiene un equipo propietario, nunca una persona, y cada columna una de cuatro clasificaciones:
public,internal,personalosensitive. Están engovernance/metadata.toml, indexadas por el ID de campo de Iceberg, y el catálogo se prueba contra el archivo recorriendo el catálogo. - Cada ejecución de un pipeline envía eventos de OpenLineage, con el linaje de columnas extraído de su SQL, incluidas las columnas que unen o filtran filas.
- Las decisiones de acceso son datos: permitir, filtros de filas y máscaras de columnas, a partir de una única política que deniega por defecto. Una capa de aplicación las aplica a cada consulta y deniega toda lectura que no corresponda a una tabla del catálogo.
- Los metadatos ausentes fallan en modo cerrado: la política de acceso trata una columna que nadie ha clasificado como
sensitive, y una tabla que nadie ha descrito sigue apareciendo como hallazgo en cada informe hasta que alguien la describa. - El trabajo de gobernanza se ejecuta en cada pull request, falla por los hallazgos que el pull request introduce, e informa de los hallazgos que ya existen en main junto con sus propietarios.
- Todo se ejecuta en un único proceso, sin conexión, sobre los sustitutos enumerados al inicio de este capítulo. La gobernanza hecha de esta forma es un conjunto de reglas pequeñas, cada una comprobada en el punto donde cambian los datos, de modo que una carencia en los metadatos aparece como una comprobación fallida y no como una sorpresa en un informe. Los capítulos siguientes prueban cada regla por turno, sobre las propias tablas de la plataforma.
Este capítulo, en esta edición
Edición 2026.11.31Ejemplos verificados el 19 de nov de 2026Superan la prueba 6 de 6 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.31.