Linhagem a partir dos pipelines

Cerca de 36 minutos min de leitura, com 11 exemplos em 11 seções.

Edição 2026.11.31 Exemplos aprovados em 19 de nov de 2026 108 de 108 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.31. Leia o original

Ao final deste capítulo, você saberá capturar a linhagem dos seus pipelines como eventos de execução do OpenLineage, com a linhagem de colunas analisada a partir do SQL deles, incluindo as colunas que aparecem apenas em junções, filtros e agrupamentos. Você usará o grafo que esses eventos descrevem para dizer o que uma mudança em uma coluna quebra a jusante, e para propor classificações para tabelas que ninguém classificou. Você também terá verificações para as três formas como a linhagem falha em produção: eventos que nunca chegam, um job que não envia nenhum, e uma cópia de dados pessoais classificada como menos que pessoal.

A plataforma de aprendizado online do capítulo 1 constrói suas tabelas de relatórios com quatro pipelines SQL sobre oito tabelas de origem. Cada pipeline é um create table ... as select ... em examples/pipelines/, e o módulo compartilhado do livro, lib.pipelines, o executa no DuckDB e grava o resultado de volta no catálogo:

  • course_performance grava analytics.course_performance: matrículas, conclusões, avaliações e receita por curso.
  • learner_activity grava analytics.learner_activity: os eventos de cada aluno e a última atividade.
  • marketing_audience grava marketing.audience: os alunos para quem o marketing pode enviar e-mails, com o nome e o e-mail.
  • review_corpus grava ai.review_corpus: o texto das avaliações no qual o assistente de cursos da plataforma se fundamenta.

A verificação de metadados do capítulo 2 constatou que duas dessas saídas, marketing.audience e ai.review_corpus, não têm nenhum metadado: nenhum responsável e nenhuma classificação para nenhuma coluna. No entanto, uma delas guarda nomes e e-mails dos alunos, e a outra guarda o texto livre das avaliações, onde o capítulo 3 também encontrou nomes e e-mails. Duas perguntas decorrem disso, e o catálogo não consegue responder nenhuma delas. Quais colunas dessas tabelas são dados pessoais? E se a equipe de CRM renomear ou reformatar crm.learners.email, o que quebra? Ambas são perguntas de linhagem. A linhagem indica de onde vêm os dados de cada coluna e para onde eles vão.

Este capítulo acrescenta o módulo compartilhado do livro para linhagem, lib.lineage. Ele executa cada pipeline, informa ao OpenLineage o que a execução leu e gravou, coluna por coluna, e lê o resultado de volta como um grafo que responde às duas perguntas.

Envie um evento de execução a partir de cada pipeline

Última alteração na edição 2026.11.27

OpenLineage, uma especificação aberta para lineage, descreve o lineage com três objetos (modelo de objetos). Um job é "um processo que consome ou produz Datasets", como um pipeline. Uma run é uma ocorrência de um job, identificada por um UUID que o cliente gera, e a especificação recomenda o UUIDv7. Um dataset é uma tabela ou arquivo, nomeado por um namespace e um nome que, juntos, o identificam. Uma run se reporta por meio de eventos de execução: um START quando começa, depois um evento terminal, COMPLETE, FAIL ou ABORT, e um servidor trata os eventos de uma mesma run como cumulativos (ciclo de execução). O lineage vem principalmente do próprio trabalho: um backend fica sabendo sobre os datasets sobretudo por informações sobre os jobs.

O cliente Python, openlineage-python 1.55.0, constrói eventos a partir de RunEvent, Run, Job, InputDataset e OutputDataset em openlineage.client.event_v2, e os envia por um transporte (documentação do cliente). Ele traz transportes HTTP e Kafka para servidores, e um transporte de arquivo "projetado principalmente para testes de integração", que, com append definido, grava um evento JSON por linha em um único arquivo (configuração). O cliente não calcula lineage. Ele serializa o que quem chama passa e acrescenta apenas metadados próprios: uma faceta de execução com sua versão, a localização do código-fonte do job quando ele roda em um checkout do Git, e quaisquer variáveis de ambiente que você configurar para coleta (emit em client/client.py, openlineage-python). Isso significa que o lineage que chega a um servidor é o lineage que o seu código colocou no evento.

