Governança de ponta a ponta

Cerca de 33 minutos min de leitura, com 6 exemplos em 8 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ê será capaz de governar, com código e de ponta a ponta, uma tabela de uma plataforma de dados. Você vai catalogá-la com uma equipe responsável e uma classificação para cada coluna, capturar a linhagem de um pipeline que a copia, decidir quem pode ler cada uma de suas linhas e aplicar essa decisão em uma consulta, e ver um pull request falhar porque acrescentou uma coluna que ninguém classificou. Cada parte é pequena e roda em segundos, e cinco capítulos posteriores tornam cada uma delas sólida.

Este livro é para engenheiros de dados, de analytics e de plataforma que já constroem pipelines e data warehouses e que receberam a tarefa de torná-los governados. Você conhece SQL, Python e Parquet ou uma tabela de lakehouse, e não precisa de teoria de governança: precisa de governança que funcione, seja testada e seja revisada em pull requests como o restante do seu código. Ao final do livro, você será capaz de governar uma plataforma de dados com código que roda em CI:

  • um catálogo em que toda tabela tem um responsável e toda coluna uma classificação;
  • dados pessoais encontrados automaticamente, com medição do que o detector deixa passar;
  • linhagem capturada a partir dos pipelines;
  • políticas de acesso como código testado, aplicadas como filtros de linhas e máscaras de colunas;
  • retenção e apagamento que removem os dados;
  • uma trilha de auditoria;
  • verificações que reprovam um pull request;
  • as mesmas regras aplicadas aos dados que treinam ou fundamentam a IA.

Este livro acompanha um único caso do início ao fim: uma plataforma online de aprendizado que vende cursos profissionais para adultos, a que chamamos de plataforma. Seu data warehouse é um catálogo de tabelas Iceberg, cada uma sob o namespace da equipe que a mantém: alunos e instrutores em crm, cursos, matrículas, eventos de aprendizado e avaliações de cursos em learning, pagamentos em billing, e tickets de suporte em support. Pipelines em SQL constroem a partir delas tabelas de relatórios. Agentes de suporte, instrutores, marketing, finanças, cientistas de dados e o assistente de cursos da plataforma, sua IA, cada um precisa de algo diferente dessas tabelas, e é isso que torna a plataforma digna de governança.

Os dados da plataforma, que todos os exemplos deste livro leem, são gerados. Um script os produz uma única vez a partir de sementes fixas com o Faker, uma biblioteca de dados falsos, e os arquivos são versionados junto com uma ficha de dados que descreve como foram feitos. Nenhuma pessoa real está nos dados. Seus endereços de e-mail estão em domínios reservados para exemplos, de modo que não conseguem alcançar ninguém, e seus endereços IP estão em faixas reservadas para documentação, de modo que não apontam para ninguém. Seus números de telefone, números de cartão e IBANs são aleatórios em um formato válido, portanto um deles pode coincidir com um número ou uma conta em uso: nunca ligue para eles, envie mensagens, cobre ou pague. A ficha de dados também lista o que foi deixado de propósito para os exemplos encontrarem, como números de cartão completos em uma coluna legada e dados pessoais em texto livre.

Todos os exemplos rodam offline, em um único processo Python 3.12.15, com bibliotecas fixadas: PyIceberg 0.12.0 para o catálogo Iceberg e suas tabelas, DuckDB 2.0.0 para consultas, sqlglot 30.33.0 para analisar SQL, openlineage-python 1.55.0 para linhagem, e regopy 1.5.2 para políticas escritas em Rego, a linguagem de políticas do Open Policy Agent (OPA). Seis serviços que uma plataforma de produção executa não rodam aqui, e cada um tem um substituto:

  • Trino, o motor SQL pelo qual as ferramentas consultam: o DuckDB atrás da camada de aplicação do livro, que reescreve cada consulta antes de executá-la.
  • O servidor do OPA, a quem o Trino pede decisões de acesso (Trino 484, controle de acesso com OPA): o regopy, avaliando o mesmo Rego dentro do processo Python.
  • Spark, ou qualquer motor que execute os pipelines em escala: o DuckDB, executando o arquivo SQL de cada pipeline.
  • Um servidor de catálogo ou um catálogo em nuvem, servindo metadados de tabelas por meio de uma API como a do catálogo REST do Iceberg (especificação do catálogo REST, 1.12.0): o catálogo SQL do PyIceberg, apoiado em um arquivo SQLite que registra onde está o metadado de cada tabela, com os metadados ao lado dos dados no disco local.
  • Um servidor de linhagem: um arquivo de eventos OpenLineage, que o código do livro lê de volta para formar um grafo.
  • O serviço de CI e o git: duas pastas, uma para a branch principal e outra para a branch de um pull request.

O que você aprende aqui são os padrões abertos com que esses serviços trabalham: os metadados de tabelas do Iceberg, o OpenLineage e o Rego. O que você constrói corresponde a eles.

A governança da plataforma começa com uma planilha. Alguém listou as colunas de crm.learners, que guarda o nome, o e-mail, o telefone e o endereço de cada aluno, com uma classificação ao lado de cada uma, e isso é tudo. Nenhuma equipe está indicada como responsável pela tabela. Um pipeline noturno copia nomes e e-mails de alunos para uma tabela de marketing, e nada registra isso. Agentes de suporte atendem cada um uma região, mas uma consulta ao warehouse devolve os alunos de todas as regiões. E a equipe do CRM está prestes a acrescentar uma coluna. Este capítulo responde a cada um desses problemas com o código que os capítulos seguintes desenvolvem, na menor escala que funciona: uma tabela, um pipeline, uma regra e uma verificação. Apenas uma das quatro é um motor de políticas; as outras são metadados, eventos de linhagem e um teste, mantidos no mesmo repositório e revisados da mesma forma.

