파일을 다시 쓰지 않고 열 추가하고 이름 바꾸기
읽는 데 약 30분분 걸린다, 8절에 4개 예제이(가) 있음.
AI로 번역함. 영어 원문을 사람이 검증함. 우리가 책을 만드는 방식
영어판 2026.11.10판을 번역한 것이다. 원문 읽기
이 장을 마치면 이미 데이터가 들어 있는 테이블에 열을 추가할 수 있고, Iceberg에서 데이터 파일을 다시 쓰지 않고 열 이름을 바꿀 수 있으며, Delta Lake에서 이름 변경이 왜 테이블 전체를 다시 쓰는 작업이 되는지 설명할 수 있다.
wiki.pageviews_hourly에 처음 세 시간 분량이 기록되고 나면 두 가지 요청이 들어온다. 이 테이블은 Wikimedia 페이지뷰 여섯 시간 분량의 시간별 조회 수를 담고 있으며, 이 데이터는 첫 번째 장에서 적재한다. 따라서 각 변경은 이미 데이터가 들어 있는 테이블에 적용된다. 첫 번째 요청은 계보 열이다. 각 행에 어느 시간별 적재가 그 행을 기록했는지 남겨, 잘못된 적재를 해당 행까지 추적할 수 있게 하자는 것이다. 테이블에는 이런 열이 필요하지만, 이미 들어 있는 행은 그 열이 생기기 전에 기록되었다. 두 번째는 이름 수정이다. 대시보드는 제목 열을 article_title이라고 부르지만, 테이블은 덤프가 쓰는 이름인 page_title이라고 부른다. 두 변경 모두 질문은 같다. 변경 이전에 기록된 파일은 어떻게 되는가?
스키마 변경은 원칙적으로 메타데이터 변경이다. 데이터 파일은 그대로 두고, 포맷이 추가되거나 이름이 바뀐 열을 메타데이터에 기록한다. 이전 파일을 여전히 올바르게 읽을 수 있는지는 포맷이 파일 안에서 열을 찾는 방식에 달려 있다. 이름으로 열을 찾는 포맷은 이름이 바뀌면 문제가 생긴다. 변하지 않는 값으로 열을 찾는 포맷은 그렇지 않다. 이 장에서는 각 포맷이 둘 중 어느 쪽인지, 각 변경에 어떤 비용이 드는지, 그리고 고정된 버전의 Delta Lake 라이브러리가 어떤 변경을 수행하지 못하는지를 보인다.
열은 ID로 추적된다
데이터 파일은 일부 열의 값을 담고 있고, 테이블의 스키마는 각 값이 어느 열에 속하는지 알려 준다. 이 둘을 맞추는 가장 간단한 방법은 이름으로 대응시키는 것이다. 이 방법은 이름이 바뀌기 전까지는 잘 작동한다. 이름이 바뀌면 스키마는 옛 파일에 그 이름으로는 존재하지 않는 열을 가리키게 되고, 리더는 옛 값이 어느 열에 속하는지 추측해야 한다.
이름으로 대응시키는 리더가 옛 이름의 열을 찾지 못하면 두 가지 나쁜 선택지가 남는다. 쿼리를 실패시키거나, 아무 말 없이 그 열을 null로 채우는 것이다. 두 번째가 더 조용한 실패이며, 대시보드는 누군가 확인하기 전까지 몇 주 동안 그 결과를 그대로 보여 줄 수 있다. 우리는 조용한 null을 더 나쁜 실패로 본다. 이는 측정한 결과가 아니라 판단이다. 식별자로 대응시키면 열이 이름과 상관없이 자신의 식별자를 유지하므로 두 가지 문제를 모두 피할 수 있다.
Iceberg는 열을 만들 때 모든 열에 정수 필드 ID를 부여하고, 이 ID로 열을 대응시킨다. 이름은 바뀔 수 있는 라벨일 뿐이며, Iceberg 명세는 필드의 이름을 바꾸면 "이름은 바꾸되 필드 ID는 바꾸지 않아야 한다"고 규정한다 [1]. 리더가 옛 파일을 열면 각 열을 필드 ID로 대응시킨다. 파일에 어떤 필드의 값이 없으면, 명세의 프로젝션 규칙은 여기에 해당하지 않는 두 경우, 즉 아이덴티티 파티션 값과 이름 매핑을 먼저 확인한다. 그런 다음 필드에 initial-default가 설정되어 있으면 그 값을 반환하고, 그 밖의 모든 경우에는 null을 반환한다 [1]. 명세는 기본값과 함께 추가된 열에 대해 initial-default를 정의한다. 이 장에서는 기본값을 설정하지 않으므로, 추가된 열은 모든 옛 행에서 null로 읽힌다.
ID는 직접 확인할 수 있다. Iceberg 테이블의 스키마는 각 필드를 ID와 함께 나열하며, 이름 변경 절의 예제는 이름을 바꾸기 전후에 한 열의 ID를 출력한다. 이름 변경이 열의 식별자를 유지했는지 알고 싶다면 확인해야 할 값은 바로 이 ID다.
Delta Lake는 다른 지점에서 출발한다. Delta Lake의 테이블 스키마는 각 열을 이름으로 지정하고, 리더는 이름으로 대응시킨다. Delta Lake 프로토콜은 선택 기능인 열 매핑(column mapping)을 정의하는데, 이 기능은 파일에 저장된 이름과 리더에게 보이는 이름을 분리한다. 모든 열은 파일에 저장되는 물리적 이름을 갖고, 리더가 사용하는 이름은 파일을 건드리지 않고도 바꿀 수 있는 표시 이름이다. 프로토콜은 열 매핑이 "모든 데이터를 다시 쓰지 않고도 열의 이름 변경과 삭제"를 지원한다고 밝힌다 [2]. 특정 라이브러리 릴리스가 실제로 그렇게 동작하는지는 별개의 문제다. Delta Lake 절에서 고정된 릴리스를 기준으로 이 질문에 답한다.
작업 규칙: Iceberg의 열은 리더가 필드 ID로 대응시키므로 이름을 바꿔도 데이터가 유지된다고 예상한다. Delta Lake의 열은 열 매핑이 켜져 있지 않으면 이름으로 대응된다고 예상한다. 이름 변경에 의존하기 전에 테이블의 복사본에서 먼저 시험하고, 변경 후에는 열 이름을 다시 읽어서 확인한다.
이 부분은 아직 번역되지 않았으므로 영어로 표시된다.
Add load_batch after three hours
The first change is the one the case needs first: a column that does not exist in the files already written. In a pipeline, that happens on an ordinary day. The pipeline starts stamping each load with its number, and the table already holds rows that predate the stamp. The setup writes the first three hours, each as its own commit, so the table holds three snapshots and three data files. An Iceberg snapshot is the table's state after a commit that changes data. Each append in this chapter adds one, and a schema change adds none.
In pyiceberg 0.12.0, you add a column inside a schema update. The call takes the name and the type, and the table assigns the field ID:
with table.update_schema() as update:
update.add_column("load_batch", IntegerType())
To see what the add does to rows already on disk, commit hours 00 to 02, add the column, and append hours 03 to 05, each stamped with its hour number in load_batch. Counting rows by hour of the day splits the table at the add: hours 00 to 02 were written before it, and hours 03 to 05 after. Each hour is one write, so the split is also the split by load.
1"""Adds load_batch to a table that already holds three hours, in Iceberg and then in Delta Lake, and counts the nulls on each side of the add.2Read the four "with load_batch null" lines, which show the rows before the add and the rows after it in each format.3"""45import pyarrow as pa6from deltalake import DeltaTable, write_deltalake7from deltalake.schema import Field, PrimitiveType8from pyiceberg.types import IntegerType910from lib.lakehouse import ICEBERG_ID, delta_file_count, iceberg_file_count, new_warehouse, read_cut_hour, read_delta, split_nulls111213def stamp(rows, hour):14 """Return one hourly load with load_batch set to that load's hour number."""15 # int32 is the width IntegerType stores, so the Arrow column matches the Iceberg field16 return rows.append_column("load_batch", pa.array([hour] * rows.num_rows, type=pa.int32()))171819with new_warehouse() as wh:20 # the schema comes from hour 0, which has no load_batch yet21 table = wh.catalog.create_table(ICEBERG_ID, schema=read_cut_hour(0).schema)22 for hour in range(3): # hours 00 to 02, each one commit, all written before the add23 table.append(read_cut_hour(hour))24 print(f"iceberg snapshots before the add: {len(table.snapshots())}")25 print(f"iceberg data files before the add: {iceberg_file_count(table)}")26 with table.update_schema() as update:27 update.add_column("load_batch", IntegerType())28 print(f"iceberg snapshots after the add: {len(table.snapshots())}")29 print(f"iceberg data files after the add: {iceberg_file_count(table)}")30 for hour in range(3, 6): # hours 03 to 05, written after the add31 table.append(stamp(read_cut_hour(hour), hour))32 iceberg_rows = table.scan().to_arrow()33 print(f"iceberg rows in the table: {iceberg_rows.num_rows}")34 # the split is at 3, the first hour written after the add35 split_nulls(wh.con, iceberg_rows, "iceberg", "load_batch", 3, sides=("written before the add", "written after the add"))3637 path = f"{wh.root}/delta/pageviews_hourly"38 for hour in range(3): # hours 00 to 02, appended as three versions before the add39 write_deltalake(path, read_cut_hour(hour), mode="append")40 print(f"delta version before the add: {DeltaTable(path).version()}")41 print(f"delta data files before the add: {delta_file_count(DeltaTable(path))}")42 DeltaTable(path).alter.add_columns([Field("load_batch", PrimitiveType("integer"))])43 print(f"delta version after the add: {DeltaTable(path).version()}")44 print(f"delta data files after the add: {delta_file_count(DeltaTable(path))}")45 for hour in range(3, 6): # hours 03 to 05, written after the add46 write_deltalake(path, stamp(read_cut_hour(hour), hour), mode="append")47 delta_rows = read_delta(path)48 print(f"delta rows in the table: {delta_rows.num_rows}")49 # the same split as the Iceberg half, at 350 split_nulls(wh.con, delta_rows, "delta", "load_batch", 3, sides=("written before the add", "written after the add"))
python add-column-to-existing-files.pyiceberg snapshots before the add: 3
iceberg data files before the add: 3
iceberg snapshots after the add: 3
iceberg data files after the add: 3
iceberg rows in the table: 2999
iceberg rows written before the add: 1499
iceberg rows written before the add with load_batch null: 1499
iceberg rows written after the add: 1500
iceberg rows written after the add with load_batch null: 0
delta version before the add: 2
delta data files before the add: 3
delta version after the add: 3
delta data files after the add: 3
delta rows in the table: 2999
delta rows written before the add: 1499
delta rows written before the add with load_batch null: 1499
delta rows written after the add: 1500
delta rows written after the add with load_batch null: 0
The add changes the metadata and no data file. The snapshot count stays at 3 across the schema change, and the table keeps its 3 data files.
The 1499 rows written before the add all read null for load_batch, and 0 of the 1500 rows written after it are null. The table holds 2999 rows in all.
Delta Lake, at deltalake 1.6.6, adds a column through its alter object. The call takes a field, and the table's version goes up by one:
DeltaTable(path).alter.add_columns([Field("load_batch", PrimitiveType("integer"))])
The Delta half follows the same sequence: three early hours as three appends, the add, then hours 03 to 05. The first write is version 0, and every version number this chapter prints is Delta's real one. The version moves from 2 to 3, and the table keeps its 3 data files.
Before the add there are 1499 rows, all null for load_batch. Once the three later appends are in, the table has 2999 rows, and 0 of the 1500 rows written after the add are null. This table has no column mapping, a point the Delta Lake rename section returns to.
Both formats give the same result for this case. The old rows stay as they were written, and the column reads as null for them. The writer did not have to touch a single old file. The two halves hold the same row counts and the same null counts, so a disagreement between them would point at a reader, not at the data.
Working rule: Add a column with the format's own call, and never by rewriting the files. Expect the rows written before the add to read null for the column, and check that they do.
이 부분은 아직 번역되지 않았으므로 영어로 표시된다.
Old files read as null
A null in an added column can look like missing data, and a reader who sees it may assume the old files are wrong. They are not. The old files hold the values the pipeline wrote, and the column they lack is filled on read. The rule the reader follows is the one the columns section describes: with no initial-default, no value for the field means null.
That makes the null count a useful check. Count the nulls by hour, as the add example does, and they show the pattern to expect: every row written before the add is null, and no row written after it is. Iceberg has 1499 nulls among its 1499 earlier rows, and Delta Lake has 1499 among its 1499.
If a count falls outside that pattern, a writer sent a different set of columns, or sent the column with nulls, and the cause is in the pipeline, not in the format. Look at the writer for the rows that break the pattern before you query the column, because a query over a column that is partly null will return an answer that looks reasonable.
Working rule: After an add, count nulls in the added column by hour of the day, where each hour is one write. Rows written before the add should be null, and rows written after it should not be. Any other pattern means a writer sent a different set of columns, or sent nulls in the column, so find that writer before you trust the column.
이 부분은 아직 번역되지 않았으므로 영어로 표시된다.
Rename a column by its ID without rewriting files
With the field ID in place, a rename is one call in Iceberg. The call changes the name the schema reports, and keeps the ID:
with table.update_schema() as update:
update.rename_column("page_title", "article_title")
To check that the ID survives, write three hours, read the field ID of page_title, rename the column and read the ID again. The example also counts data files on both sides and queries DuckDB under the new name.
1"""Renames a column in an Iceberg table and reads the old files back under the new name.2Read the field ID lines, the data file lines and the non-null count, which show what the rename kept.3"""45import pyarrow as pa67from lib.lakehouse import (8 ICEBERG_ID,9 iceberg_file_count,10 new_warehouse,11 read_cut_hour,12 scan_arrow,13 snapshot_labels,14 sql_rows,15)1617with new_warehouse() as wh:18 table = wh.catalog.create_table(ICEBERG_ID, schema=read_cut_hour(0).schema)19 for hour in range(3):20 table.append(read_cut_hour(hour))2122 before = table.schema().find_field("page_title").field_id # the ID is what the reader matches on, not the name23 print(f"page_title field ID before the rename: {before}")24 print(f"data files before the rename: {iceberg_file_count(table)}")25 with table.update_schema() as update:26 update.rename_column("page_title", "article_title")27 print(f"article_title field ID after the rename: {table.schema().find_field('article_title').field_id}")28 print(f"data files after the rename: {iceberg_file_count(table)}")2930 rows = scan_arrow(table)31 print(f"rows: {rows.num_rows}")32 # count(column) leaves out nulls, so this counts the rows that have a value under the new name33 count = sql_rows(wh.con, "SELECT count(article_title) FROM t", t=rows)[0][0]34 print(f"article_title not null: {count}")3536 labels = snapshot_labels([snapshot.snapshot_id for snapshot in table.snapshots()])37 first = table.snapshots()[0].snapshot_id # the first snapshot, written before the rename38 print(f"{labels[first]} columns: {', '.join(scan_arrow(table, snapshot_id=first).column_names)}")
python rename-by-id.pypage_title field ID before the rename: 3
data files before the rename: 3
article_title field ID after the rename: 3
data files after the rename: 3
rows: 1499
article_title not null: 1499
snapshot 1 columns: hour_utc, domain_code, page_title, views, response_bytes
The rename keeps the field ID. page_title has ID 3 before the call, and article_title has ID 3 after it.
The data file count is 3 before the call and 3 after it, so no file was rewritten. The DuckDB query counts 1499 non-null article_title values out of 1499 rows. Every row counts, including the rows written under page_title, because the reader matches the files by ID and reads them under the new name.
The dashboards need the name, and the table does not have to be rewritten to give it to them. The data stays as it was written, and the next read sees the renamed column. The run also prints the first snapshot's columns, which are hour_utc, domain_code, page_title, views and response_bytes. A snapshot reads with the schema it was written with, so an older snapshot still reports the old name. Chapter 2 covers reading older snapshots in general, and the point here is narrower: a rename does not reach back into the history.
The cost comparison is what makes this the right call for Iceberg. A rename that keeps the ID touches the metadata and nothing else, so its cost does not grow with the size of the table. The same rename done by copying the table costs one read and one write of every row. The section on Delta Lake shows what that copy costs in that format.
Working rule: Rename an Iceberg column when its name is wrong, and check the field ID before and after the call. The field ID must be the same, and the data file count must not change. Tell every reader of the table about the rename, because the current schema has only article_title, and an older snapshot still has page_title.
이 버전에서 Delta Lake에는 이름 변경 기능이 없다
Delta Lake에서 같은 이름 변경을 수행하는 호출은 이 버전에 없다. Delta Lake 테이블 변경 객체에는 deltalake 1.6.6에서 이름 변경 메서드가 없으며, 그 메서드 목록은 패키지 문서 [3]에 있다. 이름 변경처럼 보이는 것은 set_column_metadata이다. 이 메서드는 필드 메타데이터의 딕셔너리를 받으므로, name 키를 넘기는 것을 막는 장치가 없다. name를 넘겨도 호출은 오류 없이 반환된다. 이 호출은 열 매핑을 켰든 켜지 않았든 어떤 테이블에서도 아무것도 바꾸지 않으며, 이 절이 보여 주는 함정이 바로 이것이다.
함정 예제는 프로토콜이 이름 변경에 쓰는 경로인 열 매핑을 켠 테이블을 만든 다음, 그 호출을 보낸다.
DeltaTable(path).alter.set_column_metadata("page_title", {"name": "article_title"})
1"""Calls set_column_metadata with a name key on a Delta Lake table with column mapping on, then reads the names back and queries2under the new name. The columns read back line and the binder error are the lines to read.3"""45from deltalake import DeltaTable, write_deltalake67from lib.lakehouse import new_warehouse, read_cut_hour, read_delta, safe_error, sql_rows89with new_warehouse() as wh:10 path = f"{wh.root}/delta/pageviews_hourly"11 # column mapping on: the protocol's route to a rename, which this release does not offer as a call12 write_deltalake(path, read_cut_hour(0),13 configuration={"delta.columnMapping.mode": "name"})14 print(f"version before the rename: {DeltaTable(path).version()}")15 # the call raises nothing and writes a commit, so the names read back below are the only check16 DeltaTable(path).alter.set_column_metadata("page_title", {"name": "article_title"})17 print("set_column_metadata returned")18 table = DeltaTable(path)19 print(f"version after the rename: {table.version()}")20 page = next(field for field in table.schema().fields if field.name == "page_title")21 # the name key the call wrote into the field's metadata, which the reader does not use for the column name22 print(f"name in page_title metadata after the rename: {page.metadata['name']}")23 print(f"columns read back: {', '.join(read_delta(path).column_names)}")24 try:25 sql_rows(wh.con, "SELECT article_title FROM t", t=read_delta(path))26 except Exception as exc:27 print(safe_error(exc, wh))
python delta-rename-trap.pyversion before the rename: 0
set_column_metadata returned
version after the rename: 1
name in page_title metadata after the rename: article_title
columns read back: hour_utc, domain_code, page_title, views, response_bytes
BinderException: Binder Error: Referenced column "article_title" not found in FROM clause!
Candidate bindings: "page_title", "domain_code", "hour_utc", "views", "response_bytes"
LINE 1: SELECT article_title FROM t
^^^^^^^^^^^^^
호출은 반환되고 테이블의 버전은 0에서 1로 바뀐다. 즉 라이브러리가 커밋을 하나 기록한 것이다. name 키는 필드의 메타데이터에 들어 있다. 그러나 열은 여전히 page_title이다. 라이브러리로 다시 읽은 이름은 hour_utc, domain_code, page_title, views, response_bytes이다. article_title을 요청하는 DuckDB 쿼리는 BinderException와 함께 실패하며, 오류 메시지는 바인딩할 수 있는 열 가운데 page_title을 나열한다.
함정은 호출이 이름 변경처럼 보이고, 이름 변경처럼 성공한다는 데 있다. 반환값에는 이름이 그대로라는 정보가 전혀 없으므로, 이름을 직접 읽어 보아야만 사실을 알 수 있다.
이 버전에서 열 매핑은 이름 변경을 제공하지 않는다. 함정 예제의 테이블은 delta.columnMapping.mode이 name으로 설정되어 있지만, 호출은 여전히 어떤 이름도 바꾸지 않는다. 프로토콜의 열 매핑 절은 이름 변경을 설명하지만 [2], deltalake 1.6.6에는 이를 수행하는 호출이 없다.
1"""Renames a Delta Lake column by overwriting the table with renamed data and schema, then reads the version before the rewrite back.2Compare the two columns lines: the version before the rewrite, and the version the rewrite makes.3"""45from deltalake import DeltaTable, write_deltalake67from lib.lakehouse import new_warehouse, read_cut_hour, read_delta89with new_warehouse() as wh:10 path = f"{wh.root}/delta/pageviews_hourly"11 for hour in range(3):12 write_deltalake(path, read_cut_hour(hour), mode="append")13 print(f"data files before the rewrite: {len(DeltaTable(path).file_uris())}")14 before = DeltaTable(path).version() # read first, so the old version can be read back after the rewrite15 print(f"version before the rewrite: {before}")16 print(f"columns before the rewrite: {', '.join(read_delta(path, version=before).column_names)}")1718 # the new names, in the table's column order: only the third one changes19 renamed = read_delta(path).rename_columns(["hour_utc", "domain_code", "article_title", "views", "response_bytes"])20 # replace the data and the schema together, in one commit, so readers of the new version see both at once21 write_deltalake(path, renamed, mode="overwrite", schema_mode="overwrite")22 print(f"data files after the rewrite: {len(DeltaTable(path).file_uris())}")23 after = DeltaTable(path).version()24 print(f"version after the rewrite: {after}")25 print(f"columns after the rewrite: {', '.join(read_delta(path).column_names)}")26 print(f"rows after the rewrite: {read_delta(path).num_rows}")
python delta-rename-by-rewrite.pydata files before the rewrite: 3
version before the rewrite: 2
columns before the rewrite: hour_utc, domain_code, page_title, views, response_bytes
data files after the rewrite: 1
version after the rewrite: 3
columns after the rewrite: hour_utc, domain_code, article_title, views, response_bytes
rows after the rewrite: 1499
이 버전에서 이름을 얻는 방법은 다시 쓰기이다. 다시 쓰기 예제는 라이브러리로 테이블 전체를 읽고, 메모리에서 열 이름을 바꾼 다음, 데이터와 스키마를 함께 교체하는 mode="overwrite"와 schema_mode="overwrite"로 결과를 다시 기록한다. 테이블은 다시 쓰기 전에 데이터 파일이 3개였고 다시 쓴 뒤에는 1개이다. 다시 쓰기는 버전 3을 만들며, 이 버전은 article_title을 읽고 그 안에 1499개의 행이 있다.
다시 쓰기는 모든 행을 읽고 다시 기록하므로 테이블 크기만큼의 비용이 든다. 여기의 테이블은 작지만, 수백만 행을 가진 운영 테이블도 행마다 같은 비용을 치르므로 팀은 다시 쓰기를 독립된 작업으로 계획해야 한다. 다시 쓰기 이전 버전인 2은 여전히 page_title을 읽으며, 예제는 이 값도 출력한다. 따라서 다시 쓰기는 현재 버전만 바꾸고, 이전 버전은 기록될 때의 이름을 그대로 유지한다. 다시 쓰기를 실행하기 전에, 그 열을 이름으로 요청하는 읽기 작업을 모두 나열한다. 전환은 하나의 커밋으로 일어나므로 현재 버전을 읽는 모든 읽기 작업이 같은 순간에 옮겨 가지만, 이전 버전을 고정한 작업은 옛 이름을 유지한다. 그런 작업은 읽기 작업과 함께 옮기고, 옮기기가 끝날 때까지 다시 쓰기가 대체한 버전 번호를 기록해 둔다.
작업 규칙: Delta Lake의 열 이름은 테이블을 만들 때 정한다. 이 버전에서는 나중에 이름을 바꾸려면 테이블 전체를 다시 써야 하기 때문이다. 열 이름을 바꾸는 데 set_column_metadata를 쓰지 않는다. 이 호출은 버전과 메타데이터를 바꾸지만 열은 이름을 그대로 유지한다. 스키마를 변경한 뒤에는 함정 예제처럼 라이브러리로 열 이름을 다시 읽고, 쿼리가 그 이름에 의존하기 전에 확인한다.
운영 환경에서 잘못되는 것들
스키마 변경은 소리 없이 실패하는 경우가 소리 내어 실패하는 경우보다 많다. 아래의 각 실패에는 지켜볼 수 있는 징후가 있다.
먼저 아무 일도 하지 않는 이름 변경이 있다. set_column_metadata 호출은 성공하고 이력에 커밋이 나타나지만, 열은 예전 이름을 그대로 유지한다. 이 실패는 article_title을(를) 사용하는 첫 쿼리에서 드러난다. 해당 DuckDB 쿼리가 BinderException와(과) 함께 실패한다. 이런 쿼리를 실행하는 예약 작업은 변경 후 처음 실행할 때 실패하므로, 오류가 원인 가까이에서 나타난다.
다음은 이력에 남은 예전 이름이다. 재작성은 현재 버전에 article_title이라는 이름을 붙이지만, 이전 버전은 기록될 당시의 이름을 그대로 유지한다. 재작성 예제가 이를 보여 준다. 버전 2은(는) 여전히 page_title을(를) 읽는다. Iceberg 스냅숏도 마찬가지여서, 첫 번째 스냅숏은 여전히 page_title을(를) 보고한다. 이전 버전이나 스냅숏을 article_title(으)로 읽는 쿼리는 그런 열을 찾지 못한다. 버전 번호나 스냅숏 번호로 읽을 때는 그 시점에 유효하던 이름이 필요하므로, 버전 번호를 고정하는 작업은 스키마도 함께 고정하는 셈이다.
세 번째는 누락된 데이터처럼 보이는 null이다. 추가된 열은 추가 이전에 기록된 모든 행에서 null로 읽힌다. 그 열의 null 개수는 정상이며, 추가 예제가 보여 주는 전후 패턴을 벗어날 때만 결함이다. 추가 예제에서 한 것처럼 시간별로 null을 세고, 패턴을 벗어나는 행이 있으면 조사한다.
마지막은 스냅숏 목록에 나타나지 않는 스키마 변경이다. Iceberg에서 열을 추가하거나 이름을 바꿔도 스냅숏 수는 그대로였고, 파일 수도 그대로였다. 스냅숏 수를 세어 스키마 변경을 찾는 도구는 이런 변경을 놓친다. 무엇이 바뀌었는지 알아야 할 때는 스키마 자체를 필드 ID와 이름으로 비교한다.
작업 규칙: 스키마를 변경한 뒤에는 다운스트림 쿼리를 실행하기 전에 세 가지를 한다. 라이브러리를 통해 열 이름을 다시 읽고, 추가된 각 열의 null을 시간별로 세며(여기서 한 시간은 한 번의 쓰기이다), 스냅숏 수가 아니라 스키마를 변경이 의도한 내용과 비교한다.
이 장에서 내린 결정
이 절의 표는 이 장에서 다룬 변경 사항을 기준으로 두 형식을 나란히 비교한다. 각 셀의 내용은 이 장의 예제에서 나온 것이다.
| 변경 | Iceberg | Delta Lake |
|---|---|---|
| 열 추가 | 동작한다. 기존 행은 null로 읽히며, 스냅샷 수는 3로 그대로이다 | 동작한다. 기존 행은 null로 읽히며, 버전이 하나 올라간다 |
| 열 이름 변경 | 동작한다. 필드 ID는 그대로이고, 데이터 파일은 다시 쓰이지 않는다 | 이름 변경 호출이 없다. set_column_metadata는 커밋되지만 이름은 바꾸지 않으며, 이름은 재작성으로 얻는다 |
| 이전 스냅샷 또는 버전 읽기 | 이전 이름이 보인다 | 이전 이름이 보인다 |
- 두 형식 모두에서 이미 데이터가 들어 있는 테이블에 열을 추가한다. 기존 행은 이 열을 null로 읽으며, 열 추가 예제는 이 패턴을 확인해 주는 시간대별 집계를 보여 준다. 이전 파일을 전혀 쓰지 않으므로 테이블을 복사하는 방식보다 이 방법을 권장한다.
- Iceberg 열의 이름은
rename_column으로 바꾸고, 전후의 필드 ID가 같은지 확인한다. 이 방법은 비용이 테이블 크기에 좌우되지 않으므로, 이름이 잘못된 모든 Iceberg 열에 권장한다. - Delta Lake 열 이름은 테이블을 만들 때 정한다. 고정한 릴리스에서는 열 이름 변경이 테이블 전체의 재작성이며, 이름이 잘못되었을 때 대비해야 할 비용이 바로 이것이다.
- Delta Lake 열의 이름을
set_column_metadata로 바꾸려 하지 않는다. 이 호출은 성공하지만 이름에는 아무 변화도 주지 않는다. - 이 고정 버전에서는 열 매핑으로 이름을 바꿀 수 있다고 기대하지 않는다. 라이브러리에는 이름 변경을 수행하는 호출이 없으므로, 매핑을 켜도 이름 변경 기능은 생기지 않는다.
- 스키마를 변경할 때마다, 쿼리가 열 이름에 의존하기 전에 두 형식 모두에서 열 이름을 다시 읽어 확인한다.
이 부분은 아직 번역되지 않았으므로 영어로 표시된다.
Sources
- Apache Iceberg Table Spec, Schema Evolution (Column Projection), https://iceberg.apache.org/spec/, read Nov 6, 2026. Quoted: "Renaming an existing field must change the name, but not the field ID." The null rule, which the text paraphrases, is in the same section.
- Delta Transaction Log Protocol, Column Mapping section, tag v4.4.1, https://raw.githubusercontent.com/delta-io/delta/v4.4.1/PROTOCOL.md, read Nov 6, 2026. Quoted: "the renaming and dropping of columns without having to rewrite all the data."
- deltalake 1.6.6, the methods of
DeltaTable.alterin the installed package:add_columns,add_constraint,add_feature,drop_column_not_null,drop_constraint,set_column_metadata,set_table_description,set_table_nameandset_table_properties. None renames a column. To list them, rundir(DeltaTable(path).alter).
이 판의 이 장
2026.11.10판예제 통과 2026년 11월 20이 장에서 4개 예제개 중 4개가 통과한다
영어판 2026.11.10판을 번역한 것이다.