lib.lineage.run envolve lib.pipelines.run, que executa um dos quatro pipelines SQL da plataforma e grava sua tabela no catálogo. Ele envia START com as tabelas que o SQL lê como entradas, executa o pipeline e depois envia COMPLETE com o dataset de saída e duas facetas nele. Uma faceta é o nome que o OpenLineage dá a um bloco de metadados anexado a uma run, a um job ou a um dataset, e essas duas guardam o esquema da saída e o lineage de suas colunas, que a próxima seção constrói. Se o pipeline lançar uma exceção, ele envia FAIL no lugar, e lib.lineage.run_all executa os quatro pipelines dessa forma, todos em um mesmo arquivo de eventos. Os datasets precisam de um namespace, e as convenções de nomenclatura do OpenLineage não têm entrada para uma tabela Iceberg em um catálogo SQL local. A mais próxima é o sistema de arquivos local, nomeado pelo seu caminho, o que colocaria uma pasta da sua máquina em todos os eventos. Por isso, lib.lineage usa o marcador iceberg://platform, com os identificadores do catálogo, como crm.learners, como nomes.

Os exemplos precisam dos mesmos bytes a cada vez, mas o horário de um evento e o ID aleatório da run mudam por padrão. Aqui, lib.lineage carimba cada evento com o início nominal da execução noturna no "hoje" do livro, e deriva o ID da run com generate_static_uuid do cliente, que, segundo sua docstring, "sempre produz o mesmo resultado" para o mesmo horário e os mesmos dados: aqui, o nome do job. Execute os quatro pipelines com lineage duas vezes, em dois arquivos, e imprima o que os eventos do primeiro arquivo dizem, não o JSON bruto:

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 Aprovado
"""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"))
Saídapython 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 novamente a mesma execução nominal gravou os mesmos bytes, o que IDs aleatórios nunca fariam, e o exemplo verifica isso. O primeiro arquivo contém 8 eventos, um START e um COMPLETE para cada uma de 4 runs, todos carimbados com 2026-10-01T02:00:00+00:00. O START do job marketing_audience indica as tabelas que o seu SQL lê, crm.learners, learning.courses e learning.enrollments, e o seu COMPLETE indica marketing.audience, com o lineage de cada coluna. Porém, os eventos contêm algo que você não colocou ali: uma faceta de execução chamada tags, que traz a versão do próprio cliente (changelog, 1.38.0), e o URL em _producer de cada faceta também indica essa versão (DEFAULT_PRODUCER em client/constants.py). Assim, os bytes mudam a cada nova versão do cliente, embora o lineage não mude, e um teste deve comparar o que os eventos dizem, como faz o resumo deste exemplo.

Um emissor de produção carimba COMPLETE com a hora em que a execução terminou. Ainda vale manter um ID de run derivado ali, feito a partir do horário agendado, do nome do job e do número da tentativa: um evento enviado duas vezes cai na mesma run em vez de criar uma segunda, e uma tentativa repetida do job recebe uma run própria. Os eventos de produção também devem trazer o ID do snapshot Iceberg da saída, na faceta de dataset version que o modelo de objetos indica para isso. O código aqui o omite, porque o PyIceberg 0.12.0 tira cada ID de snapshot de um UUID aleatório (_generate_snapshot_id em pyiceberg/table/metadata.py).

Regra prática: Envie um START e depois um evento COMPLETE ou FAIL a partir do código que executa cada job, para que nenhuma run aconteça sem eles, e nomeie os datasets por identificadores de catálogo sob um namespace que você escolhe, nunca por um caminho. Em testes, use o transporte de arquivo com um horário fixo do evento e IDs de run estáticos, e compare o que os eventos dizem, nunca os seus bytes. Em produção, envie por um transporte até o seu servidor de lineage, e derive cada ID de run a partir do horário agendado, do job e da tentativa, para que um evento reenviado nunca crie uma run duplicada.

Rastreie cada coluna de saída até suas fontes

Última alteração na edição 2026.11.30

Um evento de execução informa quais tabelas um job leu e escreveu. A linhagem de colunas informa de quais colunas de entrada cada coluna de saída foi derivada, e é isso que a governança precisa: uma tabela que lê crm.learners pode ou não copiar os e-mails. O OpenLineage coloca a linhagem de colunas em uma faceta de dataset, columnLineage, na saída: fields mapeia cada coluna de saída para as suas inputFields, e uma lista opcional dataset reúne as entradas que afetam o dataset inteiro (esquema da faceta). Como o cliente não calcula nada disso, alguém precisa analisar o SQL de cada job.

O sqlglot, um analisador de SQL, faz isso com sqlglot.lineage.lineage. Dados um comando e o esquema das tabelas que ele lê, ele retorna, para cada coluna de saída, uma árvore cujas folhas são colunas de origem, e com column=None retorna todas as colunas de saída de uma vez (linhagem do sqlglot). Ele precisa do esquema. Sem um, SELECT * volta como uma única saída chamada *, e uma coluna sem qualificação em um join aparece como um marcador sem tabela. lib.lineage.schema constrói o esquema a partir dos metadados Iceberg do catálogo, de modo que o analisador enxerga as colunas que o warehouse tem, na versão 30.33.0 do sqlglot.

Comece por marketing_audience, que alimenta a lista para a qual o marketing pode enviar e-mails. Em palavras, ele escolhe alunos que aceitaram e-mails de marketing e cuja conta está ativa, e acrescenta a categoria de curso favorita de cada um, que uma CTE calcula ranqueando as categorias pelas matrículas do aluno. Peça ao sqlglot a linhagem das saídas do pipeline e de duas colunas de course_performance, para ver o que ele deixa de fora:

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 Aprovado
"""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]))
Saídapython 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