O capítulo 2 mantém o catálogo em sintonia com as mudanças de esquema e mede os metadados rascunhados por um modelo local. O capítulo 4 usa a linhagem para análise de impacto e para propor classificações. O capítulo 5 escreve a política completa, com seus testes, e o capítulo 6 a aplica em cada consulta. O capítulo 10 executa as verificações dos capítulos 2 a 7 no CI, com aprovações dos responsáveis e dispensas.

Quatro capítulos acrescentam o que este deixa de fora. O capítulo 3 encontra os dados pessoais que os metadados não capturam. O capítulo 7 trata de retenção, consentimento e apagamento. O capítulo 8 mantém uma trilha de auditoria, e o capítulo 9 aplica as mesmas regras aos dados que treinam ou fundamentam a IA.

Os módulos compartilhados, arquivos em examples/lib/ que reúnem o código de que muitos exemplos precisam, são seus para abrir e ler, e cada seção indica os que usa.

Catalogue uma tabela com seu dono e suas classificações

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

O primeiro problema da plataforma é a sua planilha, uma lista de colunas que ninguém verifica. Um catálogo lista as tabelas de uma plataforma e os seus esquemas, e a governança precisa de dois fatos que os dados não carregam: quem responde por cada tabela e como cada coluna deve ser protegida. Mantidos em uma planilha ou na página web de um servidor de catálogo, esses fatos mudam sem revisão, e nenhum teste consegue dizer se estão completos. Mantidos em um arquivo no repositório, ao lado dos pipelines, toda mudança é um diff que alguém aprova, e um teste pode comparar o arquivo com o catálogo.

O arquivo da plataforma é governance/metadata.toml. Ele atribui a cada tabela um dono, um domínio, que é a parte do negócio à qual a tabela pertence, e uma descrição, e a cada coluna uma descrição e uma classificação. As ferramentas de catálogo entendem coisas diferentes por dono, como o capítulo 2 compara, e aqui usamos um único significado em todo o livro: a equipe responsável pela tabela, nunca uma pessoa, para que a resposta sobreviva à saída de alguém. Uma classificação é um de quatro valores, do menos ao mais protegido:

  • public: pode ser mostrado a qualquer pessoa fora da plataforma;
  • internal: para a equipe da plataforma, e não identifica uma pessoa por si só;
  • personal: identifica uma pessoa, ou revela algo sobre ela;
  • sensitive: dados cujo vazamento causaria dano direto a alguém, como um número de cartão.

As colunas são identificadas pelo seu ID de campo do Iceberg, que sobrevive a uma renomeação, com o nome ao lado para as pessoas:

[tables."crm.learners"]
owner = "team-crm"
domain = "crm"
description = "Every learner who has signed up, with their contact details and consents. One row per learner."

[tables."crm.learners".columns]
3 = { name = "email", classification = "personal", description = "The email the learner signs in with." }

Três dos módulos compartilhados do livro fazem o trabalho. lib.catalog.open_catalog cria um catálogo Iceberg novo com as tabelas da plataforma em uma pasta temporária, que é removida quando o exemplo termina. lib.metadata carrega o arquivo, grava-o no catálogo com apply e verifica o catálogo contra ele com problems, que informa qualquer tabela sem metadados ou sem dono, e qualquer coluna sem classificação.

Carregar o arquivo e catalogar crm.learners com ele leva poucas linhas, e a verificação roda sobre o que foi construído:

