Linaje a partir de pipelines
Unos 31 minutos de lectura, con 11 ejemplos en 11 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
- Envía un evento de ejecución desde cada pipeline
- Traza cada columna de salida hasta sus fuentes
- Add the inputs that decide which rows exist
- Falla con las sentencias que el analizador no puede leer
- Encuentra qué rompe un cambio en una columna
- Proponer clasificaciones a partir del linaje
- Qué falla en producción
- Eventos que nunca llegan
- Un trabajo que nadie instrumentó
- Datos personales en una tabla clasificada como interna
- Lo que decidió este capítulo
Al final de este capítulo podrás capturar el linaje de tus pipelines como eventos de ejecución de OpenLineage, con el linaje de columnas analizado a partir de su SQL, incluidas las columnas que solo se usan en uniones, filtros y agrupaciones. Usarás el grafo que describen esos eventos para saber qué se rompe aguas abajo con un cambio en una columna, y para proponer clasificaciones para tablas que nadie ha clasificado. También tendrás comprobaciones para las tres formas en que falla el linaje en producción: eventos que nunca llegan, un trabajo que no envía ninguno, y una copia de datos personales clasificada con un nivel inferior a personal.
La plataforma de aprendizaje en línea del capítulo 1 construye sus tablas de informes con cuatro pipelines SQL sobre ocho tablas de origen. Cada pipeline es una create table ... as select ... en examples/pipelines/, y el módulo compartido del libro lib.pipelines lo ejecuta sobre DuckDB y escribe el resultado de vuelta en el catálogo:
course_performanceescribeanalytics.course_performance: inscripciones, finalizaciones, valoraciones e ingresos por curso.learner_activityescribeanalytics.learner_activity: los eventos y la última actividad de cada alumno.marketing_audienceescribemarketing.audience: los alumnos a los que marketing puede enviar un correo, con su nombre y su correo electrónico.review_corpusescribeai.review_corpus: el texto de las reseñas en el que se basa el asistente del curso de la plataforma.
La comprobación de metadatos del capítulo 2 encontró que dos de esas salidas, marketing.audience y ai.review_corpus, no tienen ningún metadato: ni propietario, ni clasificación para ninguna columna. Sin embargo, una contiene los nombres y correos electrónicos de los alumnos, y la otra contiene el texto libre de las reseñas, donde el capítulo 3 encontró también nombres y correos electrónicos. De ahí surgen dos preguntas, y el catálogo no puede responder a ninguna de ellas. ¿Qué columnas de esas tablas son datos personales? Y si el equipo de CRM renombra o cambia el formato de crm.learners.email, ¿qué se rompe? Ambas son preguntas de linaje. El linaje indica de dónde proceden los datos de cada columna y adónde van.
Este capítulo añade el módulo compartido del libro para el linaje, lib.lineage. Ejecuta cada pipeline, indica a OpenLineage qué leyó y qué escribió la ejecución, columna por columna, y lee el resultado como un grafo que responde a ambas preguntas.
Envía un evento de ejecución desde cada pipeline
OpenLineage, una especificación abierta para el linaje, lo describe con tres objetos (modelo de objetos). Un job es "un proceso que consume o produce Datasets", como un pipeline. Una ejecución (run) es una ocurrencia de un job, identificada por un UUID que genera el cliente, y la especificación recomienda UUIDv7. Un dataset es una tabla o un archivo, nombrado por un namespace y un nombre que juntos lo identifican. Una ejecución se informa a sí misma mediante eventos de ejecución: un START cuando comienza, y después un evento terminal, COMPLETE, FAIL o ABORT, y un servidor trata los eventos de una misma ejecución como acumulativos (ciclo de ejecución). El linaje procede sobre todo del propio trabajo: un backend conoce los datasets principalmente a partir de la información sobre los jobs.
El cliente de Python, openlineage-python 1.55.0, construye eventos a partir de RunEvent, Run, Job, InputDataset y OutputDataset en openlineage.client.event_v2, y los envía a través de un transporte (documentación del cliente). Incluye transportes HTTP y Kafka para servidores, y un transporte de archivo "diseñado principalmente para pruebas de integración", que, con append configurado, escribe un evento JSON por línea en un único archivo (configuración). El cliente no calcula linaje. Serializa lo que le pasa quien lo llama y añade solo metadatos propios: una faceta de ejecución con su versión, la ubicación de origen del job cuando se ejecuta en un checkout de Git, y las variables de entorno que lo configures para que recoja (emit en client/client.py, openlineage-python). Esto significa que el linaje que llega a un servidor es el que tu código puso en el evento.
lib.lineage.run envuelve a lib.pipelines.run, que ejecuta uno de los cuatro pipelines SQL de la plataforma y escribe su tabla en el catálogo. Envía START con las tablas que lee el SQL como entradas, ejecuta el pipeline y después envía COMPLETE con el dataset de salida y dos facetas sobre él. Una faceta es el nombre que OpenLineage da a un bloque de metadatos adjunto a una ejecución, a un job o a un dataset, y estas dos contienen el esquema de la salida y su linaje de columnas, que la sección siguiente construye. Si el pipeline lanza una excepción, envía FAIL en su lugar, y lib.lineage.run_all ejecuta los cuatro pipelines de esta forma, en un solo archivo de eventos. Los datasets necesitan un namespace, y las convenciones de nombrado de OpenLineage no tienen una entrada para una tabla Iceberg en un catálogo SQL local. La más cercana es el sistema de archivos local, nombrado por su ruta, lo que metería una carpeta de tu máquina en cada evento. Por eso lib.lineage usa el marcador iceberg://platform, con los identificadores del catálogo, como crm.learners, como nombres.
Los ejemplos necesitan los mismos bytes cada vez, pero la hora de un evento y el ID aleatorio de la ejecución cambian por defecto. Aquí lib.lineage marca cada evento con el inicio nominal de la ejecución nocturna en el "hoy" del libro, y deriva el ID de ejecución con generate_static_uuid del cliente, que, según su docstring, "siempre produce el mismo resultado" para la misma hora y los mismos datos: aquí, el nombre del job. Ejecuta los cuatro pipelines con linaje dos veces, en dos archivos, e imprime lo que dicen los eventos del primer archivo, no el JSON sin procesar:
1"""Runs the four pipelines with lineage twice, into two files, and reads back what the first file's events say. The2prose rests on the counts of events and run IDs, on the run facet the client adds, and on the same-bytes check, which3the example asserts."""45from openlineage.client.uuid import generate_new_uuid, generate_static_uuid67from lib import lineage8from lib.catalog import open_catalog9from lib.platform import scratch1011folder = scratch()12catalog = open_catalog()13lineage.run_all(catalog, folder / "first.jsonl")14lineage.run_all(catalog, folder / "second.jsonl") # the same nightly run, sent again15# lib.lineage fixes the event time and derives the run IDs16assert (folder / "first.jsonl").read_bytes() == (folder / "second.jsonl").read_bytes()17events = lineage.read_events(folder / "first.jsonl")1819print("events:", len(events))20for event in events:21 job, state = event["job"]["name"], event["eventType"]22 if state == "START":23 print(f"{job} START, reads:", ", ".join(dataset["name"] for dataset in event["inputs"]))24 else:25 output = event["outputs"][0]26 lineage_fields = output["facets"]["columnLineage"]["fields"]27 print(f"{job} {state}, writes:", output["name"], f"({len(lineage_fields)} columns with lineage)")2829print("event times:", ", ".join(sorted({event["eventTime"] for event in events})))30print("distinct run IDs:", len({event["run"]["runId"] for event in events}))31print("run facets the client added:", ", ".join(events[0]["run"]["facets"]))32print("same bytes when sent again:", (folder / "first.jsonl").read_bytes() == (folder / "second.jsonl").read_bytes())33# generate_new_uuid draws a random UUID each time; generate_static_uuid derives one from its arguments.34print("two random run IDs equal:", generate_new_uuid() == generate_new_uuid())35print("two static run IDs equal:", generate_static_uuid(lineage.NIGHTLY, b"marketing_audience")36 == generate_static_uuid(lineage.NIGHTLY, b"marketing_audience"))
python pipeline-run-events.pyevents: 8
course_performance START, reads: billing.payments, learning.courses, learning.enrollments, learning.reviews
course_performance COMPLETE, writes: analytics.course_performance (7 columns with lineage)
learner_activity START, reads: crm.learners, learning.events
learner_activity COMPLETE, writes: analytics.learner_activity (6 columns with lineage)
marketing_audience START, reads: crm.learners, learning.courses, learning.enrollments
marketing_audience COMPLETE, writes: marketing.audience (5 columns with lineage)
review_corpus START, reads: learning.courses, learning.reviews
review_corpus COMPLETE, writes: ai.review_corpus (5 columns with lineage)
event times: 2026-10-01T02:00:00+00:00
distinct run IDs: 4
run facets the client added: tags
same bytes when sent again: True
two random run IDs equal: False
two static run IDs equal: True
Enviar de nuevo la misma ejecución nominal escribió los mismos bytes, algo que nunca ocurriría con IDs aleatorios, y el ejemplo lo afirma. El primer archivo contiene 8 eventos, un START y un COMPLETE por cada una de las 4 ejecuciones, todos marcados con 2026-10-01T02:00:00+00:00. El START del job marketing_audience nombra las tablas que lee su SQL, crm.learners, learning.courses y learning.enrollments, y su COMPLETE nombra marketing.audience, con linaje para cada columna. Sin embargo, los eventos contienen algo que tú no pusiste: una faceta de ejecución llamada tags, que lleva la versión propia del cliente (registro de cambios, 1.38.0), y la URL _producer de cada faceta también nombra esa versión (DEFAULT_PRODUCER en client/constants.py). Así, los bytes cambian con cada versión del cliente, aunque el linaje no, y una prueba debe comparar lo que dicen los eventos, como hace el resumen de este ejemplo.
Un emisor de producción marca COMPLETE con la hora en que terminó la ejecución. Aun así, vale la pena conservar un ID de ejecución derivado, formado a partir de la hora programada, el nombre del job y el número de intento: un evento enviado dos veces cae entonces en la misma ejecución en lugar de crear una segunda, y un job reintentado obtiene una ejecución propia. Los eventos de producción también deben llevar el ID de snapshot de Iceberg de la salida, en la faceta de dataset version que el modelo de objetos define para ello. El código aquí lo omite, porque PyIceberg 0.12.0 toma cada ID de snapshot de un UUID aleatorio (_generate_snapshot_id en su pyiceberg/table/metadata.py).
Regla práctica: Envía un START y después un evento COMPLETE o FAIL desde el código que ejecuta cada job, de modo que ninguna ejecución ocurra sin ellos, y nombra los datasets por identificadores del catálogo bajo un namespace que tú elijas, nunca por una ruta. En las pruebas, usa el transporte de archivo con una hora de evento fija e IDs de ejecución estáticos, y compara lo que dicen los eventos, nunca sus bytes. En producción, envía a través de un transporte hacia tu servidor de linaje, y deriva cada ID de ejecución a partir de la hora programada, el job y el intento, de modo que un evento reenviado nunca cree una ejecución duplicada.
Traza cada columna de salida hasta sus fuentes
Un evento de ejecución indica qué tablas leyó y escribió un job. El linaje de columnas indica de qué columnas de entrada procede cada columna de salida, y eso es lo que necesita la gobernanza: una tabla que lee crm.learners puede o no copiar sus correos electrónicos. OpenLineage guarda el linaje de columnas en una faceta de conjunto de datos, columnLineage, en la salida: fields asocia cada columna de salida con sus inputFields, y una lista opcional dataset recoge las entradas que afectan a todo el conjunto de datos (esquema de la faceta). Como el cliente no calcula nada de esto, alguien tiene que analizar el SQL de cada job.
sqlglot, un analizador de SQL, lo hace con sqlglot.lineage.lineage. Dada una sentencia y el esquema de las tablas que lee, devuelve, para cada columna de salida, un árbol cuyas hojas son columnas de origen, y con column=None devuelve todas las columnas de salida a la vez (linaje de sqlglot). Necesita el esquema. Sin él, SELECT * devuelve una única salida llamada *, y una columna sin cualificar en un join aparece como un marcador sin tabla. lib.lineage.schema construye el esquema a partir de los metadatos Iceberg del catálogo, de modo que el analizador ve las columnas que tiene el almacén, con sqlglot 30.33.0.
Empecemos por marketing_audience, que alimenta la lista a la que marketing puede enviar correos. En palabras, selecciona los alumnos que aceptaron recibir correos de marketing y cuya cuenta está activa, y añade la categoría de curso favorita de cada uno, que un CTE calcula ordenando las categorías según las matrículas del alumno. Pide a sqlglot el linaje de las salidas del pipeline y de dos columnas de course_performance, para ver qué omite:
1"""What sqlglot.lineage says the pipeline outputs come from, and what it leaves out. The prose rests on the CTE-traced2source of favourite_category, on the sources of the two course performance columns, and on the assertion that neither3column the WHERE reads reaches any output."""4import sqlglot5from sqlglot import exp67from lib import lineage, pipelines8from lib.catalog import open_catalog910# sqlglot resolves each name against the catalog's columns, so lineage.schema builds them from the table metadata.11schema = lineage.schema(open_catalog(["crm.learners", "learning.courses", "learning.enrollments", "learning.reviews",12 "billing.payments"]))13statement = pipelines.sql("marketing_audience")14found = lineage.sqlglot_sources(statement, schema)15for column, sources in found.items():16 print(f"marketing.audience.{column} comes from:", ", ".join(sources))1718parsed = sqlglot.parse_one(statement, read="duckdb")19# the WHERE names columns by alias, as in l.status, so each alias maps to its table20tables = {table.alias_or_name: f"{table.db}.{table.name}" for table in parsed.find_all(exp.Table)}21where = parsed.find(exp.Where)22print("the pipeline's WHERE:", where.this.sql(dialect="duckdb"))23in_lineage = {source for sources in found.values() for source in sources} # every source column of every output24for column in where.find_all(exp.Column):25 source = f"{tables[column.table]}.{column.name}"26 assert source not in in_lineage # every column the WHERE reads, checked against the lineage above27 print(f"{source} in any column's lineage:", source in in_lineage)2829course_performance = lineage.sqlglot_sources(pipelines.sql("course_performance"), schema)30for column in ("completions", "revenue_usd"): # the two aggregates that carry a FILTER inside them31 print(f"analytics.course_performance.{column} comes from:", ", ".join(course_performance[column]))
python sqlglot-misses-row-inputs.pymarketing.audience.learner_id comes from: crm.learners.learner_id
marketing.audience.full_name comes from: crm.learners.full_name
marketing.audience.email comes from: crm.learners.email
marketing.audience.country comes from: crm.learners.country
marketing.audience.favourite_category comes from: learning.courses.category
the pipeline's WHERE: l.marketing_consent AND l.status = 'active'
crm.learners.marketing_consent in any column's lineage: False
crm.learners.status in any column's lineage: False
analytics.course_performance.completions comes from: learning.enrollments.completed_at, learning.enrollments.enrollment_id
analytics.course_performance.revenue_usd comes from: billing.payments.amount, billing.payments.status
Los valores son correctos, pero falta lo que decide qué alumnos están en la tabla. email proviene de crm.learners.email, y favourite_category se rastrea a través del CTE hasta learning.courses.category. El WHERE del pipeline es l.marketing_consent AND l.status = 'active', y ninguna de sus columnas, marketing_consent ni status, aparece en el linaje de ninguna salida. El ejemplo lo afirma en ambos casos. El filtro de consentimiento es la razón por la que marketing puede tener esta tabla, y el linaje no lo menciona. Tampoco menciona las claves de unión de enrollments y courses.
El segundo problema es el inverso: una entrada que solo filtra aparece como si fuera un valor. course_performance suma solo los pagos exitosos, con filter (where p.status = 'succeeded'), y sqlglot indica que revenue_usd procede de billing.payments.amount, billing.payments.status: la columna sumada y la columna que solo decide qué pagos cuentan aparecen igualadas. completions cuenta las matrículas con filter (where e.completed_at is not null), y devuelve lo mismo, a partir de learning.enrollments.completed_at, learning.enrollments.enrollment_id. Ambos problemas se deben a cómo sqlglot construye el árbol. Recoge las columnas de la expresión de cada salida, así que ve un filtro dentro de una expresión y nada fuera de ella, y sus nodos no llevan ningún tipo que indique cómo se usó una entrada.
Regla práctica: Usa el lineage de sqlglot para las columnas de las que se calcula el valor de cada salida, y pasa siempre el esquema del catálogo, generado a partir de los metadatos de la tabla, nunca escrito a mano. No tomes su respuesta como todo aquello de lo que depende una columna: omite las columnas que unen, filtran y agrupan, y no indica cuáles de sus entradas son valores.
Esta parte aún no está traducida, así que está en inglés.
Add the inputs that decide which rows exist
sqlglot's lineage lists the columns a value is computed from, and OpenLineage has a place for the rest. Each input field carries a list of transformations, each with a type, a subtype and a masking flag (column lineage facet). DIRECT means the output value is derived from the input value, through IDENTITY, TRANSFORMATION or AGGREGATION. INDIRECT means the output value is impacted by an input without being derived from it, through JOIN, GROUP_BY, FILTER, SORT, WINDOW or CONDITIONAL. Inputs that shape every row, such as a WHERE, belong in the facet's dataset list.
For governance, the INDIRECT side matters, since information flows through conditions as well as values. Denning calls the information that flows through conditions "implicit flow": a statement that assigns only when a condition holds still tells you the condition's value (Denning, 1976). A row in marketing.audience tells you that learner consented.
lib.lineage.column_lineage adds two things sqlglot's answer lacks: a type for each value input, and the INDIRECT inputs. It types each value input by where the column sits in the output's expression: a bare column is IDENTITY, a column inside an aggregate is AGGREGATION, and anything else is TRANSFORMATION. A column inside an aggregate's FILTER, a window's PARTITION BY or ORDER BY, or a CASE's condition or operand is INDIRECT, and a hash on the way sets masking. COALESCE's arguments count as values: OpenLineage lists COALESCE under CONDITIONAL, but any of its arguments can become the output's value. Then it walks every SELECT in the statement, CTEs included, and collects the columns of its row clauses, following CTE columns back to the tables they come from:
ROW_CLAUSES = {"joins": "JOIN", "where": "FILTER", "group": "GROUP_BY", "having": "FILTER", "qualify": "FILTER",
"order": "SORT"}
Run it on the same pipeline and the same two columns:
1"""The book's column lineage for the marketing audience pipeline and two course performance columns: each input,2with its OpenLineage type and subtype, then the inputs that shape every row. The prose rests on the source counts."""3from lib import lineage, pipelines4from lib.catalog import open_catalog56schema = lineage.schema(open_catalog(["crm.learners", "learning.courses", "learning.enrollments", "learning.reviews",7 "billing.payments"]))8# rows holds the inputs that shape every row, which OpenLineage keeps in the dataset list9fields, rows = lineage.column_lineage(pipelines.sql("marketing_audience"), schema)10for column, inputs in fields.items():11 print(f"marketing.audience.{column}:", ", ".join(f"{dependency.source} {dependency.type} {dependency.subtype}"12 for dependency in inputs))13print("inputs that shape every row of marketing.audience:")14for source in sorted({dependency.source for dependency in rows}):15 print(f" {source}:", "INDIRECT",16 ", ".join(dependency.subtype for dependency in rows if dependency.source == source))1718# the source columns that the output values are computed from19values = {dependency.source for inputs in fields.values() for dependency in inputs}20print("source columns, values only:", len(values))21# A column can both give a value and shape the rows, so the union counts it once.22print("source columns, with the rows' inputs:", len(values | {dependency.source for dependency in rows}))2324fields, _ = lineage.column_lineage(pipelines.sql("course_performance"), schema) # only these two columns are printed25for column in ("completions", "revenue_usd"):26 print(f"analytics.course_performance.{column}:",27 ", ".join(f"{dependency.source} {dependency.type} {dependency.subtype}" for dependency in fields[column]))
python indirect-column-lineage.pymarketing.audience.learner_id: crm.learners.learner_id DIRECT IDENTITY
marketing.audience.full_name: crm.learners.full_name DIRECT IDENTITY
marketing.audience.email: crm.learners.email DIRECT IDENTITY
marketing.audience.country: crm.learners.country DIRECT IDENTITY
marketing.audience.favourite_category: learning.courses.category DIRECT IDENTITY
inputs that shape every row of marketing.audience:
crm.learners.learner_id: INDIRECT JOIN
crm.learners.marketing_consent: INDIRECT FILTER
crm.learners.status: INDIRECT FILTER
learning.courses.category: INDIRECT GROUP_BY, JOIN
learning.courses.course_id: INDIRECT JOIN
learning.enrollments.course_id: INDIRECT JOIN
learning.enrollments.learner_id: INDIRECT GROUP_BY, JOIN
source columns, values only: 5
source columns, with the rows' inputs: 10
analytics.course_performance.completions: learning.enrollments.completed_at INDIRECT FILTER, learning.enrollments.enrollment_id DIRECT AGGREGATION
analytics.course_performance.revenue_usd: billing.payments.amount DIRECT AGGREGATION, billing.payments.status INDIRECT FILTER
The values match sqlglot's, each an IDENTITY copy, and the rows' inputs are the new part. Adding them grows what marketing.audience depends on from 5 source columns to 10. Some row inputs are columns no value uses: marketing_consent and status as FILTER, the two course IDs as JOIN, and the enrollments' learner_id as GROUP_BY and JOIN. crm.learners.learner_id and learning.courses.category, which values copy too, also shape rows: the ID as JOIN, the category as GROUP_BY and JOIN. For revenue_usd, the two inputs are now told apart: amount is a DIRECT AGGREGATION, and status an INDIRECT FILTER. So are the two inputs of completions: enrollment_id is counted, and completed_at only filters.
One more detail: the per-field transformationType and transformationDescription are deprecated, replaced by the per-input transformations that lib.lineage writes (changelog, 1.17.1). And OpenLineage 1.53.0 added a Lineage dataset facet for declared lineage, such as a view's, sent on a DatasetEvent, which consumers should prefer where both describe the same relationship (lineage facet). Run events from jobs carry columnLineage, as the platform's do.
Working rule: Record INDIRECT inputs with every job's column lineage: the join keys, filters and grouping columns of every SELECT, CTEs included, in the facet's dataset list, and type each value input with OpenLineage's subtypes. Expect more edges, many of them join keys. Keep them anyway: a filter on a consent column decides who may be emailed, and it reaches the table only as an INDIRECT input.
Falla con las sentencias que el analizador no puede leer
El linaje de columnas de la plataforma es tan bueno como el análisis en el que se apoya, y un análisis puede ser incorrecto sin fallar. La lineage de sqlglot acepta más que un SELECT: encuentra la consulta dentro de un CREATE TABLE ... AS, de un INSERT ... SELECT o de un CREATE VIEW, y también lee un MERGE (sqlglot, optimizer/scope.py). Tres casos devuelven un resultado que parece correcto. Las salidas de un INSERT se nombran según su SELECT, nunca según las columnas de la tabla. Un MERGE devuelve como resultado la última consulta que sqlglot alcanza dentro de él, como si esa consulta fuera lo que el MERGE escribe. Cuando USING nombra una tabla o un CTE y no sigue ninguna subconsulta, sqlglot no devuelve linaje ni error. Cuando USING es una subconsulta, o una subconsulta aparece en una condición WHEN o en un SET, devuelve las columnas de la última de esas subconsultas, tanto si el MERGE las escribe como si no. Y una columna mal escrita pasa inadvertida cuando no lleva calificador en una consulta sobre una sola tabla: sqlglot la asigna a esa tabla exista o no la columna.
Las cuatro canalizaciones de la plataforma son sentencias CREATE TABLE ... AS. A medida que las tablas crecen, canalizaciones como estas suelen volverse incrementales: un INSERT que añade los ingresos de un día a analytics.daily_revenue, o un MERGE que actualiza analytics.learner_activity en su lugar. Pregunta a sqlglot y a lib.lineage.column_lineage por cada una, el INSERT y el MERGE, este último en dos formas, y compara las respuestas:
1"""sqlglot.lineage's answers for an INSERT and for two MERGE statements, beside the book's lineage: sqlglot names the2INSERT's outputs after its SELECT, and returns nothing or a subquery's columns for a MERGE, which the book refuses. The3prose rests on the sqlglot outputs and on the refusals at the end."""4import pyarrow as pa5from sqlglot.lineage import lineage as sqlglot_lineage67from lib import lineage8from lib.catalog import open_catalog910catalog = open_catalog(["billing.payments", "crm.learners"])11catalog.create_namespace("analytics") # the incremental table, as it exists before the day's INSERT12catalog.create_table("analytics.daily_revenue", schema=pa.schema([("day", pa.date32()), ("revenue_usd", pa.float64())]))13schema = lineage.schema(catalog)14insert = """insert into analytics.daily_revenue15select cast(p.paid_at as date), sum(p.amount) from billing.payments p where p.status = 'succeeded' group by 1"""16merges = {"USING a table": """merge into analytics.learner_activity a using crm.learners l17on a.learner_id = l.learner_id when matched then update set country = l.country""",18 "USING a subquery": """merge into analytics.learner_activity a19using (select l.learner_id, l.country, l.email from crm.learners l) s on a.learner_id = s.learner_id20when not matched then insert (learner_id, country) values (s.learner_id, s.country)"""}2122print("analytics.daily_revenue columns:", ", ".join(schema["analytics"]["daily_revenue"]))23# The SELECT's expressions have no aliases, so sqlglot names each output after the SELECT, not the table. None asks for24# every output column at once.25print("sqlglot, INSERT outputs:", ", ".join(sqlglot_lineage(None, insert, schema, dialect="duckdb")))26fields, rows = lineage.column_lineage(insert, schema)27for column, inputs in fields.items():28 print(f"book, INSERT {column}:", ", ".join(f"{dependency.source} {dependency.type} {dependency.subtype}"29 for dependency in inputs))30print("book, INSERT rows shaped by:", ", ".join(f"{dependency.source} {dependency.subtype}" for dependency in rows))31for label, merge in merges.items():32 outputs = sqlglot_lineage(None, merge, schema, dialect="duckdb")33 print(f"sqlglot, MERGE {label}, outputs:", ", ".join(outputs) or "none")3435# One value too many for daily_revenue's two columns, caught after sqlglot parses it; each MERGE is refused before sqlglot is asked.36refused = {"INSERT with one value too many": insert.replace("sum(p.amount)", "sum(p.amount), count(*)"),37 **{f"MERGE {label}": merge for label, merge in merges.items()}}38for label, statement in refused.items():39 try:40 lineage.column_lineage(statement, schema)41 except lineage.LineageError as error:42 print(f"book, {label}:", error)
python insert-and-merge-lineage.pyanalytics.daily_revenue columns: day, revenue_usd
sqlglot, INSERT outputs: paid_at, _col_1
book, INSERT day: billing.payments.paid_at DIRECT TRANSFORMATION
book, INSERT revenue_usd: billing.payments.amount DIRECT AGGREGATION
book, INSERT rows shaped by: billing.payments.paid_at GROUP_BY, billing.payments.status FILTER
sqlglot, MERGE USING a table, outputs: none
sqlglot, MERGE USING a subquery, outputs: learner_id, country, email
book, INSERT with one value too many: analytics.daily_revenue: the INSERT writes 2 columns, and its SELECT has 3 values
book, MERGE USING a table: analytics.learner_activity: lineage is read only from CREATE ... AS and INSERT ... SELECT, not from MERGE
book, MERGE USING a subquery: analytics.learner_activity: lineage is read only from CREATE ... AS and INSERT ... SELECT, not from MERGE
La tabla analytics.daily_revenue tiene las columnas day, revenue_usd, pero sqlglot nombra las salidas del INSERT como paid_at, _col_1: la primera según la columna dentro del cast, la segunda un nombre generado para una expresión sin alias.
Un INSERT rellena las columnas por posición, así que lib.lineage también las asocia por posición, tomando los nombres del catálogo: las columnas que lista el INSERT, o si no, todas las de la tabla. Así, day proviene de billing.payments.paid_at DIRECT TRANSFORMATION, y la agrupación del INSERT y su filtro sobre status determinan cada fila: billing.payments.paid_at GROUP_BY, billing.payments.status FILTER. Cuando el SELECT tiene más o menos valores que las columnas escritas, lib.lineage lanza un error: analytics.daily_revenue: the INSERT writes 2 columns, and its SELECT has 3 values.
Para el MERGE cuyo USING nombra una tabla, sqlglot devuelve none, y ningún error. Para el que tiene como USING una subconsulta, devuelve learner_id, country, email, aunque ese MERGE solo escribe learner_id y country. Una comprobación de linaje vacío detecta el primero y deja pasar el segundo, así que lib.lineage no valora lo que sqlglot devuelve para un MERGE. Antes de llamar a sqlglot, rechaza toda sentencia que no sea un CREATE ... AS ni un INSERT ... SELECT: analytics.learner_activity: lineage is read only from CREATE ... AS and INSERT ... SELECT, not from MERGE.
Una columna mal escrita, el tercer caso, depende de cómo se escriba la columna. Las canalizaciones de la plataforma califican cada columna con el alias de su tabla, como en l.email, y sqlglot comprueba una columna calificada contra el esquema por sí mismo:
1"""A misspelt column, emial for email, in a query on one table: sqlglot raises when the column is qualified by its2alias, and traces it to the table when it isn't. The prose rests on the sqlglot answer for each form, and on the book's3check against the schema."""4from sqlglot.errors import OptimizeError56from lib import lineage7from lib.catalog import open_catalog89schema = lineage.schema(open_catalog(["crm.learners"])) # the schema lets sqlglot check each column name10# the alias l is right, and only the column name is misspelt11qualified = "create table marketing.audience as select l.learner_id, l.emial from crm.learners l"12# no alias, so nothing names the table the column comes from13unqualified = "create table marketing.audience as select learner_id, emial from crm.learners"1415try:16 lineage.sqlglot_sources(qualified, schema)17except OptimizeError as error:18 print("sqlglot, qualified l.emial:", f"{type(error).__name__}: {error}")19print("sqlglot, unqualified emial comes from:", ", ".join(lineage.sqlglot_sources(unqualified, schema)["emial"]))20try:21 lineage.column_lineage(unqualified, schema)22except lineage.LineageError as error:23 print("book, unqualified emial:", error)
python misspelt-column-lineage.pysqlglot, qualified l.emial: OptimizeError: Unknown column: emial
sqlglot, unqualified emial comes from: crm.learners.emial
book, unqualified emial: crm.learners has no column emial
Un error tipográfico calificado detiene a sqlglot con OptimizeError: Unknown column: emial. Uno sin calificar, en una consulta sobre una sola tabla, devuelve crm.learners.emial: una respuesta segura sobre una columna que no existe. En un join, una columna sin calificar mal escrita no pertenece a ninguna de las tablas, y sqlglot devuelve un marcador de posición sin tabla (sqlglot, lineage.py), que lib.lineage rechaza como una fuente que no puede ubicar. Para el caso de una sola tabla, lib.lineage comprueba cada fuente contra el esquema y lanza crm.learners has no column emial.
lib.lineage.record, que run usa, lee el linaje antes de que se ejecute el trabajo, así que una canalización cuyo linaje no se puede leer falla antes de escribir nada. Es estricto, y es deliberado: un trabajo con linaje vacío desaparecería de todos los informes de impacto y de las comprobaciones de clasificación de este capítulo, y uno con linaje incorrecto los induciría a error. Ejecuta la misma comprobación en la CI en cada pull request que modifique una canalización, para que el fallo aparezca en la revisión y no de noche.
Regla práctica: Trata una sentencia que tu analizador no puede leer correctamente como un error, nunca como linaje vacío o parcial. Rechaza cada tipo de sentencia que interpreta mal, como MERGE, antes de consultarle, y falla con linaje vacío, con una fuente que el analizador no puede ubicar y con una columna que el esquema no tiene. Asocia las columnas de un INSERT por posición con las columnas de la tabla en el catálogo, nunca por los nombres del SELECT, y falla cuando las cantidades no coincidan. Para un MERGE, escribe una SELECT de las columnas que escribe, y registra a partir de ella el linaje del trabajo, como un INSERT ... SELECT hacia la tabla del MERGE, hasta que tu analizador sepa manejar MERGE por sí mismo.
Encuentra qué rompe un cambio en una columna
Con linaje de columnas en cada evento COMPLETE, la plataforma tiene un grafo: las columnas son nodos, y cada campo de entrada es una arista hacia la columna o tabla que alimenta. El análisis de impacto pregunta qué puede romper un cambio en una columna. Recorre ese grafo desde la columna, siguiendo cada arista que sale de ella y continuando desde donde llega cada una, a cualquier profundidad. No se necesita un método especial; es alcanzabilidad en un grafo. Hay una regla específica del linaje. Una arista INDIRECT hacia una tabla significa que cada fila de ella puede cambiar, así que el recorrido continúa desde todas las columnas de esa tabla.
lib.lineage.graph construye el grafo solo a partir del archivo de eventos, como lo haría un servidor de linaje, y no a partir del SQL. Así incluye cada trabajo que envía eventos, sea cual sea el lenguaje en que esté escrito, y nada que no los envíe. lib.lineage.downstream realiza el recorrido.
Tomemos tres cambios que podrían hacer los equipos de la plataforma. El equipo de CRM pasa a minúsculas cada correo electrónico o renombra crm.learners.email. Un nuevo flujo de registro cambia lo que significa crm.learners.marketing_consent para las cuentas antiguas. El equipo de aprendizaje renombra una categoría en learning.courses. Haz una estimación primero: ¿cuántas columnas puede alcanzar el cambio en el consentimiento?
1"""What a change to one source column can break, walked over the column graph that the nightly run's events describe.2The prose rests on the reach counts printed for each column: through values, and in all."""34from lib import lineage5from lib.catalog import open_catalog6from lib.platform import scratch78events_file = scratch() / "events.jsonl"9lineage.run_all(open_catalog(), events_file)10graph = lineage.graph(lineage.read_events(events_file)) # built from the events alone, as a lineage server would11print("edges in the column graph:", len(graph.edges))1213for column in ("crm.learners.email", "crm.learners.marketing_consent", "learning.courses.category"):14 reached = lineage.downstream(graph, column)15 print(f"{column} reaches:")16 # dict.fromkeys drops repeated targets and keeps the order they were found in17 for target in dict.fromkeys(edge.target for edge in reached):18 how = ", ".join(f"{edge.type} {edge.subtype}" for edge in reached if edge.target == target)19 # a table's name has one dot and a column's two, so a table target means every row of it20 print(f" {target}{', every row' if target.count('.') == 1 else ''}:", how)21 values = [edge for edge in reached if edge.type == "DIRECT"] # only DIRECT edges copy values22 print(f"{column}, columns reached through values:", len(lineage.columns_reached(graph, values)))23 print(f"{column}, columns reached in all:", len(lineage.columns_reached(graph, reached)))
python column-impact.pyedges in the column graph: 51
crm.learners.email reaches:
marketing.audience.email: DIRECT IDENTITY
crm.learners.email, columns reached through values: 1
crm.learners.email, columns reached in all: 1
crm.learners.marketing_consent reaches:
marketing.audience, every row: INDIRECT FILTER
crm.learners.marketing_consent, columns reached through values: 0
crm.learners.marketing_consent, columns reached in all: 5
learning.courses.category reaches:
analytics.course_performance, every row: INDIRECT GROUP_BY
analytics.course_performance.category: DIRECT IDENTITY
marketing.audience, every row: INDIRECT GROUP_BY, INDIRECT JOIN
marketing.audience.favourite_category: DIRECT IDENTITY
learning.courses.category, columns reached through values: 2
learning.courses.category, columns reached in all: 12
El consentimiento es la sorpresa. Un cambio en él alcanza 0 columnas a través de valores, pero a través de su filtro alcanza las 5 columnas de marketing.audience, porque cambia a quién se le envía correo. Una herramienta de linaje que solo mire valores informaría que un cambio en el consentimiento no tiene impacto.
Un cambio en email alcanza 1 columna, marketing.audience.email, así que renombrarla rompe la canalización de marketing y ningún otro trabajo que envíe linaje. Un cambio de nombre de categoría alcanza 2 columnas a través de valores, y 12 en total, porque las categorías también agrupan analytics.course_performance y clasifican la categoría favorita de cada estudiante.
El mismo recorrido sirve a dos capítulos posteriores: capítulo 7 sigue las columnas de un estudiante hacia abajo para encontrar cada tabla derivada que un borrado debe alcanzar, y capítulo 10 escribe un informe de impacto para cada pull request que cambie un esquema.
Regla práctica: Ejecuta el análisis de impacto sobre el grafo construido a partir de eventos, incluidas las aristas INDIRECT, e informa de dos listas: columnas cuyos valores pueden cambiar, y tablas cuyas filas pueden cambiar. Trata un cambio en una columna usada solo en filtros y uniones como un cambio en cada columna de las tablas que filtra, y envía el informe a los responsables de cada tabla que alcance.
Proponer clasificaciones a partir del linaje
Una columna derivada contiene datos de sus entradas, así que su clasificación puede derivarse de las de ellas. La regla clásica proviene del modelo de retículo de flujo de información de Denning: la clase de un valor calculado a partir de varias entradas es la cota superior mínima, la «unión» (join), de sus clases (Denning, 1976). Las clasificaciones de la plataforma forman una línea, public, internal, personal y sensitive, así que la unión es la más estricta de ellas, que stricter devuelve en lib.metadata, el módulo de metadatos del libro. Qué entradas cuentan es una cuestión de criterio. Contamos también las entradas INDIRECT, siguiendo los flujos implícitos de Denning, porque una tabla filtrada por consentimiento revela el consentimiento de cada estudiante. Esa elección vive en governance/lineage.toml, de modo que un equipo puede cambiarla en una sola línea revisada.
Otras dos decisiones se derivan de la misma cautela. La marca masking de OpenLineage indica solo que un valor fue ofuscado, por ejemplo mediante un hash (faceta de linaje de columna). Si un identificador con hash sigue siendo un dato personal es una cuestión jurídica: el capítulo 2 cita el considerando del RGPD sobre datos seudonimizados y deja la respuesta en manos de los abogados. Por eso la regla del libro nunca rebaja una clasificación por causa del enmascaramiento. Los servidores de catálogo también dejan la elección a la configuración. Apache Atlas propaga clasificaciones a lo largo del linaje y puede bloquearlo en una arista, por ejemplo cuando una vista enmascara una columna PII (Atlas). DataHub propaga términos de glosario a lo largo del linaje de columna, una función que su documentación 1.7.0 describe como beta pública en DataHub Cloud (DataHub). Una propuesta es un mínimo, no un veredicto: como los borradores que escribe un modelo local en el capítulo 2, se revisa antes de entrar en governance/metadata.toml, el archivo de la plataforma con propietarios y clasificaciones.
lib.lineage.propose propone una clasificación para cada columna que escribió un trabajo, y lib.metadata.problems enumera las tablas que necesitan una. Comprueba la regla con las dos tablas que sí clasificaron las personas, analytics.course_performance y analytics.learner_activity, antes de confiar en ella con marketing.audience y ai.review_corpus, las dos que no tienen metadatos:
1"""Proposes classifications from lineage for the columns with no declared one, then checks the rule against the columns2people did classify. The prose rests on the personal count, on the reproduced counts, and on the check that no declared class is lower."""34from lib import lineage, metadata5from lib.catalog import open_catalog6from lib.platform import scratch78catalog = open_catalog()9events_file = scratch() / "events.jsonl"10lineage.run_all(catalog, events_file)11for problem in metadata.problems(catalog, metadata.load()):12 print("metadata problem:", problem)1314graph, known = lineage.graph(lineage.read_events(events_file)), lineage.declared() # known: governance/metadata.toml15print("propagated through:", " and ".join(lineage.rules()["propagate_through"])) # from governance/lineage.toml16proposed = lineage.propose(graph, known)17for column, (classification, decided_by) in proposed.items():18 if column not in known:19 first = decided_by[0] # lib sorts the deciding edges DIRECT first, so this is a value when one decides20 print(f"{column}: {classification}, from {first.source} ({first.type} {first.subtype})")21print("personal columns proposed:", sum(1 for column, (classification, _) in proposed.items()22 if column not in known and classification == "personal"))2324classified = [column for column in proposed if column in known]25print("declared classifications checked:", len(classified))26print("classes declared for them:", ", ".join(sorted({known[column] for column in classified})))27for through in (["DIRECT", "INDIRECT"], ["DIRECT"]):28 proposals = lineage.propose(graph, known, through)29 agree = sum(1 for column in classified if proposals[column][0] == known[column])30 print(f"declared classifications reproduced, through {' and '.join(through)}:", f"{agree} of {len(classified)}")31# proposals is the DIRECT-only run from the loop above32missed = [column for column in classified if proposals[column][0] != known[column]]33print("missed with DIRECT inputs only:", len(missed))34for column in missed:35 print(f" {column}: declared {known[column]}, DIRECT inputs propose {proposals[column][0]}")36print("declared less protected than lineage proposes:", len(lineage.understated(proposed, known)))37assert not lineage.understated(proposed, known)
python propagate-classifications.pymetadata problem: ai.review_corpus: no metadata
metadata problem: marketing.audience: no metadata
propagated through: DIRECT and INDIRECT
marketing.audience.learner_id: internal, from crm.learners.learner_id (DIRECT IDENTITY)
marketing.audience.full_name: personal, from crm.learners.full_name (DIRECT IDENTITY)
marketing.audience.email: personal, from crm.learners.email (DIRECT IDENTITY)
marketing.audience.country: internal, from crm.learners.country (DIRECT IDENTITY)
marketing.audience.favourite_category: internal, from crm.learners.learner_id (INDIRECT JOIN)
ai.review_corpus.review_id: internal, from learning.reviews.review_id (DIRECT IDENTITY)
ai.review_corpus.course_id: internal, from learning.reviews.course_id (DIRECT IDENTITY)
ai.review_corpus.course_title: internal, from learning.reviews.course_id (INDIRECT JOIN)
ai.review_corpus.rating: internal, from learning.reviews.rating (DIRECT IDENTITY)
ai.review_corpus.body: personal, from learning.reviews.body (DIRECT IDENTITY)
personal columns proposed: 3
declared classifications checked: 13
classes declared for them: internal
declared classifications reproduced, through DIRECT and INDIRECT: 13 of 13
declared classifications reproduced, through DIRECT: 10 of 13
missed with DIRECT inputs only: 3
analytics.course_performance.course_id: declared internal, DIRECT inputs propose public
analytics.course_performance.title: declared internal, DIRECT inputs propose public
analytics.course_performance.category: declared internal, DIRECT inputs propose public
declared less protected than lineage proposes: 0
La comprobación de metadatos del capítulo 2 sigue informando de las dos tablas sin metadatos, y el linaje propone una clasificación para cada una de sus columnas. Propone 3 columnas personales: full_name y email en marketing.audience, cada una una copia IDENTITY de una columna personal de crm.learners, y body en ai.review_corpus, una copia del texto libre de las reseñas. El resto sale como internal, incluida favourite_category, para la que el ejemplo imprime internal, from crm.learners.learner_id (INDIRECT JOIN). Sus valores son nombres públicos de categorías del catálogo de cursos, pero las filas en que aparecen se eligen mediante un join por identificadores de estudiante y un filtro de consentimiento, así que son internal.
Contar las entradas INDIRECT reproduce las clasificaciones declaradas en las columnas que sí clasificaron las personas, 13 of 13, y todas ellas son internal.
Solo las entradas DIRECT reproducen 10 of 13, y fallan en 3: course_id, title y category de analytics.course_performance. Una regla solo DIRECT las califica como public, como en el catálogo de cursos, mientras que el equipo de analítica eligió internal. Así que la regla propone no menos de lo que eligieron las personas aquí, y el linaje no encuentra ninguna clasificación declarada inferior a su propuesta. Es una evidencia débil: una regla que propusiera internal para cada columna obtendría la misma puntuación. Y tampoco puede mostrar qué hace la regla con un filtro personal, ya que ninguno de los filtros o joins de la plataforma lee una columna personal: incluso marketing_consent está clasificada como internal.
Por eso construye una tabla cuyo filtro sí lo haga. Para una oferta de cumpleaños, marketing quiere a los estudiantes que dieron su consentimiento y nacieron este mes, con su identificador y su país, y nada más:
1"""A birthday-offer table whose only personal input is a filter on date of birth. The prose rests on the learner count,2and on the proposals counting DIRECT inputs alone and counting DIRECT and INDIRECT inputs."""34from lib import lineage5from lib.catalog import open_catalog6from lib.platform import scratch7from lib.warehouse import connect89catalog = open_catalog(["crm.learners"])10# The consenting learners born in the month of the nightly run, on the book's "today".11select = ("select l.learner_id, l.country from crm.learners l "12 f"where l.marketing_consent and month(l.date_of_birth) = {lineage.NIGHTLY.month}")131415def offers() -> None:16 rows = connect(catalog).sql(select).to_arrow_table()17 catalog.create_namespace_if_not_exists("marketing")18 catalog.create_table("marketing.birthday_offers", schema=rows.schema).append(rows)192021events_file = scratch() / "events.jsonl"22# record derives the lineage from this statement, and reads it before offers() runs23lineage.record(lineage.client(events_file), "birthday_offers", f"create table marketing.birthday_offers as {select}",24 catalog, offers)25offers_table = catalog.load_table("marketing.birthday_offers").scan().to_arrow()26print("learners in marketing.birthday_offers:", f"{len(offers_table):,}")2728graph, known = lineage.graph(lineage.read_events(events_file)), lineage.declared()29print("crm.learners.date_of_birth declared:", known["crm.learners.date_of_birth"])30for through in (["DIRECT", "INDIRECT"], ["DIRECT"]):31 for column, (classification, decided_by) in lineage.propose(graph, known, through).items():32 label = f"{column}, through {' and '.join(through)}"33 print(f"{label}:", classification)34 print(f"{label}, decided by:", f"{decided_by[0].source} ({decided_by[0].type} {decided_by[0].subtype})")
python personal-filter-propagates.pylearners in marketing.birthday_offers: 165
crm.learners.date_of_birth declared: personal
marketing.birthday_offers.learner_id, through DIRECT and INDIRECT: personal
marketing.birthday_offers.learner_id, through DIRECT and INDIRECT, decided by: crm.learners.date_of_birth (INDIRECT FILTER)
marketing.birthday_offers.country, through DIRECT and INDIRECT: personal
marketing.birthday_offers.country, through DIRECT and INDIRECT, decided by: crm.learners.date_of_birth (INDIRECT FILTER)
marketing.birthday_offers.learner_id, through DIRECT: internal
marketing.birthday_offers.learner_id, through DIRECT, decided by: crm.learners.learner_id (DIRECT IDENTITY)
marketing.birthday_offers.country, through DIRECT: internal
marketing.birthday_offers.country, through DIRECT, decided by: crm.learners.country (DIRECT IDENTITY)
Ninguna de las columnas copia nada personal, pero cada fila indica que su estudiante nació en el mes de la oferta, parte de una fecha de nacimiento. La tabla contiene 165 estudiantes, y governance/metadata.toml clasifica la fecha de nacimiento como personal. Contar solo las entradas DIRECT propone internal para learner_id y internal para country.
Añade las entradas INDIRECT, y propone personal para learner_id y personal para country, ambas decididas por crm.learners.date_of_birth (INDIRECT FILTER). Ese es el caso para el que sirven las entradas INDIRECT, y también muestra el coste: un único filtro personal hace personal cada columna de una tabla.
OpenLineage puede llevar clasificaciones en los propios eventos, con la faceta de conjunto de datos Tags, cuya clave field «identifica el campo de un conjunto de datos si una etiqueta se aplica a uno» (faceta tags, schema). En cambio, nosotros las guardamos en governance/metadata.toml, la única fuente que también leen las políticas de acceso de la plataforma, a través de lib.policy, el módulo de políticas del libro (capítulo 5).
Regla práctica: Propón la clasificación de cada columna derivada como la más estricta de las de sus entradas, contando las entradas INDIRECT, y envía las propuestas al propietario de la tabla para su revisión antes de que se conviertan en metadatos. Nunca dejes que el linaje rebaje una clasificación que alguien declaró, y nunca trates el enmascaramiento como desclasificación. Cuenta solo las entradas DIRECT si tus pipelines suelen hacer joins o filtros sobre columnas personales, como emparejar por correo electrónico, y de otro modo todas las salidas saldrían como personales; en ese caso, revisa a mano las entradas personales INDIRECT.
Qué falla en producción
El linaje falla en silencio: una arista que falta parece exactamente igual que una columna sin dependencias, y todas las comprobaciones construidas sobre el grafo, desde el análisis de impacto hasta las clasificaciones propuestas, pasan entonces sin problemas. Tres fallos son comunes, y cada uno tiene su comprobación.
Eventos que nunca llegan
El cliente lee OPENLINEAGE_DISABLED del entorno, y cuando vale true, los eventos se descartan (configuración). En el código fuente del cliente, esa comprobación va primero (openlineage-python, client/client.py): antes de revisar el transporte que pasaste explícitamente, el cliente elige un transporte que no hace nada. Su único aviso es una línea de registro INFO: "OpenLineage is disabled. No events will be emitted." El registrador raíz de Python está configurado en WARNING por defecto, así que esa línea nunca se muestra (guía de logging). Basta con que una variable quede en un archivo de entorno compartido después de depurar. Define la variable, ejecuta review_corpus con un transporte de archivo explícito y comprueba qué llega al archivo:
1"""With OPENLINEAGE_DISABLED=true in the environment, an explicit file transport writes nothing and raises nothing. The2prose rests on the transport the client chose and on the job the check finds without a COMPLETE event."""3import os45from lib import lineage6from lib.catalog import open_catalog7from lib.platform import scratch89os.environ["OPENLINEAGE_DISABLED"] = "true" # say, left in a shared environment file after a debugging session1011events_file = scratch() / "events.jsonl"12client = lineage.client(events_file) # a file transport, passed in explicitly13catalog = open_catalog(["learning.courses", "learning.reviews"])14output = lineage.run(catalog, "review_corpus", client)1516print("transport the client chose:", client.transport.kind) # OPENLINEAGE_DISABLED wins over the transport passed in17print("pipeline wrote:", output)18print("rows written:", f"{len(catalog.load_table(output).scan().to_arrow()):,}")19assert not events_file.exists() # the noop transport never creates the file20print("events file exists:", events_file.exists())21missing = lineage.missing_runs(["review_corpus"], lineage.read_events(events_file)) # ran, but sent no COMPLETE22print("jobs that ran with no COMPLETE event:", ", ".join(missing))
python lineage-disabled-silently.pytransport the client chose: noop
pipeline wrote: ai.review_corpus
rows written: 3,000
events file exists: False
jobs that ran with no COMPLETE event: review_corpus
Con la variable definida, el pipeline sigue ejecutándose, pero nada llega al archivo. El cliente eligió el transporte noop en lugar del transporte de archivo que pasó el código, y el pipeline escribió 3,000 filas en ai.review_corpus sin error y sin archivo de eventos. La comprobación que lo detecta compara los trabajos que ejecutó el planificador con los trabajos que enviaron un evento COMPLETE: lib.lineage.missing_runs muestra review_corpus como trabajos que se ejecutaron sin uno.
Regla práctica: Después de cada ejecución programada, compara los trabajos que se ejecutaron con los trabajos cuyos eventos COMPLETE llegaron, y genera una alerta ante cualquier diferencia. No confíes en que el emisor informe su propio silencio.
Un trabajo que nadie instrumentó
El linaje cubre solo los trabajos que lo envían. El equipo de marketing de la plataforma ejecuta cada semana un script de Python que copia marketing.audience en marketing.campaign_list, una tabla que lee su herramienta de correo electrónico. Nadie conectó el script a OpenLineage:
1"""A Python step copies marketing.audience for the email tool and sends no lineage. The prose rests on the walk from the2email column, which misses the copy, and on the catalog check against the lineage, which finds it."""34from lib import lineage5from lib.catalog import open_catalog6from lib.platform import scratch7from lib.warehouse import connect89catalog = open_catalog()10events_file = scratch() / "events.jsonl"11lineage.run_all(catalog, events_file)1213# The marketing team's weekly export, written straight to the catalog: no lineage event.14export = connect(catalog).sql("select learner_id, full_name, email from marketing.audience").to_arrow_table()15catalog.create_table("marketing.campaign_list", schema=export.schema).append(export)16print("rows exported:", f"{len(export):,}")1718events = lineage.read_events(events_file)19reached = lineage.downstream(lineage.graph(events), "crm.learners.email")20print("crm.learners.email reaches:", ", ".join(edge.target for edge in reached))21# the catalog's tables, less the platform's sources and the outputs the events name22print("tables no job's lineage accounts for:", ", ".join(lineage.unaccounted(catalog, events)))
python uninstrumented-job.pyrows exported: 1,829
crm.learners.email reaches: marketing.audience.email
tables no job's lineage accounts for: marketing.campaign_list
Una exportación que no envía eventos es invisible para el análisis de impacto. El script copió los nombres y correos electrónicos de 1,829 estudiantes, pero crm.learners.email sigue llegando solo a marketing.audience.email, de modo que una eliminación guiada por este linaje omitiría la copia. Sin embargo, el catálogo sabe que la tabla existe, así que lib.lineage.unaccounted compara las tablas del catálogo con el linaje: cada tabla debe ser una de las fuentes de la plataforma o la salida de un trabajo que el linaje conoce. Encuentra marketing.campaign_list.
Regla práctica: Compara el catálogo con el linaje de manera programada, y trata una tabla que ningún linaje de trabajo explica como un incidente: encuentra el trabajo y haz que envíe eventos.
Datos personales en una tabla clasificada como interna
Instrumentar la exportación del equipo de marketing corrige el grafo y deja al descubierto un segundo problema. Cuando el propietario de la exportación creó marketing.campaign_list, clasificó todas las columnas como internas, porque solo el equipo de marketing las lee. Eso es una afirmación sobre quién lee una tabla, no sobre lo que contiene. Envuelve el trabajo del script en lib.lineage.record, con el SELECT con el que se ejecuta como su linaje, y compara las clasificaciones declaradas con la propuesta del linaje:
1"""The same export, now recorded with lineage, into a table its owner tagged internal. The prose rests on the walk to2the copy and on the check for understated classifications."""34from lib import lineage5from lib.catalog import open_catalog6from lib.platform import scratch7from lib.warehouse import connect89catalog = open_catalog()10events_file = scratch() / "events.jsonl"11lineage.run_all(catalog, events_file)1213select = "select a.learner_id, a.full_name, a.email from marketing.audience a"141516def export() -> None:17 rows = connect(catalog).sql(select).to_arrow_table()18 catalog.create_table("marketing.campaign_list", schema=rows.schema).append(rows)192021# record reads this statement's lineage before export() runs22statement = f"create table marketing.campaign_list as {select}"23lineage.record(lineage.client(events_file), "campaign_export", statement, catalog, export)2425# Its owner tagged every column internal: "only the marketing team reads it".26known = lineage.declared() | {f"marketing.campaign_list.{c}": "internal" for c in ("learner_id", "full_name", "email")}27graph = lineage.graph(lineage.read_events(events_file))28print("crm.learners.email reaches:", ", ".join(edge.target for edge in lineage.downstream(graph, "crm.learners.email")))29for problem in lineage.understated(lineage.propose(graph, known), known):30 print("understated:", problem)
python personal-copy-tagged-internal.pycrm.learners.email reaches: marketing.audience.email, marketing.campaign_list.email
understated: marketing.campaign_list.full_name: declared internal, lineage proposes personal
understated: marketing.campaign_list.email: declared internal, lineage proposes personal
Una vez que la exportación envía su linaje, el recorrido alcanza su copia: crm.learners.email llega a marketing.audience.email, marketing.campaign_list.email, dos saltos, el segundo a través de la exportación. Y lib.lineage.understated informa de full_name y email en marketing.campaign_list como declarados internos, mientras que el linaje propone personal: son copias de datos personales que cualquier política que lea la clasificación declarada trataría como interna.
Regla práctica: Ejecuta lib.lineage.understated, o tu propia comprobación similar, en cada actualización del linaje, y falla cuando una clasificación declarada sea inferior a la que propone el linaje. Clasifica según lo que contiene una tabla, nunca según quién la lee, y corrige un hallazgo de este tipo elevando la clasificación, no eliminando la arista.
Lo que decidió este capítulo
- Cada ejecución del pipeline envía eventos de ejecución de OpenLineage, START y después COMPLETE o FAIL, desde el código que la ejecuta (
lib.lineage.run), con el esquema de la salida y el linaje de columnas. Los datasets se nombran mediante identificadores del catálogo bajo el namespace provisionaliceberg://platform. Los ejemplos fijan las horas de los eventos y derivan los IDs de ejecución a partir de la ejecución nominal, y comparan lo que dicen los eventos, no sus bytes. - El linaje de columnas es el linaje de valores de sqlglot, tipado como subtipos de OpenLineage, más las entradas INDIRECT: las columnas de unión, filtro, agrupación y orden de cada
SELECT, incluidos los CTE, en la listadatasetde la faceta. - Un linaje que no puede leerse correctamente es un error, nunca vacío ni parcial.
lib.lineagesolo leeCREATE ... ASyINSERT ... SELECT, rechaza cualquier otra sentencia, incluidaMERGE, sea cual sea lo que nombre suUSING. El linaje vacío, una fuente no ubicable o una columna desconocida detienen el trabajo antes de que se ejecute. Las columnas de unINSERTprovienen del esquema de la tabla en el catálogo, emparejadas por posición, y un número distinto de columnas es un error. - El análisis de impacto recorre el grafo construido a partir de los eventos, incluidas las aristas INDIRECT, e informa de las columnas cuyos valores pueden cambiar y de las tablas cuyas filas pueden cambiar.
- Las clasificaciones se propagan como la más estricta de todas las entradas, DIRECT e INDIRECT, tal como se establece en
governance/lineage.toml, de modo que una tabla elegida por un filtro personal se propone como personal. El linaje nunca rebaja una clasificación declarada, y el enmascaramiento nunca la desclasifica. Las propuestas para las dos tablas sin clasificar,full_name,emailybodycomo personales y todas las demás columnas como internas, se envían a sus propietarios para revisión antes de entrar engovernance/metadata.toml. - Tres comprobaciones protegen el propio linaje: trabajos que se ejecutaron sin ningún evento COMPLETE, tablas que ningún linaje de trabajo explica y clasificaciones declaradas inferiores a las que propone el linaje. Un grafo de linaje solo es tan completo como sus eventos, y una arista que falta se parece exactamente a una columna sin dependencias.
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.