Os valores estão corretos, mas falta o que decide quais alunos estão na tabela. email vem de crm.learners.email, e favourite_category é rastreada pela CTE até learning.courses.category. O WHERE do pipeline é l.marketing_consent AND l.status = 'active', e nenhuma das suas colunas, marketing_consent ou status, aparece na linhagem de nenhuma saída. O exemplo verifica as duas. O filtro de consentimento é o motivo pelo qual o marketing pode manter esta tabela, e a linhagem não o menciona. Tampouco menciona as chaves de junção de matrículas e cursos.

O segundo problema é o inverso: uma entrada que apenas filtra é listada como se fosse um valor. course_performance soma apenas pagamentos bem-sucedidos, com filter (where p.status = 'succeeded'), e o sqlglot diz que revenue_usd vem de billing.payments.amount, billing.payments.status: a coluna somada e a coluna que apenas decide quais pagamentos contam, listadas da mesma forma. completions conta matrículas com filter (where e.completed_at is not null), e volta do mesmo jeito, de learning.enrollments.completed_at, learning.enrollments.enrollment_id. Os dois problemas decorrem de como o sqlglot constrói a árvore. Ele coleta as colunas na expressão de cada saída, então enxerga um filtro dentro de uma expressão e nada fora dela, e seus nós não carregam nenhum tipo que indique como uma entrada foi usada.

Regra prática: Use o lineage do sqlglot para as colunas das quais o valor de cada saída é calculado, e sempre passe o esquema do catálogo, gerado a partir dos metadados da tabela, nunca um esquema digitado. Não leia a resposta dele como tudo de que uma coluna depende: ela deixa de fora as colunas que fazem join, filtram e agrupam, e não diz quais das suas entradas são valores.

Adicione as entradas que decidem quais linhas existem

Última alteração na edição 2026.11.31

O lineage do sqlglot lista as colunas a partir das quais um valor é calculado, e o OpenLineage tem um lugar para as demais. Cada campo de entrada carrega uma lista de transformações, cada uma com um tipo, um subtipo e um indicador masking (faceta de column lineage). DIRECT significa que o valor de saída é derivado do valor de entrada, por meio de IDENTITY, TRANSFORMATION ou AGGREGATION. INDIRECT significa que o valor de saída é afetado por uma entrada sem ser derivado dela, por meio de JOIN, GROUP_BY, FILTER, SORT, WINDOW ou CONDITIONAL. Entradas que moldam cada linha, como uma WHERE, pertencem à lista dataset da faceta.

Para governança, o lado INDIRECT importa, pois a informação flui por condições além de valores. Denning chama de "fluxo implícito" a informação que flui por condições: uma instrução que atribui somente quando uma condição se verifica ainda revela o valor dessa condição (Denning, 1976). Uma linha em marketing.audience informa que aquele aprendiz consentiu.

lib.lineage.column_lineage acrescenta duas coisas que a resposta do sqlglot não tem: um tipo para cada entrada de valor, e as entradas INDIRECT. Ele tipa cada entrada de valor conforme a posição da coluna na expressão da saída: uma coluna simples é IDENTITY, uma coluna dentro de um agregado é AGGREGATION, e qualquer outro caso é TRANSFORMATION. Uma coluna dentro do FILTER de um agregado, do PARTITION BY ou do ORDER BY de uma janela, ou na condição ou operando de um CASE, é INDIRECT, e um hash no caminho define masking. Os argumentos de COALESCE contam como valores: o OpenLineage lista COALESCE como CONDITIONAL, mas qualquer um de seus argumentos pode se tornar o valor da saída. Em seguida, ele percorre cada SELECT da instrução, incluindo CTEs, e coleta as colunas de suas cláusulas de linha, remontando as colunas de CTEs até as tabelas de origem:

ROW_CLAUSES = {"joins": "JOIN", "where": "FILTER", "group": "GROUP_BY", "having": "FILTER", "qualify": "FILTER",
               "order": "SORT"}