catalog-the-learners.py Python 3.12.15 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""Apply governance/metadata.toml to crm.learners: write its owner, domain and descriptions into the catalog, then run thecheck on the catalog. The point rests on the last line, the problems the check finds once the file is applied."""from collections import Counterfrom lib import metadatafrom lib.catalog import open_catalogplatform = open_catalog(["crm.learners"])            # a fresh Iceberg catalog holding the learners tabledescribed = metadata.load()learners = described["crm.learners"]print("owner:", learners.owner)print("domain:", learners.domain)counts = Counter(column.classification for column in learners.columns.values())print("columns classified personal:", counts["personal"])print("personal columns:", ", ".join(c.name for c in learners.columns.values() if c.classification == "personal"))print("columns classified internal:", counts["internal"])# Write the descriptions into the table's schema, where readers see them, and the owner and domain into its properties.metadata.apply(platform, described)table = platform.load_table("crm.learners")print("table properties:", ", ".join(f"{key}={value}" for key, value in sorted(table.properties.items())))print("email's description, in the Iceberg schema:", table.schema().find_field("email").doc)# The check: every table in the catalog has an owner, and every column one of the four classifications.print("problems the check finds:", len(metadata.problems(platform, described)))
Saídapython catalog-the-learners.py
owner: team-crm
domain: crm
columns classified personal: 7
personal columns: full_name, email, phone, city, street_address, date_of_birth, notes
columns classified internal: 8
table properties: domain=crm, owner=team-crm
email's description, in the Iceberg schema: The email the learner signs in with.
problems the check finds: 0

O arquivo atribui crm.learners a team-crm, no domínio crm, e classifica 7 das suas colunas como pessoais: full_name, email, phone, city, street_address, date_of_birth, notes. notes está entre elas, embora o seu nome não diga nada, porque os atendentes digitam o que quiserem nela. As demais colunas são internal: o ID do aluno, duas datas, o país, os dois indicadores de consentimento, o status da conta e a região de atendimento.

Aplicar o arquivo também coloca o dono e as descrições onde todo leitor os vê. As propriedades da tabela são domain=crm, owner=team-crm, e a descrição de email fica no esquema Iceberg, onde qualquer leitor da tabela a encontra: "The email the learner signs in with." As classificações permanecem no arquivo, porque é ali que a política de acesso e as verificações as leem. Depois de apply, a verificação encontra 0 problemas.

Uma planilha não consegue lhe dar esse zero. A verificação percorre o catálogo, então uma coluna que o arquivo não descreve apareceria como problema, como work_email aparece em a seção sobre planilhas.

Regra prática: Mantenha donos, domínios, descrições e classificações em um único arquivo revisado no repositório, com uma equipe como dono de cada tabela e um dos valores de uma lista fechada de classificações em cada coluna. Escreva as descrições no catálogo, para que todo leitor de uma tabela as veja, e teste o catálogo contra o arquivo percorrendo o catálogo, nunca o arquivo. Se as edições acontecem na página web de um catálogo, escolha um dos lados como fonte e gere o outro a partir dele (capítulo 2).

Capturar o lineage de colunas de um pipeline

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

O catálogo diz o que cada tabela contém. O lineage diz de onde vieram os dados de uma tabela e para onde foram, e a governança precisa dos dois: uma tabela construída a partir de crm.learners pode ou não copiar os e-mails. O OpenLineage, uma especificação aberta para lineage, descreve um job, como um pipeline, suas execuções (runs) e os datasets que cada execução lê e escreve. Uma execução informa a si mesma por meio de eventos: um START quando começa, depois um que a encerra, como COMPLETE ou FAIL. Os eventos carregam facets, nome que o OpenLineage dá aos blocos de metadados anexados a uma execução, a um job ou a um dataset.

O facet de column lineage, no output de um evento COMPLETE, lista para cada coluna de saída as colunas de entrada de onde ela veio, cada uma marcada como DIRECT ou INDIRECT. DIRECT significa que a saída é derivada da entrada. INDIRECT significa que a entrada molda a saída sem ser copiada: o valor da coluna de saída é "impactado pelo valor da coluna inputField, mas não é derivado dela" (facet de column lineage). As colunas de uma junção ou de uma condição de filtro são entradas INDIRECT, pois decidem quais linhas existem, o mesmo valendo para as de um agrupamento, ordenação, janela ou condição.

A biblioteca cliente não calcula lineage por conta própria, como o capítulo 4 mostra em seu código-fonte: ela envia o que você lhe der. Por isso o módulo do livro, lib.lineage, faz o trabalho. Ele analisa o SQL de cada pipeline com o sqlglot e acrescenta as entradas INDIRECT que o próprio lineage do sqlglot deixa de fora. Ele também envolve lib.pipelines.run, que executa um dos pipelines SQL da plataforma no DuckDB e grava a saída no catálogo: START antes da execução, COMPLETE com o lineage depois. Os eventos passam pelo transporte de arquivo do OpenLineage para um único arquivo, com um horário fixo e um ID de execução derivado desse horário e do nome do job, de modo que o exemplo grava os mesmos bytes a cada vez.

O pipeline marketing_audience da plataforma é uma única instrução create table ... as select ... que grava marketing.audience, a lista de alunos que o marketing pode enviar e-mails. Ele seleciona o ID, o nome, o e-mail e o país de cada aluno a partir de crm.learners, junta cada aluno à sua categoria de curso favorita, classificada a partir de suas matrículas, e mantém os alunos para os quais l.marketing_consent and l.status = 'active' é verdadeiro.

Execute o pipeline com os eventos ativados, leia o lineage de volta apenas a partir dos eventos e conte as linhas por meio de lib.warehouse.connect, que dá ao DuckDB uma view de cada tabela do catálogo:

audience-pipeline-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
"""Run the marketing_audience pipeline with OpenLineage events, then read its column lineage back from the events alone.The point rests on the two INDIRECT lines: the filter and the joins decide which rows the audience table holds."""from lib import lineage, metadata, warehousefrom lib.catalog import open_catalogfrom lib.platform import scratchplatform = open_catalog(["crm.learners", "learning.courses", "learning.enrollments"])events_file = scratch() / "events.jsonl"                 # the file that stands in for a lineage server: one event per linelineage.run(platform, "marketing_audience", lineage.client(events_file))events = lineage.read_events(events_file)print("events:", ", ".join(f"{e['eventType']} of {e['job']['name']}" for e in events))print("the run read:", ", ".join(dataset["name"] for dataset in events[0]["inputs"]))  # the START event lists the inputsprint("the run wrote:", events[-1]["outputs"][0]["name"])                             # the last event, COMPLETE, names the outputgraph = lineage.graph(events)                            # built from the COMPLETE events' column lineage, not from the SQLfor column in ("full_name", "email"):    inputs = [e for e in graph.edges if e.target == f"marketing.audience.{column}"]    print(f"marketing.audience.{column} comes from:", ", ".join(f"{e.source} ({e.type} {e.subtype})" for e in inputs))# The INDIRECT inputs of each kind: the inputs that decide which rows exist, not the ones copied into them.for subtype in ("FILTER", "JOIN"):    shaping = [e.source for e in graph.edges if e.target == "marketing.audience" and e.subtype == subtype]    print(f"its rows are shaped by, INDIRECT {subtype}:", ", ".join(shaping))duckdb = warehouse.connect(platform)                     # DuckDB on the catalog's tables, to count what the join dropped# The learners the filter keeps, counted on crm.learners before any join drops one.consenting = "select count(*) from crm.learners where marketing_consent and status = 'active'"print("consenting, active learners in crm.learners:", f"{duckdb.sql(consenting).fetchall()[0][0]:,}")  # one row, one columnprint("rows in marketing.audience:", f"{duckdb.sql('select count(*) from marketing.audience').fetchall()[0][0]:,}")  # one row, one column# Every column a change to email can reach, at any depth of the graph.reached = lineage.columns_reached(graph, lineage.downstream(graph, "crm.learners.email"))print("a change to crm.learners.email reaches:", ", ".join(reached))# The catalog check, run on the catalog the pipeline wrote to.for problem in metadata.problems(platform, metadata.load()):    print("the catalog check finds:", problem)
Saídapython audience-pipeline-lineage.py
events: START of marketing_audience, COMPLETE of marketing_audience
the run read: crm.learners, learning.courses, learning.enrollments
the run wrote: marketing.audience
marketing.audience.full_name comes from: crm.learners.full_name (DIRECT IDENTITY)
marketing.audience.email comes from: crm.learners.email (DIRECT IDENTITY)
its rows are shaped by, INDIRECT FILTER: crm.learners.marketing_consent, crm.learners.status
its rows are shaped by, INDIRECT JOIN: crm.learners.learner_id, learning.courses.category, learning.courses.course_id, learning.enrollments.course_id, learning.enrollments.learner_id
consenting, active learners in crm.learners: 1,861
rows in marketing.audience: 1,829
a change to crm.learners.email reaches: marketing.audience.email
the catalog check finds: marketing.audience: no metadata

Lido apenas a partir dos eventos, o lineage mostra o que o nome da tabela deixa de fora. marketing.audience.email vem de crm.learners.email (DIRECT IDENTITY), e full_name de crm.learners.full_name (DIRECT IDENTITY), ambos cópias sem alteração de colunas pessoais.

O filtro e as junções decidem quais linhas a tabela contém. As entradas do filtro são crm.learners.marketing_consent, crm.learners.status, de modo que cada linha afirma que o aluno consentiu. As entradas das junções são crm.learners.learner_id, learning.courses.category, learning.courses.course_id, learning.enrollments.course_id, learning.enrollments.learner_id. Um aluno sem matrícula não tem categoria favorita, e a junção com ela o descarta. crm.learners contém 1,861 alunos que consentiram e estão ativos, e marketing.audience contém 1,829.

Uma mudança em crm.learners.email atinge apenas marketing.audience.email na tabela deste pipeline, de modo que renomear a coluna ou alterar seu formato afeta somente essa coluna. Com os quatro pipelines da plataforma enviando lineage, o capítulo 4 constata que ela não atinge nenhuma outra coluna.

A verificação do catálogo, da seção anterior e executada sobre o mesmo catálogo, encontra marketing.audience: no metadata. O pipeline criou uma tabela que ninguém descreveu, e o lineage muda o que essa lacuna significa: de uma tabela sobre a qual a plataforma não sabe nada para uma cópia de duas colunas pessoais, escolhidas pelo consentimento. Até que alguém a descreva, a política de acesso da plataforma trata toda coluna sem classificação como sensitive. Assim, quem lê a cópia pela camada de imposição de políticas da plataforma, que uma seção posterior apresenta, não obtém valor dela, como mostra o teste de quem vê o quê do capítulo 6.

Regra prática: Emita o lineage a partir do código que executa cada job, nunca depois dele (capítulo 4): um evento START, depois um evento COMPLETE ou FAIL, com o column lineage da saída no evento COMPLETE, obtido ao analisar o SQL do job, incluindo as entradas que juntam e filtram linhas, além daquelas que fornecem valores. Leia o lineage de volta a partir dos eventos, nunca a partir do SQL, para que o grafo mostre o que de fato foi executado. Quando o job não for um SQL que um analisador consiga ler, como um script Python, escreva o seu lineage no mesmo código e revise os dois juntos.

Aplique uma decisão de acesso a uma consulta

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

Com as tabelas da plataforma catalogadas, a próxima pergunta é quem pode ler o quê. A política como código parte da premissa do OPA de que a política pode ser desacoplada do software que ela governa, de modo que as pessoas responsáveis por ela possam escrevê-la, analisá-la, versioná-la e distribuí-la separadamente (filosofia do OPA). Uma política responde a uma requisição com uma decisão. A política da plataforma responde com um documento, e não com um simples sim ou não: se a leitura é permitida, os filtros de linha que mantêm apenas as linhas que o usuário pode ver, e as máscaras de coluna que alteram a forma como uma coluna é exibida. Os filtros e as máscaras são dados, nunca SQL. Uma decisão, sozinha, não faz nada. Algo entre o usuário e o motor precisa aplicá-la a cada tabela que uma consulta lê.

Os agentes de suporte da plataforma atendem cada um a uma região, americas, emea ou apac, e precisam dos dados de contato dos alunos para responder aos chamados. A política, governance/policies/access.rego, nega toda requisição por padrão. Ela permite a cada grupo, o papel que um usuário ocupa em governance/users.toml, as tabelas de que o trabalho dele precisa, e lê a região do agente do mesmo arquivo. Esta regra mantém um agente restrito à sua região:

row_filters contains {"column": "support_region", "equals": user.region} if {
	"support" in groups
	table in {"crm.learners", "support.tickets"}
}

lib.policy.decide avalia a política com o regopy. lib.enforce contém a camada de imposição: seu Enforcer pergunta à política sobre cada tabela que uma consulta lê, substitui cada uma por uma subconsulta que aplica a decisão e executa a reescrita no DuckDB. lib.enforce.answer é a única função que um serviço chama, e ela devolve linhas, nunca a conexão com o motor.

agent-a05, um agente de suporte na EMEA, pede três colunas de crm.learners e conta os alunos por região por meio da camada. Em seguida, os e-mails são verificados contra os arquivos gerados que lib.platform.load lê:

support-region-enforced.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""One access decision from the platform's Rego policy, and the same agent's query enforced in the layer. The point rests onthe emea line: the query names no region, yet only EMEA learners come back."""import jsonfrom lib import policyfrom lib.catalog import open_catalogfrom lib.enforce import Enforcer, answerfrom lib.platform import load# agent-a05, a support agent in EMEA, asks to read three columns of crm.learners.request = policy.request("agent-a05", "crm.learners", ["learner_id", "email", "support_region"])  # the shape Trino's OPA plugin sendsdecision = policy.decide(request)assert decision["allow"] is True           # support may read crm.learners; a policy that denies it fails this runprint("allow:", decision["allow"])print("row filters:", json.dumps(decision["row_filters"]))print("column masks:", json.dumps(decision["column_masks"]))print("reasons:", "; ".join(decision["reasons"]))# The enforcement layer asks the policy about every table a query reads, then rewrites the query to apply the answer.layer = Enforcer(open_catalog(["crm.learners"]))query = "select support_region, count(*) as learners from crm.learners group by support_region order by support_region"for region, learners in answer(layer, query, "agent-a05"):   # the layer adds the agent's region to the query before the engine runs it    print(f"learners agent-a05 sees in {region}:", f"{learners:,}")# Compare the emails the agent gets with the platform's data, without printing any.stored = load("crm.learners")                                  # the generated data, not the catalog's copyemails = dict(zip(stored.column("learner_id").to_pylist(), stored.column("email").to_pylist()))seen = answer(layer, "select learner_id, email from crm.learners", "agent-a05")   # the agent's own query, with no region in itprint("emails agent-a05 sees, as stored:", f"{sum(email == emails[learner] for learner, email in seen):,} of {len(seen):,}")print("learners in the platform's data:", f"{stored.num_rows:,}")
Saídapython support-region-enforced.py
allow: True
row filters: [{"column": "support_region", "equals": "emea"}]
column masks: {}
reasons: support may read crm.learners
learners agent-a05 sees in emea: 1,581
emails agent-a05 sees, as stored: 1,581 of 1,581
learners in the platform's data: 5,000

