テスト可能なカタログ
読了まで約68 分分、12 節 節の 11 例 例。
このページの内容
本章を終えると、カタログのメタデータをコードとして管理できるようになる。すべてのテーブルに所有者とドメインを、すべての列に説明と分類を付け、チームがレビューするファイルに記述する。このファイルは、名前変更によって何も失われないようにキー付けされ、Iceberg カタログに書き込まれ、欠けているものがあれば失敗するテストによって検査される。さらに、ローカルモデルに説明と分類の下書きを作らせ、その下書きを誰かが受け入れる前に、どのくらいの頻度で誤っているかを測定する。
このプラットフォームのカタログには三つの問題がある。このプラットフォームのウェアハウスは、オンライン学習プラットフォームが管理する Iceberg カタログであり、そのパイプラインはテーブルを追加し続けている。ウェアハウスは、それらを運用するチームの名前を付けた名前空間に、8 個のソーステーブルを保持している。たとえば crm.learners や support.tickets がそれである。パイプラインはそれらからレポート用テーブルを作成し、その後もテーブルを作り続ける。マーケティングがメールを送ってよい学習者の一覧である marketing.audience を誰が所有しているのかも、プラットフォームのコースアシスタントが読むテキストである ai.review_corpus が個人データを含むかどうかも、どこにも記されていない。スキーマ変更で名前を変えた列は、誰にも気づかれないまま分類を失うことがある。そして、パイプラインが追加するテーブルごとに、すべての列の説明と分類を手作業で書く必要があり、これは時間がかかるため、チームは省略してしまう。
第 1 章では、ガバナンスの効いたプラットフォーム全体の大まかな版を作った。本章ではそのカタログを堅牢にする。
本章の例では、本書の共有モジュールのうち五つを使う。lib.catalog.open_catalog は、プラットフォームのテーブルからなる新しいカタログを一時フォルダに作成する。これは SQLite 上の PyIceberg の SQL カタログを用いたもので、PyIceberg のドキュメントは探索と開発にのみ推奨している(PyIceberg の設定)。lib.pipelines.run はプラットフォームのパイプラインの一つを実行し、その出力をカタログに書き込む。lib.warehouse.connect はカタログのテーブルに対して DuckDB を開く。これにより、クエリはプラットフォームと同じ名前でテーブルを指定できる。lib.policy はプラットフォームのアクセスポリシーを評価する。このポリシーは第 5 章で書く。そして lib.metadata は本章で作り上げるモジュールであり、プラットフォームのメタデータを読み込み、カタログに書き込み、カタログをそのメタデータに照らして検査する。
この部分はまだ翻訳されていないため、英語で表示している。
Keep the metadata in a reviewed file
A catalog's metadata is what you know about each table that the data doesn't say: who owns it, which part of the business it belongs to, what it holds, and how each column must be protected. Catalog servers keep this in their own database and edit it in a web page. That works for browsing, but a change made there is invisible to code review, and no test can say whether the catalog is complete. Keeping the metadata in a file in the repository, beside the pipelines that create the tables, makes every change a diff that someone approves, and gives a test something to compare the catalog with.
The platform's file is governance/metadata.toml. For each table it records:
- an owner, the team answerable for the table, never a person;
- a domain, the part of the business the table belongs to;
- a description of the table;
- for each column, its name, a description and a classification.
A classification is one of four values, ordered from least to most protected:
| Classification | Meaning | On the platform |
|---|---|---|
public |
May be shown to anyone outside the platform | A course's title |
internal |
For the platform's staff, and doesn't identify a person by itself | When an enrollment started |
personal |
Identifies a person or tells something about one | A learner's email, or text they wrote |
sensitive |
Data whose leak would directly harm someone | A card number, an instructor's bank account |
The order matters: when a column is built from several others, as a pipeline's output columns often are, the stricter classification wins, and lib.metadata.stricter returns it. Loaded and counted, the file shows what it covers:
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.
Most columns are internal, because most of a warehouse is IDs, dates and counts: 57 of its 77 columns are. The protected columns are few. Of the file's columns, 12 are personal, and sensitive holds the card number in billing.payments and the payout account in crm.instructors. The file covers the eight source tables and the two reporting tables the platform's analysts rely on, and every table belongs to one of 5 owning teams. The point is that each description carries the reason for its classification. country is internal because a country alone doesn't single anyone out, while city is personal because, as its description says, it identifies a learner together with their date of birth.
The four values and the one-owner rule are ours, not a standard's. The Open Data Contract Standard (ODCS) records a domain, an owner as a free-text role on a team, and a free-text classification (ODCS v3.2.0), and its JSON schema accepts any string as a classification (ODCS JSON schema). The catalog servers differ too. DataHub types its owners (ownership types), and it lets an asset belong to only one domain at a time (domains). It classifies columns with glossary terms (business glossary).
OpenMetadata lets an owner be either a team or several users, a rule enforced at the instance level and on by default (data ownership). Its classifications are a controlled vocabulary of tags (classification), such as PII.Sensitive (PII tags). In Databricks' Unity Catalog every object has an owner, who holds every privilege on it (privileges). Tables and columns carry tags (tags), and a governed tag takes values "only from a predefined set of allowed values" (governed tags). A file like the platform's maps onto each of them. None of these documents describes the check this chapter's test makes: a team, never a person, as the owner of every table, and one of the four classifications on every column.
Working rule: Keep owners, domains, descriptions and classifications in a file in the repository, reviewed like the pipelines. Use a closed list of classifications, ordered by how much protection each needs, and one owning team per table. If your organization edits metadata in a catalog server's web page, make one side the source and generate the other from it; two sources that both accept edits drift apart.
列メタデータはフィールド ID をキーにする
プラットフォームのメタデータファイルは、各列を名前ではなく数値をキーにして管理している。名前は変わりうるからである。Iceberg はすべての列にフィールド IDを与える。これはテーブルのスキーマ内で一意な整数であり、仕様はリネームがこれを保持することを求めている。「既存のフィールドのリネームでは、名前は変更するが、フィールド ID は変更してはならない」(Iceberg テーブル仕様)。読み取り側も、この ID で値を見つける。Iceberg はデータファイルの列をフィールド ID で選択するため、リネームされた列は、リネーム前に書かれたファイルも読み取れる(Iceberg テーブル仕様)。名前をキーにしたメタデータには、頼りにできるものがない。リネームの後は、古い名前は何も指さず、新しい名前にはエントリがない。
プラットフォームの CRM チームは、業務用メールアドレスの場所を空けるために、crm.learners.email を contact_email に変更しようとしている。スクラッチカタログで実施したリネームを見ると、名前をキーにしたコピーが何を失うかが分かる。列は、フィールド ID をキーにしたメタデータファイルと、列の一覧表がたいていそうであるように名前をキーにしたコピーの両方で検索される。
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
二つの検索結果は食い違い、列が同一のものであると分かるのはフィールド ID をキーにした方だけである。リネームではフィールド ID 3 が保持され、5,000 of 5,000 の値が新しい名前で読み取れた。名前をキーにすると、contact_email には分類がなく、email のエントリはどの列にも一致しない。フィールド ID をキーにすると、この列は依然として personal である。名前をキーにしたコピーに基づくチェックは、分類のない列があると報告する一方で、分類済みの列が消えたことを見逃してしまう。
ID をキーにしたファイルはリネームに気づくことができ、本章が前提とするチェックである lib.metadata.problems がそれを報告する。報告の内容は contact_email: renamed from email since it was reviewed である。データがリネームを越えて残っても、リネームが無害になるわけではない。email という名前を指定する SQL は壊れ、列を名前でしか知らないシステムも同様に壊れる。第5章で書くプラットフォームのアクセスポリシーは、クエリが読み取る列を名前で受け取る。そのため、ポリシーは lib.policy がこのファイルから生成する、名前をキーにしたビューから分類を読み取る。チェックが失敗すると、誰かがファイル内の名前を更新して説明を読み直し、生成されるビューがそれに追随する。それまでの間、ビューには contact_email のエントリがなく、ポリシーは見つからない列を sensitive として扱う。crm.learners の他の personal 列をすべて閲覧できるサポート担当者は、contact_email を redact として受け取る。リネームは安全側に倒れて失敗し、最初に気づくのはサポートである。
実践ルール: 列メタデータはフィールド ID をキーにし、人間のために名前を横に添える。名前が一致しなくなった場合は、新しい列とみなすのではなく、その列の説明を見直す契機として扱う。列を名前でしか知らないシステムには、名前をキーにしたビューを手作業で保守するのではなく、ID をキーにしたファイルから生成する。
テーブルのスキーマに説明を書き込む
メタデータファイルは、プラットフォームのメタデータをレビューする場所である。しかし、テーブルを読む人やツールはカタログを参照するため、メタデータの一部はカタログにコピーしておく必要がある。問題は、それぞれの事実をカタログのどこに置くかである。Iceberg はその一部に答えを用意している。各列は doc を持つことができ、これはスキーマとともに受け渡される任意のコメントである(Iceberg table spec)。テーブルにはプロパティ、すなわち文字列のマップもあるが、仕様はこのマップについて「読み取りと書き込みに影響する設定を制御するために使われるものであり、任意のメタデータに使うことは意図されていない」と述べている。
そこで、できる限り仕様に従う。列の説明は doc に入れ、分類は、ポリシーやチェックが読むファイルに残しておく。所有者とドメインは、テーブルだけを読むツールへの手がかりとして二つのテーブルプロパティに入れる。これにより、テーブルだけがありリポジトリがない場合でも、問い合わせるべきチームを見つけられる。この最後の選択は仕様が示す意図に反するため、この二つの短い値だけに限定する。
Iceberg プロジェクト自身の答えは、別のチャネルである。Iceberg 1.12.0 の REST カタログ仕様は labels を追加している。これは、カタログがテーブルとともに返す所有者や分類の情報であり、テーブルごと、フィールド ID ごとに持たれ、意図的にプロパティとは分けられている(REST catalog spec)。この変更はプルリクエスト 15750で取り込まれた。PyIceberg 0.12.0 の REST クライアントは、これらを読み取らない(ソース)。
コピーを行うのは lib.metadata.apply である。ファイルが記述していて、かつカタログに存在するすべてのテーブルについて、各説明を対応する列の doc に、所有者とドメインをプロパティに書き込み、差異のある箇所だけを変更する。プラットフォームの 8 個のソーステーブルからなる新しいカタログに対して、apply が何を変更するかを示す。
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
ファイルを適用するとメタデータがカタログに書き込まれ、再度適用しても何も書き込まれないため、apply はマージのたびに実行できる。最初の実行で変更されたテーブルは 8 個であった。email の説明は、Iceberg スキーマと、スキャンが返す Arrow スキーマの両方に入っている。したがって、PyIceberg 経由でテーブルを読むコードは、ファイルの存在を知らなくても、データとともにこの説明を得られる。プロパティには owner=team-crm と domain=crm が入っている。2 回目の実行で変更されたテーブルは 0 個であった。crm.learners のスキーマ ID は、列の ID、名前、型のいずれも変わっていないにもかかわらず、0 から 1 に変わった。これについては次の小節で扱う。
この部分はまだ翻訳されていないため、英語で表示している。
A description edit is a schema change
Iceberg's spec gives every schema change a new schema with its own ID, which becomes the table's current schema and joins the list of schemas the table keeps (Iceberg table spec). In PyIceberg 0.12.0, editing nothing but a column's doc counts as such a change. Change nothing but the description of learning.reviews.body, after lib.metadata.apply has written the platform's descriptions, and watch the schema ID:
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
A description edit changes the schema ID and nothing a review should compare. The ID went from 1 to 2, and the table keeps 3 schemas: the original, the one apply wrote, and this one. The field IDs, names and types are the same, which lib.metadata.shape compares. A rule that asks for a new classification whenever the schema ID changes would fire on every description edit, and teams learn to ignore a check that fires for nothing.
Working rule: Write column descriptions into Iceberg's doc, so every reader of the table gets them, and keep classifications in the reviewed file. Put no more than an owner and a domain in table properties, and say in your code why. To decide whether a schema change needs a review, compare field IDs, names and types, never schema IDs.
この部分はまだ翻訳されていないため、英語で表示している。
Test the catalog against the metadata
With the metadata applied to the catalog, the remaining question is whether the file covers everything the catalog holds. A test answers it, and it has to start from the catalog: a check that walks the file finds problems only in tables someone already described. lib.metadata.problems lists every table in every namespace of the catalog, and reports a table with no entry or no owner, a column whose field ID has no classification, a classification that isn't one of the four, and a column renamed since it was reviewed.
On the platform, the gaps come from pipelines. Each pipeline is one create table ... as select ... in pipelines/, and running it creates a table. Run all four pipelines on a fresh catalog and check it, and the gaps show:
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
The two tables that fail are the ones that matter most. The catalog holds 12 tables, and the check finds 2 problems: ai.review_corpus: no metadata and marketing.audience: no metadata. The two analytics tables pass, because the file describes them, with field IDs that match the order of their select lists.
marketing.audience copies learners' names and emails out of crm.learners, and ai.review_corpus copies the free text of reviews, so both hold personal data, and neither has an owner who would answer for it. Until someone classifies them, the platform's access policy, governance/policies/access.rego, treats every column it can't find a classification for as sensitive, so the gap fails closed rather than open. Chapter 4 proposes their classifications from lineage, from the columns each output column was built from.
The test is then one line, assert not metadata.problems(catalog, metadata.load()), run wherever the catalog changes: in the pull request that adds a pipeline, which chapter 10 sets up, and on a schedule against the production catalog, which catches tables created outside any pull request.
Working rule: Walk the catalog, not the metadata file, so a table nobody described shows up. Fail the test on any table without an owner and any column without one of the four classifications, and never default a missing classification to anything but the most protected value. A pipeline that creates a table ships with that table's metadata, in the same pull request.
この部分はまだ翻訳されていないため、英語で表示している。
Catch schema changes before the metadata goes stale
The test against the catalog catches new tables. Tables also change underneath their metadata, and each kind of change needs its own response. A rename keeps the field ID, so the entry survives, but its description may now be wrong. An added column gets a field ID nobody has reviewed. A dropped column leaves an entry that describes nothing. And dropping a column and adding one with the same name doesn't bring the old column back: the spec gives every added field a new ID (Iceberg table spec), so the re-added column is a different column.
Schema changes are frequent enough for this to matter. In a study of ten open-source applications, "80% of the schema changes happened in 20-30% of the tables" (Qiu, Li and Su, 2013). That study covers application databases, not warehouses. If a warehouse's changes concentrate the same way, its busiest tables are the ones whose metadata goes stale first.
Two changes staged on crm.learners show both checks working: one adds preferred_name, with a description but no classification, and the other drops country and adds it back. problems and lib.metadata.dropped: the second reports entries whose field ID the table no longer has, and reads the dropped column's values the way Iceberg's time travel does, by naming a 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
A re-added column is a new column: country came back as field 17, not 5, and a plain scan, which reads through the current schema where the old field no longer exists, returns 5,000 nulls of 5,000 for it. Both added columns are unclassified, and the description given to preferred_name doesn't count: a description is a doc in the schema, and a classification is a reviewed line in the file.
The learners' countries haven't gone anywhere. A schema change writes no snapshot (0 here), so the table's current snapshot is still the one its rows were written in. A snapshot records the ID of the table's current schema when it was created (Iceberg table spec), and in PyIceberg 0.12.0, a scan that names a snapshot reads with that schema. So time travel to that snapshot returns 5,000 of 5,000 countries. Dropping a column deletes none of its values: chapter 7 is where the platform erases data for good. dropped reports that the reviewed entry for the old field now describes nothing. The rename from the field ID section is the third kind of change, which problems reports as a column to review.
Working rule: Run both checks on every schema change: problems for columns nobody has classified or renamed ones nobody has re-read, and dropped for entries that describe nothing. Remove a dropped column's entry in the same pull request that drops it. Dropping a personal column doesn't remove its values, which time travel reads until the snapshots that hold them expire and their files are deleted. Never drop and re-add a column to rename it: rename it in place, so it keeps its field ID and its data.
結合用の仮名化IDを分類する
メタデータファイルでは、人を指す列の一部をinternalに分類している。その中で最も多いのがlearner_idである。これは単独では意味を持たない数値であり、プラットフォームのアナリストやデータサイエンティストは、受講登録、イベント、支払い、チケットを相互に結合するためにこれを必要とする。learner_idのように単独では意味を持たないIDは仮名化識別子(pseudonymous identifier)である。それ自体は誰の名前も示さないが、別のテーブルを経由して特定の人にたどり着く。1つのIDは、その分類が示唆する以上に遠くまで到達する。コードは、このIDを持つテーブルを数え、受講登録を学習者に結合し、その結合を行って氏名を見ることができるのは誰かをアクセスポリシーに問い合わせる。
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)
1回の結合で人に到達する。20,000 of 20,000件の受講登録がメールアドレスにつながり、メールアドレスからは、学習者の氏名、電話番号、住所、生年月日が得られる。これらは、そのテーブルのpersonal列に含まれるものである。にもかかわらず、learner_idは、それを持つ7のすべてのテーブルでinternalである。
EUの一般データ保護規則(GDPR)は、前文第26項でこうしたデータを扱っている。「追加的な情報の使用によって自然人に帰属させることができる、仮名化を経た個人データは、識別可能な自然人に関する情報とみなされるべきである」(GDPR, Recital 26)。この前文が個々のプラットフォームにとって何を意味するかは法務担当者が判断すべき問題であり、本書では答えない。
本書が決めるのは、コードがこのIDをどう扱うかである。internalは、その列を保持するテーブルの中でその列が何を明らかにするかを記述する。残りは、メタデータファイル内の各learner_idの説明が述べており、crm.learnersを解決先のテーブルとして挙げている。learning.enrollmentsの説明も同様である。「受講登録した学習者。crm.learners と結合すると個人を識別する。」保護は、IDを解決するテーブルに置く。第5章では、crm.learnersの個人列を誰が読めるかを決める。この例の最後の数行は、そこで学習者の氏名を見られるのは誰かをポリシーに問い合わせている。結果はagent-a01, agent-a05, agent-a09, marketing-1である。そのうち、別のテーブルのlearner_idも読むのはサポート担当者だけである。その数はagent-a01 (support.tickets), agent-a05 (support.tickets), agent-a09 (support.tickets)である。彼らは自分の担当地域のすべてのチケットに氏名を対応づけることができ、それが彼らの職務である。マーケティングは氏名を見られるが、このIDを持つ他のテーブルは読まない。
つまり、結合を行えるのは誰かを決めるのは、IDの分類ではなくポリシーである。support.tickets.learner_idをpersonalに分類しても、このテーブルを読む唯一のグループであるサポートにとっては何も変わらない。ポリシーがすでにサポートにすべての個人列を見せているからである。第7章で扱う消去は、分類にかかわらず、学習者のlearner_idを保持するすべてのテーブルに及ばなければならない。このようなIDは仮名化されたものと呼び、匿名化されたものとは決して呼ばない。
実践ルール: 仮名化IDは、それ自身のテーブルが明らかにする内容によって分類し、アナリストが必要とする結合が動き続けるようにする。そして、何を介して解決されるのかを説明に書く。IDを解決するテーブルを保護し、すべての消去にそのIDを含める。IDを解決できるのは誰かはアクセスの判断である。IDと、解決先テーブルの個人列の両方をマスクなしで読んでよいユーザーを一覧にし、その組み合わせは、職務が行と人との対応づけである者にのみ付与する。
ローカルモデルによるメタデータの下書き
カタログに対するテストは、誰も説明を付けていない列を教えてくれるが、説明を書いてくれるわけではない。すべての列に説明を書き、分類を選ぶ作業は、カタログを保守するうえで最も時間のかかる部分であり、パイプラインがテーブルを追加するたびに発生する。言語モデルは、カタログツールが示せる情報、すなわち列の名前、型、いくつかの値から、説明と分類の両方を下書きできる。研究は、この支援とその限界の両方を裏付けている。あるベンチマークでは、指示と2段階のパイプラインを与えると、ChatGPT はテーブルの列の意味型に、「ゼロショットおよびワンショットの設定で85%を超える F1 スコア」でラベルを付けた(Korini and Bizer, 2023)。生成された列の説明を調べた研究では、意味が曖昧な列はモデルにとって難しく、そうした列には専門家の手作業による入力が必要であることが分かった(Wretblad et al., 2024)。したがって、モデルの下書きは提案にすぎず、人がプルリクエストの中で受け入れ、修正し、あるいは却下する。最初の作業は、下書きがどの程度誤っているかを測ることであり、これによってレビューはどこを見るべきかを知ることができる。
本書の下書きは、例の中ではメタデータ候補と呼ぶが、recordings/metadata_suggestions.pyによって一度だけ記録された。例はその記録を読み込むため、どの例もモデルを呼び出さない。このスクリプトは、リビジョンを固定した Qwen3-1.7B を実行する。このモデルは Apache-2.0 ライセンスのオープンモデルであり、誰でも同じ重みをダウンロードできる。パラメータ数は17億で、GPU なしで CPU 上で動作するため、サンプル値はモデルを実行するマシンの外に出ない。また、指示チューニングされており、回答の前に書き出す推論である「思考」をオフにするスイッチを備えている。モデルカードは、このモードではサンプリングを推奨しており、その設定は「Temperature=0.7, TopP=0.8, TopK=20, and MinP=0」である(Qwen3-1.7B)。しかし、スクリプトは最も可能性の高い次のトークンを選ぶ貪欲デコードを用いる。記録は、誰かがもう一度記録しても同じ結果にならなければならないが、サンプリングによる回答は、多数ありうる試行の一つにすぎないからである。
プラットフォームの8つのソーステーブルの各列について、モデルには、テーブル名、列名と Iceberg の型、固定シードで選んだその列の値5個、そして分類の表にある意味を添えた4つの分類を示した。各意味には2つの例が付いているが、それらはプラットフォームに実在する列ではない。sensitiveの場合、その例は「政府発行の ID 番号や健康状態」である。モデルには、1文の説明と1つの分類を JSON で返すよう求めた。記録のマニフェストには、モデル、そのリビジョン、プロンプトと設定のハッシュ、日付が記載されているため、誰でももう一度記録して比較できる。
これら5個の値は、その列が個人データである場合には常に個人データである。support.tickets.bodyでは、モデルが読んだチケットに、学習者の氏名、住所、電話番号、生年月日、銀行口座番号が含まれていた。自分のマシンで動くモデルであれば、それらはそのマシンの中にとどまる。同じプロンプトをホスト型モデルに送ると、プラットフォームの個人データが別の会社に送られることになり、個人データの他の移転と同じ判断が必要になる。
レビュー済みのファイルと照らし合わせると、各下書きの分類が一致しているかどうかが分かる。
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
64件の回答はすべて、有効な JSON であり、4つの分類のいずれかになっていた。これは形式が機能したことを示すが、回答が正しいかどうかについては何も語らない。レビューとの一致は40 of 64 (62%)列であり、この1つの数値は、誤りがどこにあるかを隠している。一致の大部分は、internalの列をinternalと判定したものである。プラットフォームの個人列については、モデルは0 of 12をpersonalと判定した。また、sensitiveの列、すなわちカード番号と支払先口座については、0 of 2であった。モデルは両方をinternalと判定したのである。
プロンプトの例は答えを漏らすことがある
プロンプトに含まれる例は、測定の一部である。スクリプトは、同じモデルに同じ列を与え、例だけが異なる第2のプロンプトでも結果を記録する。このプロンプトが例を挙げるのは personal と sensitive だけであり、その例はプラットフォーム自身の列である。personal の例は「氏名、連絡先、住所、または本人が書いた文章」であり、sensitive の例はカード番号または銀行口座である。この2つに該当するのは billing.payments.card_number と crm.instructors.payout_iban であり、機微な列はこの2つしかない。両者の答えを並べると、例が何を変えるかがわかる。
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
プラットフォーム自身の列を挙げるプロンプトでは機微な列を正しく分類できるが、本書のプロンプトではできない。プラットフォームの列を例にした場合、モデルが正しく分類した機微な列は 2 of 2 である。本書のプロンプトでは 0 of 2 であり、2つの列をどちらも internal と分類している。
全体の一致率はほとんど動かず、41 of 64 に対して 40 of 64 である。したがって、1つの数値だけでは違いは見えない。個人の列は、例を与えても何も得なかった。0 of 12 は、そのプロンプトでも personal という結果になった。
「カード番号」という例は card_number をほぼそのまま指している。一方、「氏名」という例では、full_name がそれに当たるかどうかをモデルが判断することになり、モデルはそう判断しなかった。例がカタログと一致するプロンプトは、最も保護が必要な列について、モデルを実際よりよく見せてしまう。そのため、本書のプロンプトは例をプラットフォームのデータの外から取っている。
実践ルール: モデルでメタデータの草案を作るのは、送信を許可されている入力に限り、できれば自分たちのマシン上のモデルを使う。各回答は、モデル、そのリビジョン、プロンプト、設定とともに記録し、レビュー担当者が各草案の生成元を確認できるようにする。どの回答も、読み取る前に必ず解析して検証する。プロンプトの例は、測定対象のテーブルの外から取る。レビュー済みメタデータとの一致率は、1つの数値ではなく、分類ごとに報告する。
モデルの下書きが誤る箇所を測定する
記録された下書きは、ローカルモデルがプラットフォームのソーステーブルに対して作成した説明と分類であり、ほとんどの列でレビュー済みの分類と一致している。ガバナンスの観点では、どちらの方向に外れるかのほうが重要である。本来より保護の厚い分類は、レビュー担当者の1分とアナリストにとってのマスクされた列という代償で済む。本来より保護の薄い分類は、個人データをポリシー上スタッフ用データとして、あるいは誰でも閲覧できるデータとして扱わせてしまう。外れ方を方向別に分けると、モデルがどちらに失敗するかが分かる。
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
モデルの誤りは、最も保護が必要な列に集中している。レビューより保護が薄かった列は19列、厚かった列は5列である。個人列と機微列はすべて、保護が薄いほうに含まれる。モデルは9列の個人列をinternalと判定した。その中には、crm.learnersとcrm.instructorsの両方にある氏名とメールアドレス、学習者の電話番号、生年月日、メモ、イベントのIPアドレス、サポートチケットの本文が含まれる。また、3列をpublicと判定した。学習者の市区町村と住所(番地)、およびレビューの本文である。プロンプト自身によるpersonalの定義は「人を特定する、またはその人について何かを伝える」で始まり、氏名やメールアドレスはその両方に当てはまる。
保護が薄いその他の列は、タイムスタンプ、イベントの種別とユーザーエージェントである。モデルはこれらをpublicと判定したが、レビューではinternalが選ばれた。誤りとしては小さいが、レビュー担当者が見つけて直す必要があることに変わりはない。逆方向の誤りは代償が小さい。モデルは2列の同意フラグをsensitiveと判定し、コースカタログの公開ID、タイトル、価格をinternalと判定した。
説明は別の形で誤る。モデルの説明のうち4件を、レビュー済みの説明と並べて示す。
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.
どの説明も流暢でもっともらしく、4件のうち3件は、プラットフォームがその列をどう埋めるかを知っている人にしか書けない内容を欠いている。ai_training_consentは、学習者の文章をプラットフォームのAIの学習に使ってよいかどうかを記録するものであり、学習者が学習を望むかどうかではない。null は、その質問が一度もされなかったことを意味する。notesは、値から察せられるとおり、学習者の勤務先宛ての請求書に関する注記なども含め、サポート担当者が学習者について書くものであり、学習者が書くものではない。card_numberは、本来存在すべきでないレガシー列であり、これこそが説明として最も有用な内容である。4件目は実質的に正しい。プラットフォームは各学習者に、その国を担当するサポートチームのsupport_regionを割り当てており、モデルはそれを「地域のサポート領域」と呼んでいる。流暢な説明のどこにも、それが正しいのか、何かを欠いているのかを示すものはないため、レビュー担当者はすべてを読む。列説明を生成するある手法の著者らは、単一プロンプトのモデルについて、幻覚を含む、あるいは不完全な説明を書くという同じ失敗を指摘している(Cai et al., 2026)。
これらは、1つの小さなモデルが2つのプロンプトに対して貪欲デコードで出した回答である。この記録からは、モデルが個人列を見逃すのがモデルの大きさのためなのか、名前、型、5つの値だけを手掛かりに下書きしているためなのかは判別できない。より大きなモデルやより良いプロンプトなら正解の列が増えるかもしれない。それを確かめる方法は、レビュー済みファイルを基準に同じやり方で測定することであり、これはレビューされていないテーブルを任せる前に行うべきである。
実践ルール: モデルには列の分類を引き上げさせてもよいが、引き下げさせてはならない。引き下げができるのはレビュー担当者だけであり、プルリクエストの中で、その理由を列の説明に記して行う。モデルの説明は、その列を知る人が書き直すための初稿として扱う。レビューされていないテーブルのメタデータをモデルに下書きさせる前に、レビュー済みのメタデータを基準として、分類ごと、誤りの方向ごとに測定し、モデルまたはプロンプトが変わるたびに測定し直す。
本番環境で何が問題になるか
メタデータが古くなってもエラーは出ない。以下の各障害は、誰かがそれに依拠するまで、問題がないように見える。
- オーナーが古くなる。 チームは名称変更、統合、解散を経るが、ファイルに書かれたオーナーはそれより長く残る。チームは個人と異なり、一人が離れても存続する。だが、すべてのオーナーが実在するチームであることを、組織のチーム一覧に照らして確認する検査がファイルには必要である。オーナーシップを ODCS で管理している場合、そのチームメンバーは
dateOutとreplacedByUsernameを持つ(ODCS v3.2.0)。検査はこれを読み取り、ownerロールに現在のメンバーがいないチームを見つけることができる。 - 説明が昨年のスキーマを説明している。 列の名前と型が同じままで、意味だけが変わることがある。たとえば
amountが返金を負の数として保持し始める、あるいはstatusに新しい値が加わる。スキーマ検査ではこれを検出できない。コードコメントも同じ形で失敗する。コメントに関する研究によると、不整合の検出器は、コミット前の変更を見る場合のほうが、結果のコードだけを見る場合よりも正確に不整合を検出する(Panthaplackel et al., 2021)。列については、この比較が成り立つのは、プルリクエストが変更を示す場合に限られる。パイプラインのコードは差分として変更されるが、ソースシステムは、どこにも差分が現れないまま書き込む内容を変えることがある。差分がある場合は、パイプラインのロジックを変更するプルリクエストに、そのパイプラインが書き込む列の説明も表示させ、レビュアーが両方を読めるようにする。 - 名前をキーとするメタデータは、名称変更で古くなる。 列のスプレッドシート、ダッシュボードのデータ辞書、列名に対して書かれたポリシーは、フィールド ID の節が示すとおり、名称変更のたびに列を一つ失い、そのことを報告しない。名前をキーとするビューはすべて、ID をキーとするファイルから生成し、スキーマを変更するたびに
problemsを実行する。 - 二つのメタデータ源が互いを上書きする。 カタログサーバーの Web ページとリポジトリ内のファイルはどちらも編集を受け付けるため、どちらの方向の同期でも、もう一方の編集が失われる。DataHub は、UI で行われた編集を取り込まれたメタデータとは分けて保持し、取り込みパイプラインがユーザーの入力を上書きしないようにしている(DataHub dataset entity)。一方を唯一の情報源に選び、もう一方は読み取り専用にするか、生成されるものにする。
- 説明の編集が、誰も必要としないレビューを引き起こす。 PyIceberg では、先ほどのドキュメント編集が示すとおり、ドキュメントを編集するたびにスキーマに新しい ID が付く。そのため、スキーマ ID をキーとするレビューは、何の変更もないのに起動する。代わりに、フィールド ID、名前、型を比較する。
- 下書きされた分類が一括で承認される。 モデルが下書きした列を 40 個追加するプルリクエストでは、説明は読まれるが分類は斜め読みされる。その行き着く先は記録された下書きが示している。下書きされた分類は説明とは別に、保護の弱いものから順に列挙し、レビュアーが、各下書きによって何が無防備なまま残るかを確認できるようにする。
- パイプライン外で作られたテーブルは検査をすり抜ける。 ノートブックや一度限りのバックフィルが、誰もファイルに追加しないテーブルを作る。
problemsは、プルリクエストだけでなく、本番カタログに対して定期的に実行する。
この章で決めたこと
- メタデータはレビューされるファイルである: オーナー、ドメイン、説明、分類は
governance/metadata.tomlに置き、プルリクエストによってのみ変更する。 - 順序付けられた四つの分類:
public、internal、personal、sensitiveとし、列が複数の列から作られる場合は、より厳格な分類が優先される。分類のない列はsensitiveとして扱う。 - テーブルごとに所有チームは一つとし、 個人は置かない。その横にドメインを置く。
- 列は Iceberg のフィールド ID をキーとし、 名前を併記する。これにより、名前の変更がレビューの対象として表に出る。
- 説明は Iceberg の
docに入れ、lib.metadata.applyが書き込む。オーナーとドメインはポインタとしてテーブルプロパティに入れ、分類はファイルに残す。 - カタログはファイルに照らしてテストする:
problemsはカタログ内のすべてのテーブルを走査し、droppedは存在しなくなった列のエントリを検出する。スキーマの変更は、スキーマ ID ではなく、フィールド ID、名前、型によって比較する。 learner_idはすべてのテーブルでinternalとし、crm.learnersを通じて解決される旨を説明に記す。保護はそのテーブルに置き、名前が見える状態で両者を結合してよい者はアクセスポリシーが決める。applyとproblemsはすべての変更で実行する:applyはマージのたびにファイルをカタログに書き込み、problemsはすべてのプルリクエストで、また本番カタログに対して定期的に実行する。- メタデータを下書きするモデルは、プラットフォーム自身のマシン上で動かす。 モデルに示されるサンプル値は、その列が個人データであれば個人データだからである。
- モデルが下書きしたメタデータは提案にすぎない。 下書きはモデルとともに記録し、レビュー済みのファイルに照らして評価し、人が書き直す。モデルは分類を引き上げてもよいが、引き下げてはならない。カタログ自身の列名を挙げたプロンプトはモデルに有利に働くため、プロンプトの例にはプラットフォームのデータの外から取ったものを使う。古くなった説明は、チェックの失敗になる。
この版における本章
第2026.11.31版2026年11月19日時点で例が通過この章の11 例件のうち11件が合格
英語版の書籍(版2026.11.31)から翻訳した。