Execute-o sobre o mesmo pipeline e as mesmas duas colunas:

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 Aprovado
"""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]))
Saídapython 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

Os valores coincidem com os do sqlglot, cada um uma cópia IDENTITY, e as entradas das linhas são a parte nova. Ao incluí-las, aquilo de que marketing.audience depende cresce de 5 colunas de origem para 10. Algumas entradas de linha são colunas que nenhum valor usa: marketing_consent e status como FILTER, os dois IDs de curso como JOIN, e o learner_id das matrículas como GROUP_BY e JOIN. crm.learners.learner_id e learning.courses.category, que os valores também copiam, moldam as linhas: o ID como JOIN, a categoria como GROUP_BY e JOIN. Para revenue_usd, as duas entradas agora se distinguem: amount é uma AGGREGATION DIRECT, e status um FILTER INDIRECT. O mesmo vale para as duas entradas de completions: enrollment_id é contado, e completed_at apenas filtra.

Mais um detalhe: os campos transformationType e transformationDescription por campo estão obsoletos, substituídos pelo transformations por entrada que lib.lineage escreve (changelog, 1.17.1). E o OpenLineage 1.53.0 acrescentou uma faceta de dataset Lineage para lineage declarado, como o de uma view, enviada em um DatasetEvent, que os consumidores devem preferir quando ambos descrevem a mesma relação (faceta lineage). Eventos de execução de jobs carregam columnLineage, como os da plataforma.

Regra prática: Registre as entradas INDIRECT junto com o column lineage de cada job: as chaves de junção, filtros e colunas de agrupamento de cada SELECT, incluindo CTEs, na lista dataset da faceta, e tipifique cada entrada de valor com os subtipos do OpenLineage. Espere mais arestas, muitas delas chaves de junção. Mantenha-as mesmo assim: um filtro sobre uma coluna de consentimento decide quem pode receber um e-mail, e ele chega à tabela apenas como uma entrada INDIRECT.

Falhe em instruções que o analisador não consegue ler

Última alteração na edição 2026.11.27

A linhagem de colunas da plataforma só é tão boa quanto a análise sintática por trás dela, e uma análise pode estar errada sem falhar. A lineage do sqlglot aceita mais do que um SELECT: ela encontra a consulta dentro de um CREATE TABLE ... AS, de um INSERT ... SELECT ou de um CREATE VIEW, e também lê um MERGE (sqlglot, optimizer/scope.py). Três casos voltam com aparência correta. As saídas de um INSERT recebem o nome do seu SELECT, e nunca o nome das colunas da tabela. Um MERGE volta como a última consulta que o sqlglot alcança nele, como se essa consulta fosse o que o MERGE grava. Quando o USING indica uma tabela ou uma CTE e nenhuma subconsulta segue, o sqlglot não retorna linhagem nem erro. Quando o USING é uma subconsulta, ou quando uma subconsulta aparece em uma condição WHEN ou em um SET, ele retorna as colunas da última dessas subconsultas, esteja o MERGE gravando-as ou não. E uma coluna com erro de digitação passa despercebida quando não está qualificada em uma consulta sobre uma única tabela: o sqlglot a atribui a essa tabela, tenha ela a coluna ou não.

Todos os quatro pipelines da plataforma são instruções CREATE TABLE ... AS. À medida que as tabelas crescem, pipelines como esses frequentemente se tornam incrementais: um INSERT que acrescenta a receita de um dia a analytics.daily_revenue, ou um MERGE que atualiza analytics.learner_activity no lugar. Pergunte ao sqlglot e à lib.lineage.column_lineage sobre cada um, o INSERT e o MERGE em duas formas, e compare as respostas:

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 Aprovado
"""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)
Saídapython 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

A tabela analytics.daily_revenue tem as colunas day, revenue_usd, mas o sqlglot dá às saídas do INSERT os nomes paid_at, _col_1: o primeiro leva o nome da coluna dentro do cast, o segundo é um nome gerado para uma expressão sem alias.

Um INSERT preenche colunas por posição, então a lib.lineage também faz a correspondência por posição, tomando os nomes do catálogo: as colunas que o INSERT lista, ou então todas as colunas da tabela. Assim, day vem de billing.payments.paid_at DIRECT TRANSFORMATION, e o agrupamento do INSERT e seu filtro em status moldam cada linha: billing.payments.paid_at GROUP_BY, billing.payments.status FILTER. Quando o SELECT tem mais ou menos valores do que as colunas escritas, a lib.lineage levanta um erro: analytics.daily_revenue: the INSERT writes 2 columns, and its SELECT has 3 values.