A camada aplicou a região dentro da consulta, de modo que o SQL do agente não precisou fazê-lo e não poderia evitá-lo. A decisão permite a leitura, com o filtro de linha [{"column": "support_region", "equals": "emea"}] sobre a região do próprio agente e as máscaras de coluna {}, já que o suporte é o grupo que precisa dos dados de contato. Seu motivo é support may read crm.learners. A consulta do agente não tem filtro de região, e mesmo assim retorna 1,581 alunos, todos da EMEA, dos 5,000 que a plataforma mantém. Os e-mails voltam como estão armazenados, 1,581 of 1,581, porque a decisão não mascara nada.

O regopy é o binding em Python do rego-cpp, a implementação em C++ do Rego feita pela Microsoft, que oferece suporte ao Rego v1.18.1 conforme o OPA o define (README do rego-cpp na versão v1.5.2). O regopy difere do OPA em aspectos que o capítulo 5 lista, por isso o OPA continua sendo a referência para qualquer coisa em produção. O capítulo 6 mostra por que a camada substitui tabelas inteiras, em vez de mascarar colunas nos pontos em que a consulta as nomeia.

Regra prática: escreva as regras de acesso como uma única política no repositório, que nega por padrão e devolve a decisão como dados: permissão, filtros de linha e máscaras de coluna. Aplique essa decisão em uma única camada que reescreva toda consulta antes de o motor executá-la, e forneça aos usuários as respostas dessa camada, nunca a conexão do motor. Quando um motor puder consultar a própria política, como o Trino pode consultar o OPA, deixe o motor ser essa camada.

