Um catálogo que você pode testar
Cerca de 41 minutos min de leitura, com 11 exemplos em 12 seções.
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
Nesta página
- Mantenha os metadados em um arquivo revisado
- Indexar os metadados de coluna pelo ID do campo
- Escreva as descrições no esquema da tabela
- Uma edição de descrição é uma alteração de esquema
- Teste o catálogo contra os metadados
- Detecte mudanças de esquema antes que os metadados fiquem desatualizados
- Classifique IDs pseudonimizados para junção
- Gerar rascunhos de metadados com um modelo local
- Exemplos em um prompt podem entregar a resposta
- Meça onde os rascunhos do modelo estão errados
- O que dá errado em produção
- O que este capítulo decidiu
Ao final deste capítulo, você poderá manter os metadados de um catálogo como código. Cada tabela terá um dono e um domínio, e cada coluna, uma descrição e uma classificação, em um arquivo que sua equipe revisa. O arquivo é indexado por chave, para que uma renomeação não possa perder nada, é gravado no catálogo Iceberg e é verificado por um teste que falha quando algo está faltando. Você também terá um modelo local que rascunha descrições e classificações, e medirá com que frequência os rascunhos estão errados antes que alguém os aceite.
O catálogo da plataforma tem três problemas. Seu armazém, um catálogo Iceberg mantido por uma plataforma de aprendizagem online cujos pipelines continuam adicionando tabelas, contém oito tabelas de origem em namespaces com o nome das equipes que as executam, como crm.learners e support.tickets. Seus pipelines criam tabelas de relatórios a partir dessas origens e continuam criando tabelas, e nada informa quem é o dono de marketing.audience, a lista de alunos para quem o marketing pode enviar e-mails, nem se ai.review_corpus, o texto que o assistente do curso da plataforma lê, contém dados pessoais. Uma coluna renomeada em uma mudança de esquema pode perder sua classificação sem que ninguém perceba. E toda tabela que um pipeline adiciona precisa de uma descrição e de uma classificação para cada uma de suas colunas, escritas à mão, o que é tão lento que as equipes acabam pulando essa etapa.
O Capítulo 1 construiu uma versão aproximada de toda a plataforma governada. Este capítulo torna o catálogo dessa plataforma sólido.
Os exemplos do capítulo usam cinco dos módulos compartilhados do livro. lib.catalog.open_catalog constrói um catálogo novo com as tabelas da plataforma em uma pasta temporária, sobre o catálogo SQL do PyIceberg com SQLite, que a documentação do PyIceberg recomenda apenas para exploração e desenvolvimento (configuração do PyIceberg). lib.pipelines.run executa um dos pipelines da plataforma e grava sua saída no catálogo. lib.warehouse.connect abre o DuckDB sobre as tabelas do catálogo, para que uma consulta possa citá-las como a plataforma faz, e lib.policy avalia as políticas de acesso da plataforma, que o Capítulo 5 escreve. E lib.metadata, que este capítulo constrói aos poucos, carrega os metadados da plataforma, grava-os no catálogo e verifica o catálogo contra eles.
Mantenha os metadados em um arquivo revisado
Os metadados de um catálogo são o que você sabe sobre cada tabela que os dados não dizem: quem a possui, a qual parte do negócio ela pertence, o que ela guarda e como cada coluna deve ser protegida. Servidores de catálogo guardam isso em um banco de dados próprio e o editam em uma página web. Isso funciona para navegar, mas uma mudança feita ali é invisível à revisão de código, e nenhum teste consegue dizer se o catálogo está completo. Manter os metadados em um arquivo no repositório, ao lado dos pipelines que criam as tabelas, faz de cada mudança um diff que alguém aprova, e dá a um teste algo com que comparar o catálogo.
O arquivo da plataforma é governance/metadata.toml. Para cada tabela, ele registra:
- um proprietário, a equipe responsável pela tabela, nunca uma pessoa;
- um domínio, a parte do negócio a que a tabela pertence;
- uma descrição da tabela;
- para cada coluna, seu nome, uma descrição e uma classificação.
Uma classificação é um de quatro valores, ordenados do menos ao mais protegido:
| Classificação | Significado | Na plataforma |
|---|---|---|
public |
Pode ser mostrada a qualquer pessoa fora da plataforma | O título de um curso |
internal |
Para a equipe da plataforma, e não identifica uma pessoa por si só | Quando uma matrícula começou |
personal |
Identifica uma pessoa ou diz algo sobre ela | O e-mail de um aluno, ou textos que ele escreveu |
sensitive |
Dados cujo vazamento causaria dano direto a alguém | Um número de cartão, a conta bancária de um instrutor |
A ordem importa: quando uma coluna é formada a partir de várias outras, como costumam ser as colunas de saída de um pipeline, prevalece a classificação mais restrita, e lib.metadata.stricter a devolve. Carregado e contado, o arquivo mostra o que ele cobre:
1"""Loads the metadata file and counts what it describes, then prints four of the learners table's columns, looked up by2field ID. The prose's point rests on the `country` and `city` lines, whose descriptions give the reason for each classification."""3from collections import Counter45from lib import metadata67described = metadata.load() # governance/metadata.toml8columns = [column for table in described.values() for column in table.columns.values()]9print("tables described:", len(described))10print("columns described:", len(columns))11counts = Counter(column.classification for column in columns)12for level in metadata.LEVELS:13 print(f"columns classified {level}:", counts[level])14owners = sorted({table.owner for table in described.values()})15print("teams that own tables:", len(owners))16print("owners:", ", ".join(owners))1718learners = described["crm.learners"]19print("crm.learners owner:", learners.owner)20print("crm.learners domain:", learners.domain)21for field_id in (1, 3, 5, 6): # field IDs, which the file keys columns by, not positions in the table22 column = learners.columns[field_id]23 print(f"crm.learners field {field_id}:", column.name, "|", column.classification, "|", column.description)
python metadata-model.pytables described: 10
columns described: 77
columns classified public: 6
columns classified internal: 57
columns classified personal: 12
columns classified sensitive: 2
teams that own tables: 5
owners: team-analytics, team-billing, team-crm, team-learning, team-support
crm.learners owner: team-crm
crm.learners domain: crm
crm.learners field 1: learner_id | internal | The learner's ID, which the platform's other tables use for the learner. Identifies a person through this table's personal columns.
crm.learners field 3: email | personal | The email the learner signs in with.
crm.learners field 5: country | internal | The learner's country, as an ISO 3166 two-letter code.
crm.learners field 6: city | personal | The learner's city. Identifying together with date of birth.
A maioria das colunas é internal, porque a maior parte de um data warehouse são IDs, datas e contagens: 57 de suas 77 colunas são. As colunas protegidas são poucas. Entre as colunas do arquivo, 12 são classificadas como personal, e a classificação sensitive guarda o número do cartão em billing.payments e a conta de repasse em crm.instructors. O arquivo cobre as oito tabelas de origem e as duas tabelas de relatório em que os analistas da plataforma se apoiam, e cada tabela pertence a uma de 5 equipes proprietárias. O ponto é que cada descrição traz o motivo de sua classificação. country é internal porque um país sozinho não distingue ninguém, enquanto city é personal porque, como diz sua descrição, identifica um aluno junto com sua data de nascimento.
Os quatro valores e a regra de um único proprietário são nossos, não de um padrão. O Open Data Contract Standard (ODCS) registra um domínio, um proprietário como um papel de texto livre em uma equipe, e uma classificação de texto livre (ODCS v3.2.0), e seu esquema JSON aceita qualquer string como classificação (esquema JSON do ODCS). Os servidores de catálogo também diferem. O DataHub tipifica seus proprietários (tipos de propriedade), e permite que um ativo pertença a apenas um domínio por vez (domínios). Ele classifica colunas com termos de glossário (glossário de negócio).
O OpenMetadata permite que um proprietário seja uma equipe ou vários usuários, uma regra aplicada na instância e ativada por padrão (propriedade de dados). Suas classificações são um vocabulário controlado de tags (classificação), como PII.Sensitive (tags de PII). No Unity Catalog do Databricks, todo objeto tem um proprietário, que detém todos os privilégios sobre ele (privilégios). Tabelas e colunas têm tags (tags), e uma tag governada assume valores "apenas de um conjunto predefinido de valores permitidos" (tags governadas). Um arquivo como o da plataforma se mapeia em cada um deles. Nenhum desses documentos descreve a verificação que o teste deste capítulo faz: uma equipe, nunca uma pessoa, como proprietária de cada tabela, e uma das quatro classificações em cada coluna.
Regra prática: Mantenha proprietários, domínios, descrições e classificações em um arquivo no repositório, revisado como os pipelines. Use uma lista fechada de classificações, ordenadas pelo grau de proteção que cada uma exige, e uma equipe proprietária por tabela. Se sua organização edita metadados na página web de um servidor de catálogo, faça um dos lados ser a fonte e gere o outro a partir dele; duas fontes que aceitam edições se afastam uma da outra.
Indexar os metadados de coluna pelo ID do campo
O arquivo de metadados da plataforma indexa cada coluna por um número, e não pelo nome, porque os nomes mudam. O Iceberg atribui a cada coluna um ID do campo, um inteiro único dentro do esquema da tabela, e a especificação exige que uma renomeação mantenha esse ID: "Renaming an existing field must change the name, but not the field ID" (especificação de tabelas do Iceberg). Os leitores também localizam os valores por esse ID, já que o Iceberg seleciona as colunas de um arquivo de dados pelo ID do campo, de modo que uma coluna renomeada continua lendo os arquivos gravados antes da renomeação (especificação de tabelas do Iceberg). Metadados indexados por nome não têm onde se apoiar: depois de uma renomeação, o nome antigo não aponta para nada e o nome novo não tem entrada.
A equipe de CRM da plataforma quer que crm.learners.email passe a se chamar contact_email, para abrir espaço para um e-mail de trabalho. Montada em um catálogo temporário, a renomeação mostra o que uma cópia indexada por nome perde. A coluna é consultada no arquivo de metadados, indexado pelo ID do campo, e em uma cópia indexada por nome, como costuma ser uma planilha de colunas:
1"""Renames crm.learners.email in a scratch catalog, then looks the column up by field ID and by name. The prose's point2rests on the two classification lines, which disagree, and on the check's `renamed from email` line."""3from lib import catalog, metadata, policy45platform = catalog.open_catalog(["crm.learners"])6described = metadata.load()7by_id = described["crm.learners"].columns # the book's metadata: keyed by field ID8by_name = {column.name: column.classification for column in by_id.values()} # a spreadsheet's: keyed by name910learners = platform.load_table("crm.learners")11with learners.update_schema() as update:12 update.rename_column("email", "contact_email") # renames in place: the field ID stays13field = learners.schema().find_field("contact_email")14print("contact_email field ID:", field.field_id)15values = learners.scan(selected_fields=("contact_email",)).to_arrow().column("contact_email")16print("values read under the new name:", f"{len(values) - values.null_count:,} of {len(values):,}")1718print("classification of contact_email, looked up by name:", by_name.get("contact_email"))19print("classification of contact_email, looked up by field ID:", by_id[field.field_id].classification)20names = {f.name for f in learners.schema().fields}21print("name-keyed entries that match no column:", ", ".join(sorted(set(by_name) - names)))22for problem in metadata.problems(platform, described):23 print("check:", problem)24# The policies read classifications by name, generated from the file, which still says email.25decision = policy.decide(policy.request("agent-a01", "crm.learners", ["contact_email"]))26print("a support agent reading contact_email sees it as:", decision["column_masks"].get("contact_email", "shown"))
python rename-orphans-name-keys.pycontact_email field ID: 3
values read under the new name: 5,000 of 5,000
classification of contact_email, looked up by name: None
classification of contact_email, looked up by field ID: personal
name-keyed entries that match no column: email
check: crm.learners.contact_email: renamed from email since it was reviewed
a support agent reading contact_email sees it as: redact
As duas consultas divergem, e só a que é indexada pelo ID do campo sabe que a coluna é a mesma. A renomeação manteve o ID do campo 3, e 5,000 of 5,000 valores chegaram sob o novo nome. Indexada por nome, contact_email não tem classificação, e a entrada de email não corresponde a nenhuma coluna. Indexada pelo ID do campo, a coluna continua sendo personal. Uma verificação construída sobre a cópia indexada por nome informaria uma coluna sem classificação e não perceberia que uma coluna classificada havia desaparecido.
O arquivo indexado pelo ID do campo percebe a renomeação, e lib.metadata.problems, a verificação em que este capítulo se apoia, a informa: contact_email: renamed from email since it was reviewed. O fato de os dados sobreviverem a uma renomeação não torna a renomeação inofensiva: uma consulta SQL que cita email deixa de funcionar, e o mesmo vale para qualquer sistema que conheça colunas apenas pelo nome. As políticas de acesso da plataforma, que o capítulo 5 escreve, recebem pelo nome as colunas que uma consulta lê; por isso leem as classificações em uma visão indexada por nome que lib.policy gera a partir desse arquivo. Quando a verificação falha, alguém atualiza o nome no arquivo, relê a descrição, e a visão gerada acompanha a mudança. Até lá, a visão não tem entrada para contact_email, e as políticas tratam uma coluna que não encontram como sensitive. Um agente de suporte, que vê todas as outras colunas pessoais de crm.learners, recebe contact_email como redact: a renomeação falha fechada (nega o acesso por padrão), e o suporte percebe primeiro.
Regra prática: Indexe os metadados de coluna pelo ID do campo, com o nome ao lado para as pessoas. Trate um nome que deixou de corresponder como motivo para revisar a descrição da coluna, não como uma coluna nova. Quando um sistema conhecer colunas apenas pelo nome, gere a visão indexada por nome a partir do arquivo indexado pelo ID, nunca a mantenha à mão.
Escreva as descrições no esquema da tabela
O arquivo de metadados é onde os metadados da plataforma são revisados. Pessoas e ferramentas que leem uma tabela, porém, procuram no catálogo, e por isso parte dos metadados precisa ser copiada para lá. A questão é onde cada informação pertence no catálogo, e o Iceberg responde a uma parte dela: cada coluna pode ter um doc, um comentário opcional que acompanha o esquema (especificação de tabela do Iceberg). Uma tabela também tem propriedades, um mapa de strings, mas a especificação diz que esse mapa "é usado para controlar configurações que afetam a leitura e a escrita e não se destina a ser usado para metadados arbitrários".
Por isso seguimos a especificação até onde podemos. As descrições das colunas vão para doc, e as classificações permanecem no arquivo, onde as políticas e as verificações as leem. O proprietário e o domínio vão para duas propriedades da tabela, como um apontador para ferramentas que leem apenas a tabela, de modo que qualquer pessoa com uma tabela e sem o repositório consiga encontrar a equipe a quem perguntar. Essa última escolha contraria a intenção declarada da especificação, e mantemos isso apenas para esses dois valores curtos.
A resposta do próprio projeto Iceberg é um canal separado. A especificação do catálogo REST do Iceberg 1.12.0 adiciona labels, a titularidade (quem é responsável) ou a classificação que um catálogo devolve junto com a tabela, por tabela e por ID de campo, mantidas fora das propriedades de propósito (especificação do catálogo REST). A mudança veio com a pull request 15750. O cliente REST do PyIceberg 0.12.0 não as lê (código-fonte).
lib.metadata.apply faz a cópia. Para cada tabela que o arquivo descreve e que o catálogo contém, ele grava cada descrição na doc da coluna correspondente, e o proprietário e o domínio nas propriedades, alterando apenas o que difere. Em um catálogo novo com as oito tabelas de origem da plataforma, apply mostra o que muda:
1"""Writes the metadata file into a fresh catalog of the eight source tables, then applies it again. The prose's point rests2on the second `tables changed` line, which is zero: applying a file the catalog already matches writes nothing."""3from lib import catalog, metadata45platform = catalog.open_catalog() # all eight source tables, with no metadata yet6described = metadata.load()7print("crm.learners schema ID before:", platform.load_table("crm.learners").schema().schema_id)8print("tables changed:", len(metadata.apply(platform, described)))910learners = platform.load_table("crm.learners")11print("crm.learners schema ID after:", learners.schema().schema_id)12print("email's doc, in the Iceberg schema:", learners.schema().find_field("email").doc)13scanned = learners.scan(selected_fields=("email",), limit=1).to_arrow() # one row is enough: the schema comes back with it14# Arrow keeps an Iceberg column's doc in the field's metadata, under the bytes key b"doc".15print("email's doc, in a scan's Arrow schema:", scanned.schema.field("email").metadata[b"doc"].decode())16print("crm.learners properties:", ", ".join(f"{k}={v}" for k, v in sorted(learners.properties.items())))17print("tables changed by applying again:", len(metadata.apply(platform, described)))
python apply-metadata.pycrm.learners schema ID before: 0
tables changed: 8
crm.learners schema ID after: 1
email's doc, in the Iceberg schema: The email the learner signs in with.
email's doc, in a scan's Arrow schema: The email the learner signs in with.
crm.learners properties: domain=crm, owner=team-crm
tables changed by applying again: 0
Aplicar o arquivo grava os metadados no catálogo, e aplicá-lo de novo não grava nada, de modo que apply pode rodar a cada merge. A primeira execução alterou 8 tabelas. A descrição de email agora está no esquema Iceberg e no esquema Arrow que uma leitura devolve, de modo que o código que lê a tabela pelo PyIceberg a recebe junto com os dados, sem precisar saber que o arquivo existe. As propriedades guardam owner=team-crm e domain=crm. Uma segunda execução alterou 0 tabelas. O ID do esquema de crm.learners passou de 0 para 1, embora nenhum ID, nome ou tipo de coluna tenha mudado, o que é o assunto de a próxima subseção.
Uma edição de descrição é uma alteração de esquema
A especificação do Iceberg atribui a cada alteração de esquema um novo esquema com ID próprio, que passa a ser o esquema atual da tabela e se junta à lista de esquemas que a tabela mantém (especificação de tabelas do Iceberg). No PyIceberg 0.12.0, editar apenas o atributo doc de uma coluna conta como essa alteração. Altere apenas a descrição de learning.reviews.body, depois que lib.metadata.apply tiver gravado as descrições da plataforma, e observe o ID do esquema:
1"""Changes one column's description after the metadata is applied, then compares schema IDs with field IDs, names and2types. The prose's point rests on the schema ID changing while the shape stays the same, which the assert checks."""3from lib import catalog, metadata45platform = catalog.open_catalog(["learning.reviews"])6metadata.apply(platform, metadata.load()) # the platform's descriptions go in first, so the edit below is the only change7reviews = platform.load_table("learning.reviews")8before = reviews.schema()9print("schema ID before the edit:", before.schema_id)1011with reviews.update_schema() as update: # change one description, nothing else12 update.update_column("body", doc="The review's text, as the learner wrote it. May hold names and emails.")13after = reviews.schema()14assert metadata.shape(before) == metadata.shape(after), "a doc edit changed a field ID, name or type"15print("schema ID after the edit:", after.schema_id)16print("schemas the table keeps:", len(reviews.metadata.schemas))17print("schema ID changed:", before.schema_id != after.schema_id)18print("field IDs, names or types changed:", metadata.shape(before) != metadata.shape(after))
python doc-edit-schema-id.pyschema ID before the edit: 1
schema ID after the edit: 2
schemas the table keeps: 3
schema ID changed: True
field IDs, names or types changed: False
Uma edição de descrição altera o ID do esquema e nada que uma revisão deva comparar. O ID passou de 1 para 2, e a tabela mantém 3 esquemas: o original, o que apply gravou e este. Os IDs, nomes e tipos dos campos são os mesmos, o que lib.metadata.shape compara. Uma regra que exige uma nova classificação sempre que o ID do esquema muda dispararia em toda edição de descrição, e as equipes aprendem a ignorar uma verificação que dispara à toa.
Regra prática: Escreva as descrições das colunas no atributo doc do Iceberg, para que todo leitor da tabela as receba, e mantenha as classificações no arquivo revisado. Coloque no máximo um dono e um domínio nas propriedades da tabela, e explique no seu código por quê. Para decidir se uma alteração de esquema precisa de revisão, compare IDs, nomes e tipos dos campos, nunca IDs de esquema.
Teste o catálogo contra os metadados
Com os metadados aplicados ao catálogo, a questão que resta é se o arquivo cobre tudo o que o catálogo contém. Um teste responde a ela, e ele precisa partir do catálogo: uma verificação que percorre o arquivo encontra problemas apenas em tabelas que alguém já descreveu. lib.metadata.problems lista cada tabela de cada namespace do catálogo e aponta uma tabela sem entrada ou sem proprietário, uma coluna cujo ID de campo não tem classificação, uma classificação que não é uma das quatro e uma coluna renomeada desde que foi revisada.
Na plataforma, as lacunas vêm dos pipelines. Cada pipeline é um create table ... as select ... em pipelines/, e executá-lo cria uma tabela. Execute os quatro pipelines em um catálogo novo e verifique-o, e as lacunas aparecem:
1"""Runs the platform's four pipelines on a fresh catalog, then checks every table in it against the metadata file. The2prose's point rests on the `problems found` line and the two `no metadata` lines that follow it."""3from lib import catalog, metadata, pipelines45platform = catalog.open_catalog()6for name in ("course_performance", "learner_activity", "marketing_audience", "review_corpus"): # each one a file in pipelines/7 print("pipeline output:", pipelines.run(platform, name))89# The eight source tables plus the four outputs the pipelines just created.10tables = [f"{namespace}.{name}" for (namespace,) in platform.list_namespaces() for _, name in platform.list_tables(namespace)]11print("tables in the catalog:", len(tables))12found = metadata.problems(platform, metadata.load())13print("problems found:", len(found))14for problem in found:15 print("problem:", problem)
python metadata-gaps.pypipeline output: analytics.course_performance
pipeline output: analytics.learner_activity
pipeline output: marketing.audience
pipeline output: ai.review_corpus
tables in the catalog: 12
problems found: 2
problem: ai.review_corpus: no metadata
problem: marketing.audience: no metadata
As duas tabelas que falham são as mais importantes. O catálogo contém 12 tabelas, e a verificação encontra 2 problemas: ai.review_corpus: no metadata e marketing.audience: no metadata. As duas tabelas analíticas passam, porque o arquivo as descreve, com IDs de campo que correspondem à ordem de suas listas select.
marketing.audience copia nomes e e-mails de aprendizes de crm.learners, e ai.review_corpus copia o texto livre das avaliações; portanto, ambas contêm dados pessoais, e nenhuma tem um proprietário que responderia por elas. Até que alguém as classifique, a política de acesso da plataforma, governance/policies/access.rego, trata como sensitive toda coluna para a qual não encontra classificação, de modo que a lacuna falha de forma fechada, e não aberta. O capítulo 4 propõe as classificações dessas tabelas a partir da linhagem, ou seja, das colunas de que cada coluna de saída foi construída.
O teste é então uma única linha, assert not metadata.problems(catalog, metadata.load()), executada sempre que o catálogo muda: no pull request que adiciona um pipeline, que o capítulo 10 configura, e em um agendamento contra o catálogo de produção, que captura tabelas criadas fora de qualquer pull request.
Regra prática: Percorra o catálogo, não o arquivo de metadados, para que uma tabela que ninguém descreveu apareça. Faça o teste falhar em qualquer tabela sem proprietário e em qualquer coluna sem uma das quatro classificações, e nunca use como padrão para uma classificação ausente nada além do valor mais protegido. Um pipeline que cria uma tabela é entregue com os metadados dessa tabela, no mesmo pull request.
Detecte mudanças de esquema antes que os metadados fiquem desatualizados
O teste contra o catálogo detecta tabelas novas. As tabelas também mudam por baixo de seus metadados, e cada tipo de mudança exige uma resposta própria. Uma renomeação mantém o ID de campo, então a entrada sobrevive, mas sua descrição pode já estar errada. Uma coluna adicionada recebe um ID de campo que ninguém revisou. Uma coluna removida deixa uma entrada que não descreve nada. E remover uma coluna e adicionar outra com o mesmo nome não traz de volta a coluna antiga: a especificação atribui um novo ID a cada campo adicionado (especificação de tabela do Iceberg), portanto a coluna readicionada é outra coluna.
Mudanças de esquema são frequentes o bastante para que isso importe. Em um estudo de dez aplicações de código aberto, "80% das mudanças de esquema aconteceram em 20-30% das tabelas" (Qiu, Li e Su, 2013). Esse estudo cobre bancos de dados de aplicações, não data warehouses. Se as mudanças de um warehouse se concentrarem do mesmo modo, suas tabelas mais movimentadas são as que terão metadados desatualizados primeiro.
Duas mudanças preparadas em crm.learners mostram as duas verificações funcionando: uma adiciona preferred_name, com descrição mas sem classificação, e a outra remove country e o adiciona de volta. problems e lib.metadata.dropped: a segunda informa entradas cujo ID de campo a tabela não tem mais, e lê os valores da coluna removida da forma como a viagem no tempo do Iceberg faz, ao nomear um snapshot:
1"""Adds an unreviewed column, drops a column and adds it back, then runs both checks and reads the dropped values by time2travel. The prose's point rests on the two field IDs, and on the time-travel line, which still returns every country."""3from pyiceberg.types import StringType45from lib import catalog, metadata67platform = catalog.open_catalog(["crm.learners"])8described = metadata.load()9learners = platform.load_table("crm.learners")10written = learners.current_snapshot() # the snapshot the rows were written in11print("country field ID, before it was dropped:", learners.schema().find_field("country").field_id)1213with learners.update_schema() as update: # a column nobody has reviewed14 update.add_column("preferred_name", StringType(), doc="What the learner asks to be called.")15with learners.update_schema() as update: # drop a column, then add it back16 update.delete_column("country")17with learners.update_schema() as update:18 update.add_column("country", StringType()) # an added field gets a new ID, never the old one1920country = learners.schema().find_field("country")21print("country field ID, after it was added back:", country.field_id)22values = learners.scan(selected_fields=("country",)).to_arrow().column("country")23print("country values after it was added back:", f"{values.null_count:,} nulls of {len(values):,}")24# Minus the one snapshot that wrote the rows: the schema changes wrote none of their own.25print("snapshots the schema changes wrote:", len(learners.metadata.snapshots) - 1)26old = learners.scan(snapshot_id=written.snapshot_id, selected_fields=("country",)).to_arrow().column("country")27print("country values, read by time travel to that snapshot:", f"{len(old) - old.null_count:,} of {len(old):,}")28for problem in metadata.problems(platform, described):29 print("problems():", problem)30for problem in metadata.dropped(platform, described):31 print("dropped():", problem)
python schema-changes-checked.pycountry field ID, before it was dropped: 5
country field ID, after it was added back: 17
country values after it was added back: 5,000 nulls of 5,000
snapshots the schema changes wrote: 0
country values, read by time travel to that snapshot: 5,000 of 5,000
problems(): crm.learners.preferred_name: not classified
problems(): crm.learners.country: not classified
dropped(): crm.learners.country: field 5 is described but no longer in the table
Uma coluna readicionada é uma coluna nova: country voltou como campo 17, e não 5, e uma leitura comum, que usa o esquema atual, em que o campo antigo não existe mais, retorna 5,000 nulls of 5,000 para ela. Ambas as colunas adicionadas não têm classificação, e a descrição dada a preferred_name não conta: uma descrição é um doc no esquema, e uma classificação é uma linha revisada no arquivo.
Os países dos alunos não sumiram. Uma mudança de esquema não grava snapshot (0 aqui), então o snapshot atual da tabela ainda é aquele em que suas linhas foram gravadas. Um snapshot registra o ID do esquema atual da tabela no momento em que foi criado (especificação de tabela do Iceberg), e no PyIceberg 0.12.0, uma leitura que nomeia um snapshot usa esse esquema. Assim, a viagem no tempo até esse snapshot retorna 5,000 of 5,000 países. Remover uma coluna não apaga nenhum de seus valores: o capítulo 7 é onde a plataforma apaga os dados de forma definitiva. dropped informa que a entrada revisada do campo antigo agora não descreve nada. A renomeação da seção sobre IDs de campo é o terceiro tipo de mudança, que problems informa como uma coluna a revisar.
Regra prática: Execute as duas verificações em toda mudança de esquema: problems para colunas que ninguém classificou e renomeações que ninguém releu, e dropped para entradas que não descrevem nada. Remova a entrada de uma coluna removida no mesmo pull request que a remove. Remover uma coluna pessoal não remove seus valores, que a viagem no tempo continua lendo até que os snapshots que os contêm expirem e seus arquivos sejam apagados. Nunca remova e readicione uma coluna para renomeá-la: renomeie-a no lugar, para que ela mantenha seu ID de campo e seus dados.
Classifique IDs pseudonimizados para junção
O arquivo de metadados classifica algumas colunas que apontam para pessoas como internal, e a mais comum delas é learner_id. Trata-se de um número sem significado próprio, e os analistas e cientistas de dados da plataforma precisam dele para juntar matrículas, eventos, pagamentos e tickets entre si. Um ID sem significado próprio, como learner_id, é um identificador pseudonimizado: ele não nomeia ninguém, mas leva a alguém por meio de outra tabela. Um ID alcança mais longe do que sua classificação sugere. O código conta as tabelas que o carregam, junta matrículas a alunos e pergunta à política de acesso quem pode fazer essa junção e ver nomes:
1"""Counts the tables that carry learner_id and how many enrollments one join resolves to an email, then asks the access2policy who sees learners' names and also reads another table's learner_id. The prose's point rests on the enrollments3line and the last line's list of users."""4from lib import catalog, metadata, policy, warehouse56described = metadata.load()7carrying = {name: table.column("learner_id") for name, table in described.items() if table.column("learner_id")} # column() gives None when absent8print("tables with a learner_id column:", len(carrying))9print("learner_id classified as:", ", ".join(sorted({column.classification for column in carrying.values()})))10personal = [c.name for c in described["crm.learners"].columns.values() if c.classification == "personal"]11print("personal columns in crm.learners:", ", ".join(personal))1213con = warehouse.connect(catalog.open_catalog(["crm.learners", "learning.enrollments"]))14found, total = con.execute("""15 -- the left join keeps every enrollment; count(l.email) counts only those whose learner has an email16 select count(l.email), count(*)17 from learning.enrollments e left join crm.learners l on l.learner_id = e.learner_id18""").fetchall()[0] # fetchall returns a list of rows, and this query has exactly one19print("enrollments whose learner_id leads to an email:", f"{found:,} of {total:,}")2021# Who can put a name on another table's learner_id: users who read that table and see crm.learners' names unmasked.22rego, seeing, naming = policy.interpreter(), [], []23for user in policy.data_document()["platform"]["users"]:24 names = policy.decide(policy.request(user, "crm.learners", ["full_name"]), rego)25 if names["allow"] and "full_name" not in names["column_masks"]: # allowed, and not masked: the name shows in clear26 seeing.append(user)27 tables = [t for t in carrying if t != "crm.learners" # the other tables with learner_id this user may read28 and policy.decide(policy.request(user, t, ["learner_id"]), rego)["allow"]]29 naming += [f"{user} ({', '.join(tables)})"] if tables else []30print("users who see learners' names in crm.learners:", ", ".join(seeing))31print("of them, users who read learner_id in another table:", ", ".join(naming))
python pseudonymous-learner-id.pytables with a learner_id column: 7
learner_id classified as: internal
personal columns in crm.learners: full_name, email, phone, city, street_address, date_of_birth, notes
enrollments whose learner_id leads to an email: 20,000 of 20,000
users who see learners' names in crm.learners: agent-a01, agent-a05, agent-a09, marketing-1
of them, users who read learner_id in another table: agent-a01 (support.tickets), agent-a05 (support.tickets), agent-a09 (support.tickets)
Uma junção chega a uma pessoa: 20,000 of 20,000 matrículas levam a um e-mail, e com o e-mail vêm o nome, o telefone, o endereço e a data de nascimento do aluno, que estão entre as colunas personal da tabela. No entanto, learner_id é internal em todas as 7 tabelas que o carregam.
O Regulamento Geral de Proteção de Dados (RGPD) da UE trata dados desse tipo no Considerando 26: "Os dados pessoais submetidos a pseudonimização, que possam ser atribuídos a uma pessoa singular através da utilização de informações suplementares, deverão ser considerados informações sobre uma pessoa singular identificável" (RGPD, Considerando 26). O que o considerando significa para uma determinada plataforma é uma questão para os advogados dela, e não a respondemos.
O que decidimos é como o código do livro trata o ID. internal descreve o que a coluna revela na tabela que a contém, e a descrição de cada learner_id no arquivo de metadados diz o resto, nomeando crm.learners como a tabela que o resolve, assim como a de learning.enrollments faz: "O aluno que se matriculou. Identifica uma pessoa quando combinado com crm.learners." A proteção recai sobre a tabela que resolve o ID. O capítulo 5 decide quem pode ler as colunas pessoais de crm.learners, e as últimas linhas do exemplo perguntam à sua política quem vê os nomes dos alunos ali: agent-a01, agent-a05, agent-a09, marketing-1. Destes, apenas os agentes de suporte também leem um learner_id em outra tabela: agent-a01 (support.tickets), agent-a05 (support.tickets), agent-a09 (support.tickets). Eles podem associar um nome a cada ticket de sua região, e esse é o seu trabalho. O marketing vê nomes, mas não lê nenhuma outra tabela que contenha o ID.
Portanto, é a política, e não a classificação do ID, que decide quem pode fazer a junção. Classificar support.tickets.learner_id como personal não mudaria nada para o suporte, o único grupo que lê a tabela, porque a política já mostra ao suporte todas as colunas pessoais. A eliminação, no capítulo 7, precisa alcançar todas as tabelas que contêm o learner_id de um aluno, qualquer que seja a sua classificação. Chamamos esses IDs de pseudonimizados, nunca de anonimizados.
Regra prática: Classifique um ID pseudonimizado pelo que a sua própria tabela revela, para que as junções de que os seus analistas precisam continuem funcionando, e diga na sua descrição por meio de que tabela ele é resolvido. Proteja a tabela que o resolve e inclua o ID em toda eliminação. Quem pode resolver o ID é uma decisão de acesso: liste os usuários que podem ler, sem mascaramento, tanto o ID quanto as colunas pessoais da tabela que o resolve, e conceda esse par apenas àqueles cujo trabalho é vincular linhas a pessoas.
Gerar rascunhos de metadados com um modelo local
O teste contra o catálogo mostra quais colunas ninguém descreveu, mas não escreve as descrições. Escrever uma descrição e escolher uma classificação para cada coluna é a parte mais lenta da manutenção de um catálogo, e esse trabalho volta com cada tabela que um pipeline adiciona. Um modelo de linguagem pode rascunhar as duas coisas a partir do que uma ferramenta de catálogo consegue mostrar a ele: o nome de uma coluna, seu tipo e alguns de seus valores. A pesquisa sustenta tanto a ajuda quanto os limites. Em um benchmark, dadas instruções e um pipeline de duas etapas, o ChatGPT rotulou os tipos semânticos de colunas de tabelas com "pontuações F1 acima de 85% em configurações zero-shot e one-shot" (Korini and Bizer, 2023). Um estudo sobre descrições de colunas geradas constatou que modelos têm dificuldade com colunas cujo significado é ambíguo, e que essas colunas precisam de contribuição manual de especialistas (Wretblad et al., 2024). Portanto, o rascunho de um modelo é uma proposta que uma pessoa aceita, corrige ou rejeita no pull request. A primeira tarefa é medir o quanto os rascunhos erram, para que a revisão saiba onde olhar.
Os rascunhos do livro, que os exemplos chamam de sugestões de metadados, foram registrados uma única vez por recordings/metadata_suggestions.py, e os exemplos leem esse registro, de modo que nenhum deles chama um modelo. O script executa o Qwen3-1.7B em uma revisão fixada. O modelo é aberto, sob a licença Apache-2.0, de modo que qualquer pessoa pode baixar os mesmos pesos. Com 1.7 bilhão de parâmetros, ele roda em uma CPU, sem GPU, o que mantém os valores de amostra na máquina que o executa. Além disso, ele é ajustado para instruções e tem uma chave que desliga o seu "thinking", o raciocínio que ele escreve de outra forma antes de responder. O script decodifica de forma gulosa, escolhendo o token seguinte mais provável, embora a ficha do modelo sugira amostragem neste modo: "Temperature=0.7, TopP=0.8, TopK=20, and MinP=0" (Qwen3-1.7B). Um registro precisa sair igual quando alguém o refizer, e uma resposta amostrada é apenas um sorteio entre muitos.
Para cada coluna das oito tabelas de origem da plataforma, o modelo viu o nome da tabela, o nome da coluna e o tipo Iceberg, cinco valores da coluna escolhidos com uma semente fixa, e as quatro classificações com os significados da tabela de classificações. Cada significado vem com dois exemplos, e nenhum deles é uma coluna da plataforma. Para sensitive, os exemplos são "um número de documento de identidade do governo ou uma condição de saúde". O modelo foi solicitado a dar uma descrição de uma frase e uma classificação, em JSON. O manifesto do registro indica o modelo, sua revisão, um hash dos prompts e das configurações, e a data, de modo que qualquer pessoa pode registrar de novo e comparar.
Esses cinco valores são dados pessoais sempre que a coluna for pessoal: para support.tickets.body, os tickets que o modelo leu continham nomes de alunos, endereços residenciais, um número de telefone, uma data de nascimento e um número de conta bancária. Um modelo rodando na sua própria máquina mantém esses dados ali. Enviar o mesmo prompt a um modelo hospedado envia os dados pessoais da plataforma a outra empresa, o que exige a mesma decisão que qualquer outra transferência desses dados.
Comparada ao arquivo revisado, a classificação de cada rascunho mostra se ele concorda:
1"""Compares the recorded model's classification of each source column with the reviewed one, and counts how many agree.2The prose's point rests on the agreement line and on the two lines counting personal and sensitive columns."""3from collections import Counter45from lib import metadata67reviewed = metadata.load() # governance/metadata.toml, reviewed by people8suggested = metadata.suggestions() # the recorded answers under the book's prompt: no model runs here9assert all(reviewed[s.table].columns[s.field_id].name == s.column for s in suggested) # each answer names the file's column at its field ID10print("columns the model was asked about:", len(suggested))11print("answers that parse as the JSON asked for:", sum(s.description is not None for s in suggested)) # None when the answer isn't that JSON12print("answers with one of the four classifications:", sum(s.classification in metadata.LEVELS for s in suggested))1314pairs = Counter((reviewed[s.table].columns[s.field_id].classification, s.classification) for s in suggested)15agree = sum(n for (was, said), n in pairs.items() if was == said)16print("classifications that agree with the review:", f"{agree} of {len(suggested)} ({agree / len(suggested):.0%})")17for level in metadata.LEVELS:18 said = sorted(((s, n) for (was, s), n in pairs.items() if was == level), key=lambda p: -p[1])19 print(f"reviewed {level}, the model said:", ", ".join(f"{s} {n}" for s, n in said))20for level in ("personal", "sensitive"):21 reviewed_as = sum(n for (was, _), n in pairs.items() if was == level)22 print(f"{level} columns the model called {level}:", f"{pairs[level, level]} of {reviewed_as}")
python suggestion-agreement.pycolumns the model was asked about: 64
answers that parse as the JSON asked for: 64
answers with one of the four classifications: 64
classifications that agree with the review: 40 of 64 (62%)
reviewed public, the model said: internal 3, public 3
reviewed internal, the model said: internal 37, public 5, sensitive 2
reviewed personal, the model said: internal 9, public 3
reviewed sensitive, the model said: internal 2
personal columns the model called personal: 0 of 12
sensitive columns the model called sensitive: 0 of 2
Todas as 64 respostas são JSON válido com uma das quatro classificações, o que mostra que o formato funcionou e não diz nada sobre se as respostas estão certas. Elas concordam com a revisão em 40 of 64 (62%) colunas, e esse único número esconde onde estão os erros. A maior parte da concordância são colunas internal classificadas como internal. Das colunas pessoais da plataforma, o modelo classificou 0 of 12 como personal, e, das suas colunas sensitive, o número do cartão e a conta de repasse, 0 of 2: ele classificou as duas como internal.
Exemplos em um prompt podem entregar a resposta
Os exemplos de um prompt fazem parte da medição. O script também registra o mesmo modelo, sobre as mesmas colunas, sob um segundo prompt, idêntico ao primeiro exceto pelos exemplos. Esse prompt dá exemplos apenas para personal e sensitive, e eles são as próprias colunas da plataforma. Para personal, os exemplos são "um nome, dados de contato, um endereço ou um texto que a pessoa escreveu", e para sensitive, um número de cartão ou uma conta bancária. Essas duas são billing.payments.card_number e crm.instructors.payout_iban, as únicas colunas sensíveis. Lado a lado, as respostas mostram o que os exemplos mudam:
1"""Scores the recorded answers under two prompts against the reviewed classifications: the book's prompt, whose examples2come from outside the platform, and one whose examples are the platform's own columns. The prose's point rests on3the sensitive-column lines and the agreement counts."""4from lib import metadata56reviewed = metadata.load()7prompts = {"the book's prompt": metadata.SUGGESTIONS,8 "the prompt with the platform's columns as examples": metadata.SUGGESTIONS_WITH_PLATFORM_EXAMPLES}9for name, path in prompts.items():10 # Each recorded answer, paired with the classification the file reviewed for its column.11 suggested = [(s, reviewed[s.table].columns[s.field_id].classification) for s in metadata.suggestions(path)]12 agree = sum(s.classification == was for s, was in suggested)13 print(f"{name}, classifications that agree with the review:", f"{agree} of {len(suggested)}")14 for level in ("personal", "sensitive"):15 reviewed_as = [s for s, was in suggested if was == level]16 print(f"{name}, {level} columns called {level}:",17 f"{sum(s.classification == level for s in reviewed_as)} of {len(reviewed_as)}")18 for s, was in suggested:19 if was == "sensitive":20 print(f"{name}, {s.table}.{s.column}:", s.classification)
python suggestions-with-platform-examples.pythe book's prompt, classifications that agree with the review: 40 of 64
the book's prompt, personal columns called personal: 0 of 12
the book's prompt, sensitive columns called sensitive: 0 of 2
the book's prompt, crm.instructors.payout_iban: internal
the book's prompt, billing.payments.card_number: internal
the prompt with the platform's columns as examples, classifications that agree with the review: 41 of 64
the prompt with the platform's columns as examples, personal columns called personal: 0 of 12
the prompt with the platform's columns as examples, sensitive columns called sensitive: 2 of 2
the prompt with the platform's columns as examples, crm.instructors.payout_iban: sensitive
the prompt with the platform's columns as examples, billing.payments.card_number: sensitive
Um prompt que cita as próprias colunas da plataforma acerta as colunas sensíveis, e o prompt do livro não acerta. Com as colunas da plataforma como exemplos, o modelo acerta 2 of 2 colunas sensíveis. O prompt do livro acerta 0 of 2, e classifica as duas como internal.
A concordância geral quase não muda, 41 of 64 contra 40 of 64, por isso um único número nunca mostraria a diferença. As colunas pessoais não ganharam nada com seus exemplos: 0 of 12 saiu como personal também sob esse prompt.
"Um número de cartão" nomeia card_number quase palavra por palavra, enquanto "um nome" deixa o modelo decidir que full_name é um, e ele não decidiu. Um prompt cujos exemplos coincidem com o catálogo faz um modelo parecer melhor do que é, justamente nas colunas que mais precisam de proteção; por isso, o prompt do livro tira seus exemplos de fora dos dados da plataforma.
Regra prática: Elabore rascunhos de metadados com um modelo apenas a partir de entradas que você tem permissão para enviar a ele, de preferência a um modelo nas suas próprias máquinas. Registre cada resposta com o modelo, sua revisão, o prompt e as configurações, para que um revisor possa ver o que produziu cada rascunho, e faça a análise e a validação de cada resposta antes que qualquer coisa a leia. Tire os exemplos do prompt de fora das tabelas nas quais você o mede. Informe a concordância com os metadados revisados por classificação, nunca como um único número.
Meça onde os rascunhos do modelo estão errados
Os rascunhos registrados, as descrições e classificações de um modelo local para as tabelas de origem da plataforma, concordam com as classificações revisadas na maioria das colunas. Para a governança, importa mais o sentido dos erros. Uma classificação mais protegida do que deveria ser custa um minuto a um revisor e uma coluna mascarada a um analista. Uma menos protegida do que deveria ser deixa dados pessoais onde as políticas os tratam como dados de equipe, ou como dados que qualquer pessoa pode ver. Separar os erros por direção mostra em que sentido o modelo falha:
1"""Counts the recorded classifications that protect a column less than the review does, and those that protect it more,2then lists each kind of miss. The prose's point rests on the two counts and on the `personal columns the model called3internal` line."""4from lib import metadata56reviewed = metadata.load()7rank = metadata.LEVELS.index # a column's position in LEVELS: a larger rank is more protected8weaker, stronger = [], []9for s in metadata.suggestions():10 if s.classification not in metadata.LEVELS: # an answer nobody can act on goes to a person11 continue12 column = reviewed[s.table].columns[s.field_id]13 if rank(s.classification) < rank(column.classification):14 weaker.append((s, column.classification))15 elif rank(s.classification) > rank(column.classification):16 stronger.append((s, column.classification))17print("columns the model protects less than the review:", len(weaker))18print("columns the model protects more than the review:", len(stronger))1920# Each kind of miss, the most protected review first.21for misses in (weaker, stronger):22 for was, said in sorted({(was, s.classification) for s, was in misses}, key=lambda p: (-rank(p[0]), -rank(p[1]))):23 names = [f"{s.table}.{s.column}" for s, w in misses if (w, s.classification) == (was, said)]24 print(f"{was} columns the model called {said}:", len(names))25 print(f"which, {was} called {said}:", ", ".join(names))
python suggestion-mistakes.pycolumns the model protects less than the review: 19
columns the model protects more than the review: 5
sensitive columns the model called internal: 2
which, sensitive called internal: crm.instructors.payout_iban, billing.payments.card_number
personal columns the model called internal: 9
which, personal called internal: crm.learners.full_name, crm.learners.email, crm.learners.phone, crm.learners.date_of_birth, crm.learners.notes, crm.instructors.full_name, crm.instructors.email, learning.events.ip_address, support.tickets.body
personal columns the model called public: 3
which, personal called public: crm.learners.city, crm.learners.street_address, learning.reviews.body
internal columns the model called public: 5
which, internal called public: learning.events.event_type, learning.events.occurred_at, learning.events.user_agent, learning.reviews.posted_at, support.tickets.opened_at
internal columns the model called sensitive: 2
which, internal called sensitive: crm.learners.marketing_consent, crm.learners.ai_training_consent
public columns the model called internal: 3
which, public called internal: learning.courses.course_id, learning.courses.title, learning.courses.price_usd
Os erros do modelo recaem sobre as colunas que mais precisam de proteção. Ele protegeu 19 colunas menos do que a revisão, e 5 mais. Toda coluna pessoal e sensível está entre as menos protegidas. Ele classificou 9 colunas pessoais como internal, entre elas os nomes e e-mails tanto em crm.learners quanto em crm.instructors, os telefones, datas de nascimento e anotações dos alunos, os endereços IP dos eventos e o texto dos tickets de suporte. Ele classificou 3 delas como public: cidades e endereços dos alunos, e o texto de suas avaliações. O significado que o prompt dá a personal começa com "identifica uma pessoa ou revela algo sobre ela", e um nome ou um e-mail faz as duas coisas.
As outras colunas menos protegidas são timestamps, o tipo de um evento e o seu user agent, que o modelo classificou como public onde a revisão escolheu internal: um erro menor, mas que um revisor ainda precisa pegar. Os erros no sentido contrário custam menos. O modelo classificou as 2 flags de consentimento como sensitive, e classificou como internal o ID público, o título e o preço do catálogo de cursos.
As descrições falham de outro modo, e quatro das do modelo mostram isso lado a lado com as revisadas:
1"""Prints the recorded description beside the reviewed one for four columns, where the review knows what a name, a type2and five values can't say. The prose's point rests on the pairs themselves, read one after another."""3from lib import metadata45reviewed = metadata.load()6suggested = {(s.table, s.column): s for s in metadata.suggestions()} # keyed by name, so the four columns below can be named78# Four columns where the platform knows more than a name, a type and five values say.9for table, column in [("crm.learners", "ai_training_consent"), ("crm.learners", "support_region"),10 ("crm.learners", "notes"), ("billing.payments", "card_number")]:11 print(f"{table}.{column}, the model:", suggested[table, column].description)12 print(f"{table}.{column}, the review:", reviewed[table].column(column).description) # looked up by name: the file keys columns by field ID, but `column()` finds one by name
python suggestion-descriptions.pycrm.learners.ai_training_consent, the model: This column indicates whether a learner has consented to receive AI training.
crm.learners.ai_training_consent, the review: Whether the learner agreed to their text training the platform's AI. Unknown for sign-ups before the question was asked.
crm.learners.support_region, the model: The 'support_region' column indicates the regional support area for learners in the online learning platform.
crm.learners.support_region, the review: The support team that serves the learner: americas, emea or apac.
crm.learners.notes, the model: Stores notes from learners about their move, billing address, or preferences.
crm.learners.notes, the review: Free text from support agents. May hold anything, so it is treated as personal.
billing.payments.card_number, the model: Stores the card numbers of customers for payment processing.
billing.payments.card_number, the review: The full card number, from a legacy export. Should not be stored at all.
Toda descrição é fluente e plausível, e três das quatro deixam de dizer algo que só quem sabe como a plataforma preenche a coluna poderia escrever. ai_training_consent registra se o texto do aluno pode treinar a IA da plataforma, não se o aluno quer o treinamento, e um null significa que a pergunta nunca foi feita. notes são escritas por agentes de suporte sobre os alunos, como os valores sugerem, com uma nota sobre faturas para o empregador do aluno, e não pelos próprios alunos. E card_number é uma coluna legada que não deveria existir, o que é a coisa mais útil que sua descrição pode dizer. A quarta está correta no conteúdo: a plataforma atribui a cada aluno a support_region da equipe de suporte que atende o país dele, e o modelo a chama de "área regional de suporte". Nada numa descrição fluente diz se ela está certa ou se deixa algo de fora, por isso um revisor lê todas. Os autores de um método para gerar descrições de colunas nomeiam a mesma falha em modelos de prompt único, que escrevem descrições alucinadas ou incompletas (Cai et al., 2026).
Estas são as respostas de um modelo pequeno, decodificadas de modo guloso (greedy), para dois prompts. A gravação não permite saber se o modelo erra nas colunas pessoais por causa do seu tamanho, ou porque rascunha com apenas um nome, um tipo e cinco valores como base. Um modelo maior ou um prompt melhor podem acertar mais colunas, e a forma de descobrir é medir do mesmo modo, contra o arquivo revisado, antes de confiar nele para tabelas que ninguém revisou.
Regra prática: Deixe um modelo elevar a classificação de uma coluna, nunca reduzi-la: só um revisor a reduz, no pull request, com o motivo na descrição da coluna. Trate as descrições do modelo como primeiros rascunhos para alguém que conhece a coluna reescrever. Antes de um modelo rascunhar metadados para tabelas que ninguém revisou, meça-o contra os seus metadados revisados, por classificação e por direção de erro, e meça de novo sempre que o modelo ou o prompt mudar.
O que dá errado em produção
Nada gera erro quando os metadados ficam desatualizados, e cada uma das falhas abaixo parece completa até que alguém dependa dela.
- Os responsáveis ficam desatualizados. Equipes são renomeadas, fundidas e dissolvidas, e o responsável no arquivo sobrevive a elas. Uma equipe, diferentemente de uma pessoa, sobrevive à saída de um integrante, mas o arquivo ainda precisa de uma verificação de que cada responsável é uma equipe que existe, executada contra a lista de equipes da sua organização. Se você mantém a propriedade no ODCS, as pessoas da equipe têm um
dateOute umreplacedByUsername(ODCS v3.2.0), que uma verificação pode ler para encontrar uma equipe sem nenhuma pessoa atual no papelowner. - As descrições descrevem o esquema do ano passado. O significado de uma coluna muda enquanto o nome e o tipo permanecem os mesmos:
amountpassa a conter reembolsos como números negativos, oustatusganha um novo valor. Nenhuma verificação de esquema percebe isso. Comentários no código falham da mesma forma. Uma pesquisa sobre eles constatou que um detector identifica inconsistências com mais precisão quando vê uma mudança antes de ela ser confirmada do que quando vê apenas o código resultante (Panthaplackel et al., 2021). Para colunas, a comparação só vale onde um pull request mostra a mudança. A lógica de um pipeline muda em um diff, mas um sistema de origem pode mudar o que escreve sem diff algum. Onde há um diff, faça com que o pull request que altera a lógica de um pipeline mostre as descrições das colunas que ele escreve, para que o revisor leia as duas coisas. - Metadados indexados por nome ficam desatualizados em uma renomeação. Uma planilha de colunas, o dicionário de dados de um dashboard ou uma política escrita com base em nomes de colunas perde uma coluna a cada renomeação, como mostra a seção sobre o ID de campo, e não informa nada. Gere todas as visões indexadas por nome a partir do arquivo indexado por ID, e execute
problemsa cada mudança de esquema. - Duas fontes de metadados se sobrescrevem. A página web de um servidor de catálogo e um arquivo em um repositório aceitam edições, e uma sincronização em qualquer direção apaga a edição da outra. O DataHub mantém as edições feitas na sua interface separadas dos metadados ingeridos, para que os pipelines de ingestão não sobrescrevam o que os usuários informaram (entidade de dataset do DataHub). Escolha uma fonte e torne a outra somente leitura ou gerada.
- Edições de descrição disparam revisões que ninguém precisa. No PyIceberg, cada edição de documentação dá ao esquema um novo ID, como mostra a edição de documentação acima, então uma revisão baseada em IDs de esquema é acionada à toa. Compare IDs de campo, nomes e tipos.
- Classificações propostas são aprovadas em lote. Um pull request que adiciona quarenta colunas propostas por modelo tem suas descrições lidas e suas classificações apenas examinadas por alto, e os rascunhos registrados mostram aonde isso leva. Liste cada classificação proposta separadamente das descrições, da menos protegida para a mais protegida, para que o revisor veja o que cada rascunho deixaria desprotegido.
- Uma tabela criada fora dos pipelines escapa do teste. Um notebook ou um backfill pontual cria uma tabela que ninguém vai incluir no arquivo. Execute
problemsem uma agenda contra o catálogo de produção, e não apenas nos pull requests.
O que este capítulo decidiu
- Metadados são um arquivo revisado: proprietários, domínios, descrições e classificações ficam em
governance/metadata.toml, alterados somente por pull request. - Quatro classificações, ordenadas:
public,internal,personalesensitive, prevalecendo a mais restritiva quando uma coluna é construída a partir de várias. Uma coluna sem classificação é tratada comosensitive. - Uma equipe proprietária por tabela, nunca uma pessoa, e um domínio ao lado dela.
- As colunas são identificadas pelo ID de campo do Iceberg, com o nome mantido ao lado, para que uma renomeação apareça para revisão.
- As descrições vão para o
docdo Iceberg, escritas porlib.metadata.apply. O proprietário e o domínio vão para as propriedades da tabela como um ponteiro, e as classificações permanecem no arquivo. - O catálogo é testado contra o arquivo:
problemspercorre todas as tabelas do catálogo, edroppedencontra entradas de colunas que não existem mais. Mudanças de esquema são comparadas por IDs de campo, nomes e tipos, não por IDs de esquema. learner_idéinternalem todas as tabelas, com uma descrição que indica que ele é resolvido por meio decrm.learners. A proteção recai sobre essa tabela, e a política de acesso decide quem pode juntar as duas com os nomes visíveis.applyeproblemsrodam em cada alteração:applygrava o arquivo no catálogo a cada merge, eproblemsroda em cada pull request e periodicamente contra o catálogo de produção.- O modelo que redige metadados roda nas máquinas da própria plataforma, porque os valores de amostra que ele recebe são dados pessoais sempre que a coluna for pessoal.
- Metadados redigidos por modelo são uma proposta. Os rascunhos são registrados com o modelo que os gerou, medidos contra o arquivo revisado e reescritos por uma pessoa. Um modelo pode elevar uma classificação, nunca reduzi-la. Um prompt que cita as colunas do próprio catálogo favorece o modelo de forma enganosa, por isso os exemplos em um prompt vêm de fora dos dados da plataforma. Uma descrição desatualizada torna-se uma verificação com falha.
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.