Para o MERGE cujo USING indica uma tabela, o sqlglot retorna none, e nenhum erro. Para aquele cujo USING é uma subconsulta, ele retorna learner_id, country, email, embora esse MERGE grave apenas learner_id e country. Uma verificação de linhagem vazia pega o primeiro e deixa passar o segundo; por isso, lib.lineage não avalia o que o sqlglot retorna para um MERGE. Antes de chamar o sqlglot, ela recusa toda instrução que não seja um CREATE ... AS ou um INSERT ... SELECT: analytics.learner_activity: lineage is read only from CREATE ... AS and INSERT ... SELECT, not from MERGE.

Um erro de digitação em uma coluna, o terceiro caso, depende de como a coluna está escrita. Os pipelines da plataforma qualificam cada coluna com o alias da sua tabela, como em l.email, e o próprio sqlglot verifica uma coluna qualificada contra o esquema:

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 Aprovado
"""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)
Saídapython 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

Um erro de digitação qualificado interrompe o sqlglot com OptimizeError: Unknown column: emial. Uma coluna não qualificada, em uma consulta sobre uma única tabela, volta como crm.learners.emial: uma resposta confiante sobre uma coluna que não existe. Em um join, uma coluna não qualificada com erro de digitação não pertence a nenhuma das tabelas, e o sqlglot retorna um marcador sem tabela (sqlglot, lineage.py), que lib.lineage rejeita como uma origem que não consegue localizar. Para o caso de tabela única, lib.lineage verifica cada origem contra o esquema e levanta crm.learners has no column emial.

lib.lineage.record, que run usa, lê a linhagem antes de o job rodar, então um pipeline cuja linhagem não pode ser lida falha antes de gravar qualquer coisa. Isso é rigoroso, e deliberado: um job com linhagem vazia desapareceria de todos os relatórios de impacto e verificações de classificação deste capítulo, e um com linhagem errada os induziria ao erro. Execute a mesma verificação no CI em cada pull request que altere um pipeline, para que a falha apareça na revisão, e não à noite.

Regra prática: Trate uma instrução que seu analisador não consegue ler corretamente como erro, nunca como linhagem vazia ou parcial. Recuse todo tipo de instrução que ele interpreta mal, como MERGE, antes de submetê-la a ele, e falhe em linhagem vazia, em uma origem que o analisador não consegue localizar e em uma coluna que o esquema não tem. Faça a correspondência das colunas de um INSERT por posição com as colunas da tabela no catálogo, nunca pelos nomes do SELECT, e falhe quando as quantidades forem diferentes. Para um MERGE, escreva um SELECT das colunas que ele grava, e registre a linhagem do job a partir dele, como um INSERT ... SELECT para a tabela do MERGE, até que o seu analisador passe a tratar o MERGE por si mesmo.

Descubra o que uma mudança em coluna quebra

Última alteração na edição 2026.11.27

Com a linhagem de colunas presente em cada evento COMPLETE, a plataforma tem um grafo: as colunas são nós, e cada campo de entrada é uma aresta até a coluna ou tabela que ele alimenta. A análise de impacto pergunta o que uma mudança em uma coluna pode quebrar. Ela percorre esse grafo a partir da coluna, seguindo cada aresta que sai dela e continuando a partir de onde cada uma chega, em qualquer profundidade. Não é preciso nenhum método especial: trata-se de alcançabilidade em grafos. Uma regra é específica da linhagem. Uma aresta INDIRECT que aponta para uma tabela significa que cada linha dela pode mudar, então o percurso continua a partir de todas as colunas dessa tabela.

lib.lineage.graph constrói o grafo apenas a partir do arquivo de eventos, como faria um servidor de linhagem, e não a partir do SQL. Assim, ele inclui todo job que envia eventos, qualquer que seja a linguagem em que foi escrito, e nada que não envie. lib.lineage.downstream faz o percurso.

Considere três mudanças que as equipes da plataforma podem fazer. A equipe de CRM passa todos os e-mails para minúsculas, ou renomeia crm.learners.email. Um novo fluxo de cadastro muda o que crm.learners.marketing_consent significa para contas antigas. A equipe de aprendizado renomeia uma categoria em learning.courses. Antes de continuar, faça um palpite: quantas colunas a mudança de consentimento pode alcançar?

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 Aprovado
"""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)))
Saídapython 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

O consentimento é a surpresa. Uma mudança nele alcança 0 colunas por meio de valores, mas, por meio do seu filtro, alcança todas as 5 colunas de marketing.audience, porque altera quem recebe e-mails. Uma ferramenta de linhagem que considera apenas valores informaria que uma mudança no consentimento não tem impacto algum.

Uma mudança em email alcança 1 coluna, marketing.audience.email, então renomeá-la quebra o pipeline de marketing e nenhum outro job que envia linhagem. Uma renomeação de categoria alcança 2 colunas por meio de valores e 12 no total, porque as categorias também agrupam analytics.course_performance e classificam o favorito de cada aluno.