Reprove o pull request que adiciona uma coluna sem classificação

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

A verificação do catálogo comprova que o catálogo está completo no dia em que roda, e a plataforma muda toda semana. Uma verificação que depende de alguém lembrar de executá-la é rodada raramente e lida ainda menos. Rodada em todo pull request, onde seu código de saída pode reprová-lo, a mesma verificação se torna um portão, e seus achados aparecem onde os engenheiros já trabalham. Os autores do Tricorder, a plataforma de análise de código do Google, constataram repetidamente que, quando os desenvolvedores precisam abrir um painel ou executar uma ferramenta de linha de comando separada, o uso da análise cai (Sadowski et al., 2015). Essa é a experiência de uma empresa com análise de código, não um dado, mas as verificações de governança atingem as mesmas pessoas. Um portão também reprova um pull request apenas pelo que ele altera, de modo que um achado já presente na main é reportado com seu responsável e não reprova nenhum pull request que o deixe como está.

O módulo do livro para isso é lib.ci, o job de governança da plataforma. Uma mudança de esquema na plataforma é uma migração, uma instrução alter table em um arquivo na pasta migrations/ da branch. Cada lado de um pull request é um checkout em sua própria pasta, um da main e outro da branch. Para cada lado, lib.ci.run constrói uma plataforma temporária, um catálogo novo montado da forma como a plataforma roda. Ele contém as tabelas de origem, as migrações daquele lado, seus metadados gravados no catálogo e seus pipelines. Executa as verificações indicadas sobre a plataforma da branch, executa-as apenas sobre a da main para conhecer o que já existe ali, e compara os achados pelo ID.

