Linaje a partir de pipelines

Unos 31 minutos de lectura, con 11 ejemplos en 11 secciones.

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

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

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

Al final de este capítulo podrás 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_performance escribe analytics.course_performance: inscripciones, finalizaciones, valoraciones e ingresos por curso.
  • learner_activity escribe analytics.learner_activity: los eventos y la última actividad de cada alumno.
  • marketing_audience escribe marketing.audience: los alumnos a los que marketing puede enviar un correo, con su nombre y su correo electrónico.
  • review_corpus escribe ai.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

Último cambio en la edición 2026.11.27

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:

pipeline-run-events.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Superado
"""Runs the four pipelines with lineage twice, into two files, and reads back what the first file's events say. Theprose rests on the counts of events and run IDs, on the run facet the client adds, and on the same-bytes check, whichthe example asserts."""from openlineage.client.uuid import generate_new_uuid, generate_static_uuidfrom lib import lineagefrom lib.catalog import open_catalogfrom lib.platform import scratchfolder = scratch()catalog = open_catalog()lineage.run_all(catalog, folder / "first.jsonl")lineage.run_all(catalog, folder / "second.jsonl")          # the same nightly run, sent again# lib.lineage fixes the event time and derives the run IDsassert (folder / "first.jsonl").read_bytes() == (folder / "second.jsonl").read_bytes()events = lineage.read_events(folder / "first.jsonl")print("events:", len(events))for event in events:    job, state = event["job"]["name"], event["eventType"]    if state == "START":        print(f"{job} START, reads:", ", ".join(dataset["name"] for dataset in event["inputs"]))    else:        output = event["outputs"][0]        lineage_fields = output["facets"]["columnLineage"]["fields"]        print(f"{job} {state}, writes:", output["name"], f"({len(lineage_fields)} columns with lineage)")print("event times:", ", ".join(sorted({event["eventTime"] for event in events})))print("distinct run IDs:", len({event["run"]["runId"] for event in events}))print("run facets the client added:", ", ".join(events[0]["run"]["facets"]))print("same bytes when sent again:", (folder / "first.jsonl").read_bytes() == (folder / "second.jsonl").read_bytes())# generate_new_uuid draws a random UUID each time; generate_static_uuid derives one from its arguments.print("two random run IDs equal:", generate_new_uuid() == generate_new_uuid())print("two static run IDs equal:", generate_static_uuid(lineage.NIGHTLY, b"marketing_audience")      == generate_static_uuid(lineage.NIGHTLY, b"marketing_audience"))
Salidapython pipeline-run-events.py
events: 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

Último cambio en la edición 2026.11.30

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:

sqlglot-misses-row-inputs.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Superado
"""What sqlglot.lineage says the pipeline outputs come from, and what it leaves out. The prose rests on the CTE-tracedsource of favourite_category, on the sources of the two course performance columns, and on the assertion that neithercolumn the WHERE reads reaches any output."""import sqlglotfrom sqlglot import expfrom lib import lineage, pipelinesfrom lib.catalog import open_catalog# sqlglot resolves each name against the catalog's columns, so lineage.schema builds them from the table metadata.schema = lineage.schema(open_catalog(["crm.learners", "learning.courses", "learning.enrollments", "learning.reviews",                                      "billing.payments"]))statement = pipelines.sql("marketing_audience")found = lineage.sqlglot_sources(statement, schema)for column, sources in found.items():    print(f"marketing.audience.{column} comes from:", ", ".join(sources))parsed = sqlglot.parse_one(statement, read="duckdb")# the WHERE names columns by alias, as in l.status, so each alias maps to its tabletables = {table.alias_or_name: f"{table.db}.{table.name}" for table in parsed.find_all(exp.Table)}where = parsed.find(exp.Where)print("the pipeline's WHERE:", where.this.sql(dialect="duckdb"))in_lineage = {source for sources in found.values() for source in sources}     # every source column of every outputfor column in where.find_all(exp.Column):    source = f"{tables[column.table]}.{column.name}"    assert source not in in_lineage        # every column the WHERE reads, checked against the lineage above    print(f"{source} in any column's lineage:", source in in_lineage)course_performance = lineage.sqlglot_sources(pipelines.sql("course_performance"), schema)for column in ("completions", "revenue_usd"):    # the two aggregates that carry a FILTER inside them    print(f"analytics.course_performance.{column} comes from:", ", ".join(course_performance[column]))
Salidapython sqlglot-misses-row-inputs.py
marketing.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