O mesmo percurso serve a dois capítulos posteriores: o capítulo 7 acompanha as colunas de um aluno a jusante para encontrar cada tabela derivada que uma exclusão precisa alcançar, e o capítulo 10 escreve um relatório de impacto para cada pull request que altera um esquema.

Regra prática: Execute a análise de impacto sobre o grafo construído a partir dos eventos, incluindo as arestas INDIRECT, e apresente duas listas: colunas cujos valores podem mudar, e tabelas cujas linhas podem mudar. Trate uma mudança em uma coluna usada apenas em filtros e junções como uma mudança em todas as colunas das tabelas que ela filtra, e envie o relatório aos responsáveis por cada tabela que ela alcança.

Propor classificações a partir da linhagem

Última alteração na edição 2026.11.27

Uma coluna derivada guarda dados de suas entradas, então sua classificação pode ser derivada das classificações delas. A regra clássica vem do modelo de reticulado de Denning para o fluxo de informação: a classe de um valor calculado a partir de várias entradas é o menor limite superior, o "join", das classes delas (Denning, 1976). As classificações da plataforma formam uma linha, public, internal, personal e sensitive, então o join é a mais restrita delas, o que stricter em lib.metadata, o módulo de metadados do livro, retorna. Quais entradas contam é uma questão de julgamento. Contamos também as entradas INDIRECT, seguindo os fluxos implícitos de Denning, porque uma tabela filtrada por consentimento revela o consentimento de cada aprendiz. Essa escolha está em governance/lineage.toml, para que uma equipe possa mudá-la em uma única linha revisada.

Duas outras escolhas seguem da mesma cautela. A flag masking do OpenLineage indica apenas que um valor foi ofuscado, por exemplo com um hash (facet de linhagem de coluna). Se um identificador com hash ainda é dado pessoal é uma questão jurídica: o capítulo 2 cita o considerando do GDPR sobre dados pseudonimizados e deixa a resposta para os advogados. Por isso, a regra do livro nunca rebaixa uma classificação por causa de mascaramento. Servidores de catálogo também deixam a escolha para a configuração. O Apache Atlas propaga classificações ao longo da linhagem e pode bloquear isso em uma aresta, por exemplo quando uma view mascara uma coluna PII (Atlas). O DataHub propaga termos de glossário ao longo da linhagem de colunas, recurso que sua documentação da versão 1.7.0 chama de beta público no DataHub Cloud (DataHub). Uma proposta é um piso, não um veredito: como os rascunhos que um modelo local escreve no capítulo 2, ela é revisada antes de entrar em governance/metadata.toml, o arquivo da plataforma com donos e classificações.

lib.lineage.propose propõe uma classificação para cada coluna que um job escreveu, e lib.metadata.problems lista as tabelas que precisam de uma. Verifique a regra nas duas tabelas que as pessoas classificaram, analytics.course_performance e analytics.learner_activity, antes de confiar nela em marketing.audience e ai.review_corpus, as duas sem metadados:

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 Aprovado
"""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)
Saídapython 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

A verificação de metadados do capítulo 2 ainda aponta as duas tabelas sem metadados, e a linhagem propõe uma classificação para cada uma de suas colunas. Ela propõe 3 colunas pessoais: full_name e email em marketing.audience, cada uma uma cópia IDENTITY de uma coluna pessoal em crm.learners, e body em ai.review_corpus, uma cópia do texto livre das avaliações. As demais saem como internal, inclusive favourite_category, para a qual o exemplo imprime internal, from crm.learners.learner_id (INDIRECT JOIN). Seus valores são nomes públicos de categorias do catálogo de cursos, mas as linhas em que estão são escolhidas por um join em IDs de aprendizes e por um filtro de consentimento, então elas são internal.

Contar as entradas INDIRECT reproduz as classificações declaradas nas colunas que as pessoas classificaram, 13 of 13, e todas elas são internal.

As entradas DIRECT sozinhas reproduzem 10 of 13, e deixam passar 3: course_id, title e category de analytics.course_performance. Uma regra só com DIRECT as classifica como public, como no catálogo de cursos, enquanto a equipe de analytics escolheu internal. Assim, a regra propõe não menos do que as pessoas escolheram aqui, e a linhagem não encontra classificação declarada inferior à sua proposta. Isso é evidência fraca: uma regra que propusesse internal para toda coluna teria o mesmo desempenho. E ela não pode mostrar o que a regra faz com um filtro pessoal, já que nenhum dos filtros ou joins da plataforma lê uma coluna pessoal: nem mesmo marketing_consent é classificada como internal.

Então construa uma tabela cujo filtro leia uma coluna pessoal. Para uma oferta de aniversário, o marketing quer os aprendizes que consentiram e nasceram neste mês, com seu ID e país, e nada mais:

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 Aprovado
"""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})")
Saídapython 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)

