테스트할 수 있는 카탈로그
읽는 데 약 59분분 걸린다, 12절에 11개 예제이(가) 있음.
AI로 번역함. 영어 원문을 사람이 검증함. 우리가 책을 만드는 방식
영어판 2026.11.31판을 번역한 것이다. 원문 읽기
이 페이지의 내용
- Keep the metadata in a reviewed file
- 필드 ID로 열 메타데이터를 키 지정하라
- 테이블 스키마에 설명 쓰기
- A description edit is a schema change
- Test the catalog against the metadata
- Catch schema changes before the metadata goes stale
- Classify pseudonymous IDs for joining
- 로컬 모델로 메타데이터 초안 작성하기
- 프롬프트의 예제가 답을 알려 줄 수 있다
- 모델의 초안이 어디에서 틀리는지 측정한다
- 운영 환경에서 무엇이 잘못되는가
- 이 장에서 결정한 것
이 장을 마치면 카탈로그의 메타데이터를 코드로 관리할 수 있다. 모든 테이블에는 소유자와 도메인이, 모든 컬럼에는 설명과 분류가 붙으며, 이 내용은 팀이 검토하는 파일에 담긴다. 이 파일은 이름이 바뀌어도 아무것도 잃어버리지 않도록 키를 지정해 작성하고, Iceberg 카탈로그에 기록하며, 빠진 항목이 있으면 실패하는 테스트로 검사한다. 또 로컬 모델이 설명과 분류의 초안을 작성하게 하고, 누군가 그 초안을 받아들이기 전에 초안이 얼마나 자주 틀리는지 측정한다.
이 플랫폼의 카탈로그에는 세 가지 문제가 있다. 웹 기반 학습 플랫폼이 운영하는 Iceberg 카탈로그인 이 웨어하우스에는 파이프라인이 계속 테이블을 추가한다. 웨어하우스에는 원본 테이블 여덟 개가 있으며, 이 테이블들은 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는 테이블 스키마 안에서 고유한 정수이며, 명세는 이름을 바꿔도 이 ID를 유지하도록 요구한다. "기존 필드의 이름을 바꾸면 이름은 바뀌지만 필드 ID는 바뀌지 않아야 한다"(Iceberg table spec). 값을 읽는 쪽도 이 ID로 열을 찾는다. Iceberg는 데이터 파일의 열을 필드 ID로 선택하므로, 이름이 바뀐 열도 이름을 바꾸기 전에 작성된 파일을 그대로 읽는다(Iceberg table spec). 이름으로 키 지정한 메타데이터는 붙잡을 것이 없다. 이름을 바꾸고 나면 옛 이름은 아무것도 가리키지 않고, 새 이름에는 항목이 없다.
플랫폼의 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의 다른 개인 정보 열을 모두 볼 수 있는 지원 담당자는 contact_email을 redact로 받는다. 이름 변경은 안전한 쪽으로 실패하며, 가장 먼저 알아차리는 쪽은 지원 부서다.
작업 규칙: 열 메타데이터는 필드 ID로 키 지정하고, 사람이 볼 수 있도록 이름을 옆에 둔다. 이름이 더 이상 일치하지 않으면 새 열로 보지 말고 그 열의 설명을 검토할 사유로 취급한다. 열을 이름으로만 아는 시스템의 이름 키 뷰는 손으로 관리하지 말고 ID로 키 지정한 파일에서 생성한다.
테이블 스키마에 설명 쓰기
메타데이터 파일은 플랫폼의 메타데이터를 검토하는 곳이다. 그러나 테이블을 읽는 사람과 도구는 카탈로그를 들여다보므로, 메타데이터 일부는 카탈로그로 복사해야 한다. 문제는 각 사실이 카탈로그의 어디에 속하는가이며, Iceberg는 이 중 일부에 답을 준다. 각 컬럼은 스키마와 함께 이동하는 선택적 주석인 doc을 가질 수 있다(Iceberg table spec). 테이블에는 문자열 맵인 속성(properties)도 있지만, 명세는 이 맵이 "읽기와 쓰기에 영향을 주는 설정을 제어하는 데 쓰이며 임의의 메타데이터를 담기 위한 것이 아니다"라고 밝힌다.
그래서 명세를 따를 수 있는 데까지 따른다. 컬럼 설명은 doc에 넣고, 분류는 정책과 검사가 읽는 파일에 그대로 둔다. 소유자와 도메인은 테이블만 읽는 도구를 위한 안내로서 두 개의 테이블 속성에 넣는다. 그러면 테이블만 있고 저장소가 없는 사람도 문의할 팀을 찾을 수 있다. 이 마지막 선택은 명세가 밝힌 의도에 어긋나므로, 짧은 값 두 개로만 제한한다.
Iceberg 프로젝트가 내놓은 답은 별도의 채널이다. Iceberg 1.12.0의 REST 카탈로그 명세는 labels를 추가한다. 이는 카탈로그가 테이블과 함께 반환하는 소유권이나 분류 정보로, 테이블별, 필드 ID별로 관리되며 일부러 속성과 분리되어 있다(REST catalog spec). 이 변경은 pull request 15750으로 반영되었다. PyIceberg 0.12.0의 REST 클라이언트는 이를 읽지 않는다(source).
복사는 lib.metadata.apply이 수행한다. 파일이 설명하고 카탈로그가 보유한 모든 테이블에 대해, 각 설명을 해당 컬럼의 doc에, 소유자와 도메인을 속성에 쓰되 달라진 부분만 바꾼다. 플랫폼의 소스 테이블 여덟 개로 구성한 새 카탈로그에 대해 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가 들어 있다. 두 번째 실행에서는 0개의 테이블이 바뀌었다. crm.learners의 스키마 ID는 0에서 1로 바뀌었는데, 어떤 컬럼의 ID, 이름, 타입도 바뀌지 않았다. 이는 다음 하위 절의 주제이다.
이 부분은 아직 번역되지 않았으므로 영어로 표시된다.
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.
이 부분은 아직 번역되지 않았으므로 영어로 표시된다.
Classify pseudonymous IDs for joining
The metadata file classifies some columns that point at people as internal, and the most common of them is learner_id. It's a number with no meaning of its own, and the platform's analysts and data scientists need it to join enrollments, events, payments and tickets to each other. An ID with no meaning of its own, such as learner_id, is a pseudonymous identifier: it doesn't name anyone, but it leads to someone through another table. One ID reaches further than its classification suggests. The code counts the tables that carry it, joins enrollments to learners, and asks the access policy who can make that join and see names:
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)
One join reaches a person: 20,000 of 20,000 enrollments lead to an email, and with the email come the learner's name, phone number, address and date of birth, which are among the table's personal columns. Yet learner_id is internal in all 7 tables that carry it.
The EU's General Data Protection Regulation (GDPR) addresses data like this in Recital 26: "Personal data which have undergone pseudonymisation, which could be attributed to a natural person by the use of additional information should be considered to be information on an identifiable natural person" (GDPR, Recital 26). What the recital means for a given platform is a question for its lawyers, and we don't answer it.
What we do decide is how the book's code treats the ID. internal describes what the column reveals in the table that holds it, and each learner_id's description in the metadata file says the rest, naming crm.learners as the table that resolves it, as learning.enrollments' does: "The learner who enrolled. Identifies a person when joined with crm.learners." The protection sits on the table that resolves the ID. Chapter 5 decides who may read the personal columns of crm.learners, and the example's last lines ask its policy who sees learners' names there: agent-a01, agent-a05, agent-a09, marketing-1. Of them, only the support agents also read a learner_id in another table: agent-a01 (support.tickets), agent-a05 (support.tickets), agent-a09 (support.tickets). They can put a name on every ticket of their region, and that's their job. Marketing sees names but reads no other table that holds the ID.
So the policy, not the ID's classification, decides who can make the join. Classifying support.tickets.learner_id as personal would change nothing for support, the only group that reads the table, because the policy already shows support every personal column. Erasure, in chapter 7, has to reach every table that holds a learner's learner_id, whatever its classification. We call such IDs pseudonymized, never anonymized.
Working rule: Classify a pseudonymous ID by what its own table reveals, so the joins your analysts need keep working, and say in its description what it resolves through. Protect the table that resolves it, and include the ID in every erasure. Who can resolve the ID is an access decision: list the users who may read both the ID and the resolving table's personal columns unmasked, and grant that pair only to those whose job is linking rows to people.
로컬 모델로 메타데이터 초안 작성하기
카탈로그 대상 테스트는 어떤 열에 설명이 없는지 알려 주지만, 설명을 대신 써 주지는 않는다. 모든 열에 설명을 쓰고 분류를 정하는 일은 카탈로그를 관리하는 작업 중 가장 느린 부분이며, 파이프라인이 테이블을 추가할 때마다 이 일이 되돌아온다. 언어 모델은 카탈로그 도구가 보여 줄 수 있는 정보, 즉 열의 이름과 타입, 그리고 값 몇 개만으로 설명과 분류의 초안을 쓸 수 있다. 연구는 이 도움과 한계를 모두 뒷받침한다. 한 벤치마크에서 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), 기록은 다시 만들었을 때 같은 결과가 나와야 하고 샘플링한 답은 여러 번의 추출 중 하나일 뿐이기 때문이다.
모델은 플랫폼의 소스 테이블 여덟 개에 있는 각 열에 대해 테이블 이름, 열 이름과 Iceberg 타입, 고정된 시드로 고른 열 값 다섯 개, 그리고 분류 표의 의미와 함께 네 가지 분류를 보았다. 각 의미에는 예가 두 개씩 붙어 있으며, 그중 플랫폼에 실제로 있는 열은 하나도 없다. sensitive의 경우 "정부 발급 ID 번호나 건강 상태"가 그 예이다. 모델에는 한 문장의 설명과 하나의 분류를 JSON으로 요청했다. 기록의 매니페스트에는 모델, 리비전, 프롬프트와 설정의 해시, 날짜가 적혀 있으므로 누구나 다시 기록하여 비교할 수 있다.
열이 개인 데이터이면 그 다섯 개 값도 개인 데이터이다. 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이다. 이는 형식이 작동했음을 보여 줄 뿐, 답이 맞는지는 말해 주지 않는다. 검토와 일치하는 열은 40 of 64 (62%)개인데, 이 숫자 하나는 틀린 곳이 어디인지 감춘다. 일치의 대부분은 internal 열을 internal으로 분류한 경우이다. 플랫폼의 개인 열 중에서 모델이 0 of 12개를 personal으로 분류했다. sensitive 열인 카드 번호와 지급 계좌 중에서는 0 of 2개만 맞혔고, 모델은 둘 다 internal으로 분류했다.
프롬프트의 예제가 답을 알려 줄 수 있다
프롬프트에 든 예제도 측정의 일부다. 스크립트는 같은 모델이 같은 열에 대해 내놓는 답을 두 번째 프롬프트로도 기록한다. 이 프롬프트는 예제만 다르고 나머지는 같다. 예제는 personal와 sensitive에 대해서만 주어지며, 플랫폼의 실제 열을 가리킨다. personal의 예제는 "이름, 연락처, 주소 또는 사람이 직접 쓴 텍스트"이고, sensitive의 예제는 카드 번호나 은행 계좌이다. 여기에 해당하는 열은 billing.payments.card_number와 crm.instructors.payout_iban이며, 민감한 열은 이 둘뿐이다. 두 프롬프트의 답을 나란히 놓으면 예제가 무엇을 바꾸는지 드러난다.
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개를 맞히며, 두 열을 모두 internal로 분류한다.
전체 일치율은 거의 변하지 않는다. 41 of 64과 40 of 64이므로 숫자 하나만 보아서는 차이를 알 수 없다. 개인 열은 예제로 얻은 이득이 없었다. 0 of 12은 그 프롬프트에서도 personal로 분류되었다.
"카드 번호"는 card_number를 거의 그대로 가리킨다. 반면 "이름"은 full_name가 이름에 해당하는지를 모델의 판단에 맡기는데, 모델은 그렇게 판단하지 못했다. 예제가 카탈로그와 일치하는 프롬프트는 보호가 가장 필요한 열에서 모델을 실제보다 좋아 보이게 만든다. 그래서 이 책의 프롬프트는 예제를 플랫폼의 데이터 바깥에서 가져온다.
작업 규칙: 모델로 메타데이터 초안을 작성할 때는 보내도 되는 입력만 사용하고, 가능하면 자체 장비에서 돌아가는 모델을 쓴다. 각 답을 모델, 모델의 리비전, 프롬프트, 설정과 함께 기록해 검토자가 각 초안을 무엇이 만들었는지 볼 수 있게 하고, 어떤 답이든 읽기 전에 파싱하고 검증한다. 프롬프트의 예제는 프롬프트를 측정하는 테이블 바깥에서 가져온다. 검토를 마친 메타데이터와의 일치율은 숫자 하나로 보고하지 말고 분류별로 보고한다.
모델의 초안이 어디에서 틀리는지 측정한다
기록된 초안은 플랫폼의 원본 테이블에 대해 로컬 모델이 작성한 설명과 분류이며, 대부분의 열에서 검토를 거친 분류와 일치한다. 거버넌스에서는 어느 방향으로 틀리는지가 더 중요하다. 필요 이상으로 보호하는 분류는 검토자에게 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로 분류했다.
설명은 다른 방식으로 실패하며, 모델이 작성한 설명 네 개를 검토를 거친 설명과 나란히 놓으면 이를 볼 수 있다.
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.
모든 설명이 유려하고 그럴듯하지만, 네 개 중 세 개는 플랫폼이 그 열을 어떻게 채우는지 아는 사람만 쓸 수 있는 내용을 빠뜨린다. ai_training_consent는 학습자의 텍스트를 플랫폼의 AI 학습에 사용해도 되는지를 기록하는 것이지 학습자가 학습을 원하는지를 기록하는 것이 아니며, null은 그 질문을 한 적이 없다는 뜻이다. notes는 값이 시사하듯 학습자가 아니라 지원 담당자가 학습자에 관해 작성하며, 학습자의 고용주에게 보낼 청구서에 관한 메모가 그 예다. 그리고 card_number는 아예 존재해서는 안 되는 레거시 열이며, 설명이 할 수 있는 가장 유용한 말이 바로 그것이다. 네 번째는 본질적으로 맞다. 플랫폼은 각 학습자에게 그 학습자의 국가를 담당하는 지원팀의 support_region를 부여하는데, 모델은 이를 "지역 지원 영역"이라고 부른다. 유려한 설명만으로는 그 설명이 옳은지 무언가를 빠뜨렸는지 알 수 없으므로 검토자는 모든 설명을 읽는다. 열 설명을 생성하는 한 방법의 저자들도 단일 프롬프트 모델에서 같은 실패를 지적하는데, 이 모델들은 환각이 섞이거나 불완전한 설명을 쓴다(Cai et al., 2026).
이 결과는 작은 모델 하나가 두 프롬프트에 대해 탐욕적 디코딩으로 낸 답이다. 기록만으로는 모델이 개인 열을 놓치는 이유가 크기 때문인지, 이름과 타입, 값 다섯 개만 가지고 초안을 쓰기 때문인지 알 수 없다. 더 큰 모델이나 더 나은 프롬프트가 더 많은 열을 맞힐 수도 있으며, 이를 확인하는 방법은 검토를 거친 파일을 기준으로 같은 방식으로 측정하는 것이다. 아무도 검토하지 않은 테이블을 맡기기 전에 그렇게 해야 한다.
작업 규칙: 모델이 열의 분류를 높이는 것은 허용하되 낮추는 것은 허용하지 않는다. 분류를 낮추는 것은 검토자만 풀 리퀘스트에서 그 이유를 열의 설명에 적어 수행한다. 모델이 쓴 설명은 그 열을 아는 사람이 다시 써야 하는 초안으로 취급한다. 아무도 검토하지 않은 테이블의 메타데이터를 모델이 초안으로 작성하게 하기 전에, 검토를 거친 메타데이터를 기준으로 분류별, 오류 방향별로 모델을 측정하고, 모델이나 프롬프트가 바뀔 때마다 다시 측정한다.
운영 환경에서 무엇이 잘못되는가
메타데이터가 낡아도 오류는 발생하지 않으며, 아래의 각 실패는 누군가 그것에 의존하기 전까지는 완전해 보인다.
- 소유자가 낡는다. 팀은 이름이 바뀌거나 합쳐지거나 해체되는데, 파일에 적힌 소유자는 그보다 오래 남는다. 팀은 개인과 달리 한 사람이 떠나도 유지되지만, 그래도 파일에는 모든 소유자가 실제로 존재하는 팀인지 확인하는 검사가 필요하며, 이 검사는 조직의 팀 목록을 대상으로 실행한다. 소유권을 ODCS로 관리한다면 ODCS의 팀 구성원은
dateOut와replacedByUsername를 가지고 있으므로(ODCS v3.2.0), 검사에서 이를 읽어owner역할을 맡은 현재 구성원이 없는 팀을 찾을 수 있다. - 설명이 지난해의 스키마를 설명한다. 열의 이름과 타입은 그대로인데 의미가 바뀌는 경우가 있다.
amount가 환불을 음수로 담기 시작하거나status에 새로운 값이 추가되는 경우다. 어떤 스키마 검사도 이를 발견하지 못한다. 코드 주석도 같은 방식으로 실패한다. 이에 관한 연구에서는 탐지기가 결과 코드만 볼 때보다 커밋되기 전의 변경을 볼 때 불일치를 더 정확하게 찾아낸다는 결과가 나왔다(Panthaplackel et al., 2021). 열의 경우 이러한 비교는 풀 리퀘스트에 변경이 드러나는 곳에서만 성립한다. 파이프라인의 코드는 diff로 변경되지만, 소스 시스템은 어디에도 diff를 남기지 않고 기록하는 내용을 바꿀 수 있다. diff가 있는 곳에서는 파이프라인의 로직을 바꾸는 풀 리퀘스트가 그 파이프라인이 기록하는 열의 설명도 함께 보여 주도록 하여, 검토자가 둘 다 읽게 한다. - 이름을 키로 삼은 메타데이터는 이름이 바뀌면 낡는다. 열을 정리한 스프레드시트, 대시보드의 데이터 사전, 열 이름을 기준으로 작성한 정책은 이름이 바뀔 때마다 열 하나를 잃으며, 필드 ID 절에서 보듯이 이를 보고하지도 않는다. 이름을 키로 하는 모든 뷰는 ID를 키로 하는 파일에서 생성하고, 스키마가 바뀔 때마다
problems를 실행한다. - 두 메타데이터 소스가 서로를 덮어쓴다. 카탈로그 서버의 웹 페이지와 저장소의 파일은 모두 편집을 받아들이므로, 어느 방향으로 동기화하든 상대편의 편집을 잃는다. DataHub는 UI에서 이루어진 편집을 수집된 메타데이터와 분리해 보관하여, 수집 파이프라인이 사용자가 입력한 내용을 덮어쓰지 않도록 한다(DataHub dataset entity). 소스를 하나만 선택하고, 나머지는 읽기 전용으로 두거나 생성되도록 한다.
- 설명을 편집하면 아무도 필요로 하지 않는 검토가 시작된다. PyIceberg에서는 앞의 설명 편집에서 보듯이 설명을 편집할 때마다 스키마에 새 ID가 부여되므로, 스키마 ID를 기준으로 한 검토는 아무 이유 없이 실행된다. 대신 필드 ID, 이름, 타입을 비교한다.
- 초안으로 작성된 분류가 한꺼번에 승인된다. 모델이 초안을 작성한 열 마흔 개를 추가하는 풀 리퀘스트에서는 설명은 읽히지만 분류는 훑어보는 데 그치며, 기록된 초안은 그 결과가 어떻게 되는지 보여 준다. 초안으로 작성된 각 분류를 설명과 따로, 보호 수준이 가장 낮은 것부터 나열하여, 검토자가 각 초안 때문에 무엇이 보호되지 않은 채 남게 되는지 알 수 있게 한다.
- 파이프라인 밖에서 만들어진 테이블은 검사를 피한다. 노트북이나 일회성 백필은 아무도 파일에 추가하지 않을 테이블을 만든다.
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판을 번역한 것이다.