Último cambio en la edición 2026.11.31

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:

indirect-column-lineage.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Superado
"""The book's column lineage for the marketing audience pipeline and two course performance columns: each input,with its OpenLineage type and subtype, then the inputs that shape every row. The prose rests on the source counts."""from lib import lineage, pipelinesfrom lib.catalog import open_catalogschema = lineage.schema(open_catalog(["crm.learners", "learning.courses", "learning.enrollments", "learning.reviews",                                      "billing.payments"]))# rows holds the inputs that shape every row, which OpenLineage keeps in the dataset listfields, rows = lineage.column_lineage(pipelines.sql("marketing_audience"), schema)for column, inputs in fields.items():    print(f"marketing.audience.{column}:", ", ".join(f"{dependency.source} {dependency.type} {dependency.subtype}"                                                    for dependency in inputs))print("inputs that shape every row of marketing.audience:")for source in sorted({dependency.source for dependency in rows}):    print(f"  {source}:", "INDIRECT",          ", ".join(dependency.subtype for dependency in rows if dependency.source == source))# the source columns that the output values are computed fromvalues = {dependency.source for inputs in fields.values() for dependency in inputs}print("source columns, values only:", len(values))# A column can both give a value and shape the rows, so the union counts it once.print("source columns, with the rows' inputs:", len(values | {dependency.source for dependency in rows}))fields, _ = lineage.column_lineage(pipelines.sql("course_performance"), schema)   # only these two columns are printedfor column in ("completions", "revenue_usd"):    print(f"analytics.course_performance.{column}:",          ", ".join(f"{dependency.source} {dependency.type} {dependency.subtype}" for dependency in fields[column]))
Salidapython indirect-column-lineage.py
marketing.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

Último cambio en la edición 2026.11.27

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:

insert-and-merge-lineage.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Superado
"""sqlglot.lineage's answers for an INSERT and for two MERGE statements, beside the book's lineage: sqlglot names theINSERT's outputs after its SELECT, and returns nothing or a subquery's columns for a MERGE, which the book refuses. Theprose rests on the sqlglot outputs and on the refusals at the end."""import pyarrow as pafrom sqlglot.lineage import lineage as sqlglot_lineagefrom lib import lineagefrom lib.catalog import open_catalogcatalog = open_catalog(["billing.payments", "crm.learners"])catalog.create_namespace("analytics")             # the incremental table, as it exists before the day's INSERTcatalog.create_table("analytics.daily_revenue", schema=pa.schema([("day", pa.date32()), ("revenue_usd", pa.float64())]))schema = lineage.schema(catalog)insert = """insert into analytics.daily_revenueselect cast(p.paid_at as date), sum(p.amount) from billing.payments p where p.status = 'succeeded' group by 1"""merges = {"USING a table": """merge into analytics.learner_activity a using crm.learners lon a.learner_id = l.learner_id when matched then update set country = l.country""",          "USING a subquery": """merge into analytics.learner_activity ausing (select l.learner_id, l.country, l.email from crm.learners l) s on a.learner_id = s.learner_idwhen not matched then insert (learner_id, country) values (s.learner_id, s.country)"""}print("analytics.daily_revenue columns:", ", ".join(schema["analytics"]["daily_revenue"]))# The SELECT's expressions have no aliases, so sqlglot names each output after the SELECT, not the table. None asks for# every output column at once.print("sqlglot, INSERT outputs:", ", ".join(sqlglot_lineage(None, insert, schema, dialect="duckdb")))fields, rows = lineage.column_lineage(insert, schema)for column, inputs in fields.items():    print(f"book, INSERT {column}:", ", ".join(f"{dependency.source} {dependency.type} {dependency.subtype}"                                               for dependency in inputs))print("book, INSERT rows shaped by:", ", ".join(f"{dependency.source} {dependency.subtype}" for dependency in rows))for label, merge in merges.items():    outputs = sqlglot_lineage(None, merge, schema, dialect="duckdb")    print(f"sqlglot, MERGE {label}, outputs:", ", ".join(outputs) or "none")# One value too many for daily_revenue's two columns, caught after sqlglot parses it; each MERGE is refused before sqlglot is asked.refused = {"INSERT with one value too many": insert.replace("sum(p.amount)", "sum(p.amount), count(*)"),           **{f"MERGE {label}": merge for label, merge in merges.items()}}for label, statement in refused.items():    try:        lineage.column_lineage(statement, schema)    except lineage.LineageError as error:        print(f"book, {label}:", error)
Salidapython insert-and-merge-lineage.py
analytics.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:

misspelt-column-lineage.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Superado
"""A misspelt column, emial for email, in a query on one table: sqlglot raises when the column is qualified by itsalias, and traces it to the table when it isn't. The prose rests on the sqlglot answer for each form, and on the book'scheck against the schema."""from sqlglot.errors import OptimizeErrorfrom lib import lineagefrom lib.catalog import open_catalogschema = lineage.schema(open_catalog(["crm.learners"]))    # the schema lets sqlglot check each column name# the alias l is right, and only the column name is misspeltqualified = "create table marketing.audience as select l.learner_id, l.emial from crm.learners l"# no alias, so nothing names the table the column comes fromunqualified = "create table marketing.audience as select learner_id, emial from crm.learners"try:    lineage.sqlglot_sources(qualified, schema)except OptimizeError as error:    print("sqlglot, qualified l.emial:", f"{type(error).__name__}: {error}")print("sqlglot, unqualified emial comes from:", ", ".join(lineage.sqlglot_sources(unqualified, schema)["emial"]))try:    lineage.column_lineage(unqualified, schema)except lineage.LineageError as error:    print("book, unqualified emial:", error)
Salidapython misspelt-column-lineage.py
sqlglot, 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

Último cambio en la edición 2026.11.27

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?

column-impact.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Superado
"""What a change to one source column can break, walked over the column graph that the nightly run's events describe.The prose rests on the reach counts printed for each column: through values, and in all."""from lib import lineagefrom lib.catalog import open_catalogfrom lib.platform import scratchevents_file = scratch() / "events.jsonl"lineage.run_all(open_catalog(), events_file)graph = lineage.graph(lineage.read_events(events_file))    # built from the events alone, as a lineage server wouldprint("edges in the column graph:", len(graph.edges))for column in ("crm.learners.email", "crm.learners.marketing_consent", "learning.courses.category"):    reached = lineage.downstream(graph, column)    print(f"{column} reaches:")    # dict.fromkeys drops repeated targets and keeps the order they were found in    for target in dict.fromkeys(edge.target for edge in reached):        how = ", ".join(f"{edge.type} {edge.subtype}" for edge in reached if edge.target == target)        # a table's name has one dot and a column's two, so a table target means every row of it        print(f"  {target}{', every row' if target.count('.') == 1 else ''}:", how)    values = [edge for edge in reached if edge.type == "DIRECT"]    # only DIRECT edges copy values    print(f"{column}, columns reached through values:", len(lineage.columns_reached(graph, values)))    print(f"{column}, columns reached in all:", len(lineage.columns_reached(graph, reached)))
Salidapython column-impact.py
edges 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

Último cambio en la edición 2026.11.27

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:

propagate-classifications.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Superado
"""Proposes classifications from lineage for the columns with no declared one, then checks the rule against the columnspeople did classify. The prose rests on the personal count, on the reproduced counts, and on the check that no declared class is lower."""from lib import lineage, metadatafrom lib.catalog import open_catalogfrom lib.platform import scratchcatalog = open_catalog()events_file = scratch() / "events.jsonl"lineage.run_all(catalog, events_file)for problem in metadata.problems(catalog, metadata.load()):    print("metadata problem:", problem)graph, known = lineage.graph(lineage.read_events(events_file)), lineage.declared()   # known: governance/metadata.tomlprint("propagated through:", " and ".join(lineage.rules()["propagate_through"]))      # from governance/lineage.tomlproposed = lineage.propose(graph, known)for column, (classification, decided_by) in proposed.items():    if column not in known:        first = decided_by[0]      # lib sorts the deciding edges DIRECT first, so this is a value when one decides        print(f"{column}: {classification}, from {first.source} ({first.type} {first.subtype})")print("personal columns proposed:", sum(1 for column, (classification, _) in proposed.items()                                        if column not in known and classification == "personal"))classified = [column for column in proposed if column in known]print("declared classifications checked:", len(classified))print("classes declared for them:", ", ".join(sorted({known[column] for column in classified})))for through in (["DIRECT", "INDIRECT"], ["DIRECT"]):    proposals = lineage.propose(graph, known, through)    agree = sum(1 for column in classified if proposals[column][0] == known[column])    print(f"declared classifications reproduced, through {' and '.join(through)}:", f"{agree} of {len(classified)}")# proposals is the DIRECT-only run from the loop abovemissed = [column for column in classified if proposals[column][0] != known[column]]print("missed with DIRECT inputs only:", len(missed))for column in missed:    print(f"  {column}: declared {known[column]}, DIRECT inputs propose {proposals[column][0]}")print("declared less protected than lineage proposes:", len(lineage.understated(proposed, known)))assert not lineage.understated(proposed, known)
Salidapython propagate-classifications.py
metadata 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:

personal-filter-propagates.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Superado
"""A birthday-offer table whose only personal input is a filter on date of birth. The prose rests on the learner count,and on the proposals counting DIRECT inputs alone and counting DIRECT and INDIRECT inputs."""from lib import lineagefrom lib.catalog import open_catalogfrom lib.platform import scratchfrom lib.warehouse import connectcatalog = open_catalog(["crm.learners"])# The consenting learners born in the month of the nightly run, on the book's "today".select = ("select l.learner_id, l.country from crm.learners l "          f"where l.marketing_consent and month(l.date_of_birth) = {lineage.NIGHTLY.month}")def offers() -> None:    rows = connect(catalog).sql(select).to_arrow_table()    catalog.create_namespace_if_not_exists("marketing")    catalog.create_table("marketing.birthday_offers", schema=rows.schema).append(rows)events_file = scratch() / "events.jsonl"# record derives the lineage from this statement, and reads it before offers() runslineage.record(lineage.client(events_file), "birthday_offers", f"create table marketing.birthday_offers as {select}",               catalog, offers)offers_table = catalog.load_table("marketing.birthday_offers").scan().to_arrow()print("learners in marketing.birthday_offers:", f"{len(offers_table):,}")graph, known = lineage.graph(lineage.read_events(events_file)), lineage.declared()print("crm.learners.date_of_birth declared:", known["crm.learners.date_of_birth"])for through in (["DIRECT", "INDIRECT"], ["DIRECT"]):    for column, (classification, decided_by) in lineage.propose(graph, known, through).items():        label = f"{column}, through {' and '.join(through)}"        print(f"{label}:", classification)        print(f"{label}, decided by:", f"{decided_by[0].source} ({decided_by[0].type} {decided_by[0].subtype})")
Salidapython personal-filter-propagates.py
learners 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

Último cambio en la edición 2026.11.27

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:

lineage-disabled-silently.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Superado
"""With OPENLINEAGE_DISABLED=true in the environment, an explicit file transport writes nothing and raises nothing. Theprose rests on the transport the client chose and on the job the check finds without a COMPLETE event."""import osfrom lib import lineagefrom lib.catalog import open_catalogfrom lib.platform import scratchos.environ["OPENLINEAGE_DISABLED"] = "true"        # say, left in a shared environment file after a debugging sessionevents_file = scratch() / "events.jsonl"client = lineage.client(events_file)                # a file transport, passed in explicitlycatalog = open_catalog(["learning.courses", "learning.reviews"])output = lineage.run(catalog, "review_corpus", client)print("transport the client chose:", client.transport.kind)      # OPENLINEAGE_DISABLED wins over the transport passed inprint("pipeline wrote:", output)print("rows written:", f"{len(catalog.load_table(output).scan().to_arrow()):,}")assert not events_file.exists()         # the noop transport never creates the fileprint("events file exists:", events_file.exists())missing = lineage.missing_runs(["review_corpus"], lineage.read_events(events_file))   # ran, but sent no COMPLETEprint("jobs that ran with no COMPLETE event:", ", ".join(missing))
Salidapython lineage-disabled-silently.py
transport 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ó