Nenhuma coluna copia algo pessoal, mas cada linha diz que seu aprendiz nasceu no mês da oferta, parte de uma data de nascimento. A tabela contém 165 aprendizes, e governance/metadata.toml classifica a data de nascimento como personal. Contar apenas as entradas DIRECT propõe internal para learner_id e internal para country.

Acrescente as entradas INDIRECT, e a regra propõe personal para learner_id e personal para country, ambas decididas por crm.learners.date_of_birth (INDIRECT FILTER). É esse o caso para o qual existem as entradas INDIRECT, e ele mostra também o custo: um único filtro pessoal torna pessoal cada coluna de uma tabela.

O OpenLineage pode carregar classificações nos próprios eventos, com a faceta de dataset Tags, cuja chave field "identifica o campo em um dataset se uma tag se aplica a ele" (faceta tags, schema). Nós as mantemos em governance/metadata.toml em vez disso, a única fonte que as políticas de acesso da plataforma também leem, por meio de lib.policy, o módulo de políticas do livro (capítulo 5).

Regra prática: Proponha a classificação de cada coluna derivada como a mais restrita das classificações de suas entradas, contando as entradas INDIRECT, e envie as propostas ao dono da tabela para revisão antes que se tornem metadados. Nunca deixe a linhagem rebaixar uma classificação declarada por alguém, e nunca trate o mascaramento como desclassificação. Conte apenas as entradas DIRECT se seus pipelines frequentemente fazem join ou filtram por colunas pessoais, como casar por email, e todas as saídas, caso contrário, ficariam pessoais; nesse caso, revise à mão as entradas pessoais INDIRECT.

O que dá errado em produção

A linhagem falha silenciosamente: uma aresta ausente parece exatamente uma coluna sem dependências, e toda verificação construída sobre o grafo, desde a análise de impacto até as classificações propostas, então passa. Três falhas são comuns, e cada uma tem uma verificação.

Eventos que nunca chegam

Última alteração na edição 2026.11.27

O cliente lê OPENLINEAGE_DISABLED do ambiente e, quando o valor é true, os eventos são descartados (configuração). No código-fonte do cliente, essa verificação vem primeiro (openlineage-python, client/client.py): antes de examinar o transporte que você passou explicitamente, o cliente escolhe um transporte que não faz nada. O único aviso é uma linha de log INFO: "OpenLineage is disabled. No events will be emitted." Por padrão, o logger raiz do Python está configurado como WARNING, então essa linha nunca aparece (logging HOWTO). Basta uma variável que tenha ficado em um arquivo de ambiente compartilhado depois da depuração. Defina a variável, execute review_corpus com um transporte de arquivo explícito e verifique o que chega ao arquivo:

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 Aprovado
"""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))
Saídapython 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

Com a variável definida, o pipeline continua executando, mas nada chega ao arquivo. O cliente escolheu o transporte noop em vez do transporte de arquivo que o código passou, e o pipeline gravou 3,000 linhas em ai.review_corpus sem erro e sem arquivo de eventos. A verificação que detecta o problema compara os jobs que o agendador executou com os jobs que enviaram um evento COMPLETE: lib.lineage.missing_runs lista review_corpus como tendo sido executados sem um.

Regra prática: Após cada execução agendada, compare os jobs que foram executados com os jobs cujos eventos COMPLETE chegaram, e emita um alerta para qualquer diferença. Não dependa do emissor para informar o próprio silêncio.

Um job que ninguém instrumentou

Última alteração na edição 2026.11.27

A linhagem cobre apenas os jobs que a enviam. A equipe de marketing da plataforma executa um script Python semanal que copia marketing.audience para marketing.campaign_list, uma tabela que a ferramenta de e-mail lê. Ninguém conectou o script ao 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 Aprovado
"""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)))
Saídapython uninstrumented-job.py
rows exported: 1,829
crm.learners.email reaches: marketing.audience.email
tables no job's lineage accounts for: marketing.campaign_list

Uma exportação que não envia eventos é invisível para a análise de impacto. O script copiou 1,829 nomes e e-mails de alunos, mas crm.learners.email ainda alcança apenas marketing.audience.email, então uma exclusão guiada por esta linhagem deixaria de fora a cópia. O catálogo, porém, sabe que a tabela existe. Por isso, lib.lineage.unaccounted compara as tabelas do catálogo com a linhagem: toda tabela precisa ser uma das fontes da plataforma ou a saída de um job que a linhagem conhece. Ele encontra marketing.campaign_list.