Esta seção executa uma verificação, coverage. A verificação de cobertura é a verificação do catálogo, lib.metadata.problems, executada sobre a plataforma da branch, e, para cada coluna que ninguém classificou, acrescenta o que uma regra sobre nomes de colunas sugere, a partir das regras que o capítulo 3 escreve.

O pull request da equipe de CRM adiciona, em uma migração, uma coluna com o e-mail de trabalho dos alunos e esquece os metadados da coluna, de modo que a verificação de cobertura tem algo a encontrar:

unclassified-column-fails.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 Aprovado
"""The CRM team's pull request adds a column to crm.learners and no metadata for it; the coverage check runs on its branch andon main. The point rests on the exit code line: the pull request's own finding fails the job, and the findings on main don't."""from lib import cimain = ci.checkout()                      # the main branch: the governance files and pipelines, and no migrations yetbranch = ci.checkout(main)                # the pull request's branch, starting from main# The pull request's only change: a migration that adds the column, with no metadata for it.(branch / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")print("files the pull request changes:", ", ".join(ci.changed(main, branch)))# Build a scratch platform from each side, run the coverage check on both, and compare their findings by ID.report = ci.run(main, branch, checks=["coverage"])for line in ci.lines(report):    if not line.startswith("change "):    # schema changes are chapter 10's report        print(line)for line in ci.totals(report):    if line.startswith(("findings the pull request introduces", "findings already on main", "exit code")):        print(line)
Saídapython unclassified-column-fails.py
files the pull request changes: migrations/0001-add-work-email.sql
coverage: failed, findings 3, new 1, on main 2, waived 0, 12 tables checked
coverage/ai.review_corpus: no metadata; on main, owner team-platform
coverage/crm.learners.work_email: not classified; its name suggests personal
coverage/marketing.audience: no metadata; on main, owner team-platform
job: failed
findings the pull request introduces: 1
findings already on main: 2
exit code: 1

O pull request é reprovado por 1 achado próprio, a coluna sem classificação. O arquivo que ele altera é migrations/0001-add-work-email.sql, e a verificação de cobertura reporta failed, findings 3, new 1, on main 2, waived 0, 12 tables checked, que conta as oito tabelas de origem da plataforma e as quatro que seus pipelines gravam. O novo achado é crm.learners.work_email, reportado como not classified; its name suggests personal. A regra de nome corresponde a email, que sugere a classificação, e seu ID, coverage/crm.learners.work_email, permanece o mesmo de uma execução para outra, por isso pode ser discutido e contado.

Os achados já presentes na main existiam antes do pull request: coverage/ai.review_corpus e coverage/marketing.audience, a tabela que a seção de linhagem encontrou sem descrição. Ninguém é dono de nenhuma das duas tabelas, então o job nomeia a equipe de plataforma, a equipe responsável pelas tabelas sem dono. O job termina com código de saída 1, de modo que o pull request permanece reprovado até que a coluna tenha uma classificação, e os achados na main não reprovam nenhum pull request que os deixe como estão. O job do capítulo 10 executa as verificações dos capítulos 2 a 7 no mesmo pull request, 11 delas.

Regra prática: Execute cada verificação de governança como um único job em todo pull request, exigido pela proteção de branch, e reprove-o pelo código de saída diante de qualquer achado que o pull request introduza. Reporte os achados já presentes na branch main com seus responsáveis, sem reprovar o pull request por causa deles. Registre cada achado no próprio pull request, sob um ID que permaneça o mesmo de uma execução para outra, com o que deve ser feito a respeito. Execute as mesmas verificações também de forma agendada sobre o catálogo de produção, para o que muda fora dos pull requests.

O que dá errado em produção

A governança falha sem erro em duas situações que as partes acima tratam: uma planilha que ninguém atualiza, e uma política que outra ferramenta contorna. A primeira é o motivo de os metadados serem código, e a segunda, o motivo de a aplicação ficar em um único lugar.

Uma planilha de governança que ninguém atualiza

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

A planilha de que este capítulo partiu lista tabelas e colunas, com uma classificação ao lado de cada uma, e uma planilha descreve o esquema no dia em que foi escrita. Esquemas não ficam parados. Um estudo de dez aplicações de banco de dados de código aberto, com mais de 160,000 revisões no total, aponta como primeira conclusão principal que os esquemas de banco de dados evoluem com frequência ao longo da vida de uma aplicação (Qiu, Li and Su, 2013). O estudo cobre bancos de dados de aplicações, não data warehouses, mas toda mudança que adiciona uma coluna acrescenta uma que a planilha não lista.