Último cambio en la edición 2026.11.27

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:

uninstrumented-job.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Superado
"""A Python step copies marketing.audience for the email tool and sends no lineage. The prose rests on the walk from theemail column, which misses the copy, and on the catalog check against the lineage, which finds it."""from lib import lineagefrom lib.catalog import open_catalogfrom lib.platform import scratchfrom lib.warehouse import connectcatalog = open_catalog()events_file = scratch() / "events.jsonl"lineage.run_all(catalog, events_file)# The marketing team's weekly export, written straight to the catalog: no lineage event.export = connect(catalog).sql("select learner_id, full_name, email from marketing.audience").to_arrow_table()catalog.create_table("marketing.campaign_list", schema=export.schema).append(export)print("rows exported:", f"{len(export):,}")events = lineage.read_events(events_file)reached = lineage.downstream(lineage.graph(events), "crm.learners.email")print("crm.learners.email reaches:", ", ".join(edge.target for edge in reached))# the catalog's tables, less the platform's sources and the outputs the events nameprint("tables no job's lineage accounts for:", ", ".join(lineage.unaccounted(catalog, events)))
Salidapython uninstrumented-job.py
rows 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

Último cambio en la edición 2026.11.27

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:

personal-copy-tagged-internal.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Superado
"""The same export, now recorded with lineage, into a table its owner tagged internal. The prose rests on the walk tothe copy and on the check for understated classifications."""from lib import lineagefrom lib.catalog import open_catalogfrom lib.platform import scratchfrom lib.warehouse import connectcatalog = open_catalog()events_file = scratch() / "events.jsonl"lineage.run_all(catalog, events_file)select = "select a.learner_id, a.full_name, a.email from marketing.audience a"def export() -> None:    rows = connect(catalog).sql(select).to_arrow_table()    catalog.create_table("marketing.campaign_list", schema=rows.schema).append(rows)# record reads this statement's lineage before export() runsstatement = f"create table marketing.campaign_list as {select}"lineage.record(lineage.client(events_file), "campaign_export", statement, catalog, export)# Its owner tagged every column internal: "only the marketing team reads it".known = lineage.declared() | {f"marketing.campaign_list.{c}": "internal" for c in ("learner_id", "full_name", "email")}graph = lineage.graph(lineage.read_events(events_file))print("crm.learners.email reaches:", ", ".join(edge.target for edge in lineage.downstream(graph, "crm.learners.email")))for problem in lineage.understated(lineage.propose(graph, known), known):    print("understated:", problem)
Salidapython personal-copy-tagged-internal.py
crm.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

Último cambio en la edición 2026.11.27
  • 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 provisional iceberg://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 lista dataset de la faceta.
  • Un linaje que no puede leerse correctamente es un error, nunca vacío ni parcial. lib.lineage solo lee CREATE ... AS y INSERT ... SELECT, rechaza cualquier otra sentencia, incluida MERGE, sea cual sea lo que nombre su USING. El linaje vacío, una fuente no ubicable o una columna desconocida detienen el trabajo antes de que se ejecute. Las columnas de un INSERT provienen 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, email y body como personales y todas las demás columnas como internas, se envían a sus propietarios para revisión antes de entrar en governance/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.

Cita esta sección

Formato

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

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

En esta página

Capítulo 4 de 10: Linaje a partir de pipelines

  1. Envía un evento de ejecución desde cada pipeline
  2. Traza cada columna de salida hasta sus fuentes
  3. Add the inputs that decide which rows exist
  4. Falla con las sentencias que el analizador no puede leer
  5. Encuentra qué rompe un cambio en una columna
  6. Proponer clasificaciones a partir del linaje
  7. Qué falla en producción
  8. Eventos que nunca llegan
  9. Un trabajo que nadie instrumentó
  10. Datos personales en una tabla clasificada como interna
  11. Lo que decidió este capítulo

Volver arribaTodos los capítulos