Regra prática: Compare o catálogo com a linhagem periodicamente, em um cronograma fixo, e trate uma tabela que a linhagem de nenhum job explica como um incidente: encontre o job e faça com que ele envie eventos.

Dados pessoais em uma tabela classificada como interna

Última alteração na edição 2026.11.27

Instrumentar a exportação da equipe de marketing corrige o grafo e expõe um segundo problema. Quando o responsável pela exportação criou marketing.campaign_list, classificou todas as colunas como internas, porque apenas a equipe de marketing lê essa tabela. Isso é uma afirmação sobre quem lê uma tabela, não sobre o que ela contém. Envolva o trabalho do script em lib.lineage.record, com o SELECT com que ele é executado como sua linhagem, e compare as classificações declaradas com a proposta da linhagem:

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 Aprovado
"""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)
Saídapython 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

Assim que a exportação envia a linhagem, a travessia alcança a sua cópia: crm.learners.email alcança marketing.audience.email, marketing.campaign_list.email, dois saltos, o segundo através da exportação. E lib.lineage.understated informa full_name e email em marketing.campaign_list como declarados internos, enquanto a linhagem propõe pessoais: cópias de dados pessoais que qualquer política que leia a classificação declarada trataria como internas.

Regra prática: Execute lib.lineage.understated, ou uma verificação própria semelhante, a cada atualização da linhagem, e falhe quando uma classificação declarada for inferior à proposta pela linhagem. Classifique pelo que uma tabela contém, nunca por quem a lê, e corrija um achado desse tipo elevando a classificação, não removendo a aresta.

O que este capítulo decidiu

Última alteração na edição 2026.11.27
  • Toda execução de pipeline envia eventos de execução do OpenLineage, START e depois COMPLETE ou FAIL, a partir do código que a executa (lib.lineage.run), com o schema da saída e a linhagem de colunas. Os datasets são nomeados por identificadores do catálogo sob o namespace de placeholder iceberg://platform. Os exemplos fixam os horários dos eventos e derivam os IDs de execução a partir da execução nominal, e comparam o que os eventos dizem, não seus bytes.
  • A linhagem de colunas é a linhagem de valor do sqlglot, tipada como subtipos do OpenLineage, mais as entradas INDIRECT: as colunas de junção, filtro, agrupamento e ordenação de cada SELECT, incluindo CTEs, na lista dataset da faceta.
  • Linhagem que não pode ser lida corretamente é um erro, nunca vazia ou parcial. lib.lineage lê apenas CREATE ... AS e INSERT ... SELECT, recusa qualquer outra instrução, MERGE inclusive, independentemente do que seu USING nomeia. Linhagem vazia, uma fonte que não pode ser localizada ou uma coluna desconhecida interrompe o job antes que ele seja executado. As colunas de um INSERT vêm do schema da tabela no catálogo, associadas por posição, e uma contagem diferente é um erro.
  • A análise de impacto percorre o grafo construído a partir dos eventos, incluindo as arestas INDIRECT, e informa as colunas cujos valores podem mudar e as tabelas cujas linhas podem mudar.
  • As classificações se propagam como a mais restritiva de todas as entradas, DIRECT e INDIRECT, conforme definido em governance/lineage.toml, de modo que uma tabela escolhida por um filtro pessoal é proposta como pessoal. A linhagem nunca reduz uma classificação declarada, e o mascaramento nunca desclassifica. As propostas para as duas tabelas sem classificação, full_name, email e body pessoais e todas as demais colunas internas, vão para seus proprietários para revisão antes de entrarem em governance/metadata.toml.
  • Três verificações protegem a própria linhagem: jobs que foram executados sem um evento COMPLETE, tabelas que nenhuma linhagem de job explica, e classificações declaradas inferiores às que a linhagem propõe. Um grafo de linhagem só é tão completo quanto seus eventos, e uma aresta ausente se parece exatamente com uma coluna sem dependências.

Este capítulo, nesta edição

Edição 2026.11.31Exemplos aprovados em 19 de nov de 202611 de 11 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.31.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 4 de 10: Linhagem a partir dos pipelines

  1. Envie um evento de execução a partir de cada pipeline
  2. Rastreie cada coluna de saída até suas fontes
  3. Adicione as entradas que decidem quais linhas existem
  4. Falhe em instruções que o analisador não consegue ler
  5. Descubra o que uma mudança em coluna quebra
  6. Propor classificações a partir da linhagem
  7. O que dá errado em produção
  8. Eventos que nunca chegam
  9. Um job que ninguém instrumentou
  10. Dados pessoais em uma tabela classificada como interna
  11. O que este capítulo decidiu

Voltar ao topoTodos os capítulos