Pegue a planilha da plataforma, um inventário de crm.learners exportado como CSV, uma linha por coluna. Em seguida, a migração da equipe de CRM do pull request acima adiciona work_email. Compare-a com o catálogo depois da migração para descobrir o que ela deixa de fora:

spreadsheet-misses-new-column.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 Aprovado
"""A governance inventory kept as a spreadsheet, exported before a schema change, then compared with the catalog after it.The point rests on the two work_email lines: the spreadsheet doesn't list the column, and the check finds it unclassified."""import csvimport iofrom lib import ci, metadatafrom lib.catalog import open_catalogplatform = open_catalog(["crm.learners"])described = metadata.load()# The inventory: one row per column of crm.learners, exported on the day someone was asked for one.inventory = io.StringIO()writer = csv.writer(inventory)writer.writerow(["table", "column", "classification"])for field in platform.load_table("crm.learners").schema().fields:    # Metadata is keyed by Iceberg field ID, not by name, so the lookup survives a rename.    writer.writerow(["crm.learners", field.name, described["crm.learners"].columns[field.field_id].classification])# Later, the CRM team's migration adds a column for learners' work email, applied as an Iceberg schema change.ci.migrate(platform, "alter table crm.learners add column work_email varchar;")rows = list(csv.DictReader(io.StringIO(inventory.getvalue())))print("columns the spreadsheet lists:", len(rows))print("of them without a classification, by the spreadsheet:", sum(not row["classification"] for row in rows))  # a blank classification cell: a column the spreadsheet never classifiedlive = [field.name for field in platform.load_table("crm.learners").schema().fields]print("columns crm.learners has:", len(live))print("columns the spreadsheet doesn't list:", ", ".join(sorted(set(live) - {row["column"] for row in rows})))for problem in metadata.problems(platform, described):    print("the check against the catalog finds:", problem)
Saídapython spreadsheet-misses-new-column.py
columns the spreadsheet lists: 15
of them without a classification, by the spreadsheet: 0
columns crm.learners has: 16
columns the spreadsheet doesn't list: work_email
the check against the catalog finds: crm.learners.work_email: not classified

A planilha parece completa e deixa de fora uma coluna. Segundo ela mesma, lista 15 colunas, e 0 delas não têm classificação. A tabela tem 16 colunas, e a coluna que ela não lista é work_email. Nada na planilha pode mostrar isso, porque nada a compara com o catálogo. lib.metadata.problems, a verificação contra o catálogo, percorre o catálogo e encontra crm.learners.work_email: not classified, a mesma constatação que reprova o pull request da equipe de CRM. Em nossa experiência, uma cópia dos metadados mantida à mão, seja uma planilha, uma página de wiki ou um dicionário de dados, fica desatualizada na primeira mudança de esquema, e nada avisa que isso aconteceu.

Regra prática: Nunca mantenha metadados de governança em um documento que ninguém verifica. Mantenha-os em um arquivo revisado que um teste compara com o catálogo ativo, em cada pull request e em uma programação. Se as pessoas precisarem de uma planilha, gere-a a partir do arquivo e registre nela quando foi gerada.

Uma política que uma ferramenta aplica e outra contorna

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

Uma política protege apenas as leituras que passam pelo que a aplica. O Trino aplica filtros de linhas somente quando recebe a indicação de onde buscá-los; portanto, sem a configuração opa.policy.row-filters-uri, ele não aplica filtragem de linhas alguma (Trino 484, controle de acesso com OPA). A especificação do catálogo REST do Iceberg, na versão 1.12.0, permite que um catálogo devolva restrições de leitura junto com uma tabela, e afirma que "Um leitor que oferece suporte a restrições de leitura deve falhar em qualquer leitura da tabela carregada que não consiga aplicar integralmente uma restrição devolvida" (Especificação do catálogo REST, 1.12.0). A especificação dá ao leitor um sinal para acesso delegado, o cabeçalho X-Iceberg-Access-Delegation, mas nenhum sinal para restrições de leitura. Por isso, um catálogo não consegue saber quais leitores aplicarão as suas restrições. O cliente REST do PyIceberg, na versão 0.12.0, não lê nenhuma delas (código-fonte). Recomendamos que um catálogo que devolva restrições de leitura conceda acesso ao armazenamento somente a motores que as apliquem.

A camada de imposição mantém agent-a05 restrito à EMEA. No entanto, há caminhos que contornam a camada, pois qualquer componente com o acesso do catálogo pode ler os arquivos da tabela. Leia a tabela contornando a camada duas vezes: com o DuckDB por meio de lib.warehouse.connect, que a própria camada usa, como faria um notebook, e com a varredura própria do PyIceberg, como faria qualquer leitor que tenha o acesso do catálogo:

read-around-the-layer.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""The same table, read three ways: through the enforcement layer, and around it with DuckDB and with PyIceberg. The pointrests on the two lines around the layer, which return every region where the layer returns only EMEA's."""from collections import Counterfrom lib import warehousefrom lib.catalog import open_catalogfrom lib.enforce import Denied, Enforcer, answerplatform = open_catalog(["crm.learners"])query = "select support_region, count(*) from crm.learners group by support_region order by support_region"def show(rows):    return ", ".join(f"{region} {learners:,}" for region, learners in rows)layer = Enforcer(platform)print("through the enforcement layer, as agent-a05:", show(answer(layer, query, "agent-a05")))# A notebook with DuckDB on the same catalog: the same SQL, and no policy in the way.print("DuckDB on the same catalog:", show(warehouse.connect(platform).sql(query).fetchall()))# Any reader that holds the catalog's access, here PyIceberg's own scan: no SQL to rewrite at all.scan = platform.load_table("crm.learners").scan(selected_fields=("support_region", "email")).to_arrow()print("PyIceberg's scan of the table:", show(sorted(Counter(scan.column("support_region").to_pylist()).items())))print("emails PyIceberg's scan returns:", f"{scan.num_rows - scan.column('email').null_count:,}")  # rows whose email isn't null# lib.warehouse builds each table's view on a scan it registers under a name of its own. Through the layer, it's denied.try:    answer(layer, "select count(*) from scan_crm_learners", "agent-a05")except Denied as reason:    print("the layer, asked for the raw scan:", reason)
Saídapython read-around-the-layer.py
through the enforcement layer, as agent-a05: emea 1,581
DuckDB on the same catalog: americas 2,276, apac 1,143, emea 1,581
PyIceberg's scan of the table: americas 2,276, apac 1,143, emea 1,581
emails PyIceberg's scan returns: 5,000
the layer, asked for the raw scan: not a table in the catalog: scan_crm_learners

Um leitor fora da camada recebe todas as regiões, porque a política nunca foi consultada. Pela camada, a consulta do agente devolve emea 1,581. O mesmo SQL no DuckDB, sem camada na frente, devolve americas 2,276, apac 1,143, emea 1,581. A varredura do PyIceberg, que não tem SQL a reescrever, devolve americas 2,276, apac 1,143, emea 1,581, com 5,000 e-mails. O mesmo desvio ocorre em produção sempre que um segundo motor, um job Spark ou um script com credenciais de armazenamento lê os arquivos que o motor governado lê.

lib.warehouse constrói a visão de cada tabela sobre uma varredura que ele registra sob um nome próprio, scan_crm_learners para esta tabela, de modo que a conexão da camada também contém a varredura bruta. A última linha da saída mostra a resposta da camada quando uma consulta menciona essa varredura: not a table in the catalog: scan_crm_learners. Esse é o projeto que o capítulo 6 segue: impõe a política em um único lugar e nega qualquer outra leitura de dados, tudo o que não for uma tabela do catálogo. Em produção, esse lugar é o motor pelo qual as ferramentas consultam, como argumenta o capítulo 6. E, como as permissões de armazenamento fazem parte da imposição, somente esse motor e os jobs que gravam as tabelas devem poder ler os arquivos.

Regra prática: Escolha um único lugar que aplique a política, o motor pelo qual todas as ferramentas consultam, e conceda credenciais de armazenamento apenas a ele e aos jobs que gravam as tabelas, nunca a pessoas ou notebooks. Negue, nesse lugar, toda consulta que leia dados que não sejam por meio de uma tabela do catálogo. Antes de considerar uma tabela protegida, liste tudo o que pode ler os seus arquivos, e trate como desvio qualquer leitor que não consulte a política, a menos que seja um job cujas saídas estejam catalogadas e classificadas como as tabelas que ele lê.

O que este capítulo decidiu

Última alteração na edição 2026.11.27
  • A governança são quatro tipos de código em um único repositório: um arquivo de metadados, o código que envia os eventos de linhagem de cada job, uma política de acesso em Rego e verificações que rodam em cada pull request. Apenas um deles é um motor de políticas.
  • Cada tabela tem uma equipe proprietária, nunca uma pessoa, e cada coluna tem uma de quatro classificações: public, internal, personal ou sensitive. Elas ficam em governance/metadata.toml, indexadas pelo ID de campo do Iceberg, e o catálogo é testado contra o arquivo percorrendo o catálogo.
  • Cada execução de pipeline envia eventos OpenLineage, com a linhagem de colunas extraída do seu SQL, incluindo as colunas usadas para juntar e filtrar linhas.
  • Decisões de acesso são dados: permitir, filtros de linhas e máscaras de colunas, a partir de uma única política que nega por padrão. Uma camada de aplicação as aplica a toda consulta e nega toda leitura que não seja de uma tabela do catálogo.
  • Metadados ausentes falham de forma restritiva: a política de acesso trata uma coluna que ninguém classificou como sensitive, e uma tabela que ninguém descreveu permanece como um achado em todos os relatórios até que alguém a descreva.
  • O job de governança roda em cada pull request, falha nos achados que o pull request introduz e informa os achados já presentes na branch main, com seus responsáveis.
  • Tudo roda em um único processo, offline, sobre os substitutos listados no início deste capítulo. A governança feita dessa forma é um conjunto de regras pequenas, cada uma verificada onde os dados mudam, de modo que uma lacuna nos metadados aparece como uma verificação que falha, e não como uma surpresa em um relatório. Os capítulos seguintes testam cada regra por vez, sobre as tabelas da própria plataforma.

Este capítulo, nesta edição

Edição 2026.11.31Exemplos aprovados em 19 de nov de 20266 de 6 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 1 de 10: Governança de ponta a ponta

  1. Catalogue uma tabela com seu dono e suas classificações
  2. Capturar o lineage de colunas de um pipeline
  3. Aplique uma decisão de acesso a uma consulta
  4. Reprove o pull request que adiciona uma coluna sem classificação
  5. O que dá errado em produção
  6. Uma planilha de governança que ninguém atualiza
  7. Uma política que uma ferramenta aplica e outra contorna
  8. O que este capítulo decidiu

Voltar ao topoTodos os capítulos