ファイルを書き換えずに列を追加・名前変更する

読了まで約36 分分、8 節 節の 4 例 例。

第2026.11.10版 2026年11月20日時点で例が通過 39 例中 39 例が合格 変更点

AIによる翻訳。英語版は人による検証済みである。 当社の書籍の作り方

英語版の書籍(版2026.11.10)から翻訳した。 原文を読む

この章を終えると、すでにデータを保持しているテーブルに列を追加できる。また、Iceberg でデータファイルを書き換えずに列の名前を変更できる。さらに、Delta Lake で名前変更がテーブル全体の書き換えになる理由を説明できる。

wiki.pageviews_hourly に最初の3時間分が書き込まれた時点で、2つの要求が届く。このテーブルには、Wikimedia のページビュー6時間分について、1時間ごとの閲覧数が入っている。これは最初の章で読み込んだものであり、したがってどちらの変更も、すでにデータを持つテーブルに対して行われる。1つ目の要求は、系統(リネージ)を記録する列である。各行に、どの1時間単位のロードがその行を書き込んだかを記録し、問題のあるロードをその行まで追跡できるようにする。テーブルにはそのような列が必要であるが、すでに保持している行は、その列が存在する前に書き込まれたものである。2つ目は名前の修正である。ダッシュボードではタイトルの列を article_title と呼んでいるが、テーブルではダンプが使う名前の page_title と呼んでいる。どちらの変更でも問いは同じである。変更より前に書き込まれたファイルはどうなるのか。

スキーマ変更は、原理上はメタデータの変更である。データファイルはそのままの場所にあり、フォーマットは追加または名前変更された列をメタデータに記録する。古いファイルがその後も正しく読めるかどうかは、フォーマットがファイル内の列をどのように見つけるかによって決まる。列を名前で見つけるフォーマットは、名前が変わると問題が生じる。変わらないものを手がかりに列を見つけるフォーマットでは、その問題は生じない。この章では、各フォーマットがどちらに当たるのか、それぞれの変更にどれだけのコストがかかるのか、そして固定したバージョンの Delta Lake ライブラリではどの変更ができないのかを示す。

列はIDで追跡される

最終変更:版2026.11.10

データファイルには一部の列の値が格納されており、テーブルのスキーマが、各値がどの列に属するかを定める。両者を対応づける単純な方法は名前による照合である。この方法は、名前が変更されるまでは問題なく機能する。変更後は、スキーマが指す名前の列を古いファイルが持たなくなり、リーダーは古い値がどの列に属するのかを推測せざるを得なくなる。

名前で照合するリーダーが、古い名前の列を見つけられなかった場合、選べる手段は二つあり、どちらも望ましくない。クエリを失敗させるか、何も告げずにその列を 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 プロトコルは、ファイル内の名前とリーダーに見える名前を切り離す、任意の列マッピング機能を定義している。各列にはファイルに保存される物理名が与えられ、リーダーが使う名前は、ファイルに触れずに変更できる表示名である。プロトコルは、列マッピングが「すべてのデータを書き直すことなく、列の名前変更と削除」を支えると述べている [2]。特定のライブラリのリリースが実際にそうなるかどうかは別の問題である。Delta Lake の節が、固定したリリースについてこれに答える。

実践ルール: Iceberg の列は、リーダーがフィールド ID で照合するため、名前変更を経てもデータを保つと考えてよい。Delta Lake の列は、列マッピングが有効でない限り、名前で照合されると考えるべきである。名前変更に頼る前に、テーブルのコピーで試し、その後で列名を読み戻して確認すること。

この部分はまだ翻訳されていないため、英語で表示している。

Add load_batch after three hours

最終変更:版2026.11.10

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.

add-column-to-existing-files.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 合格
"""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.Read the four "with load_batch null" lines, which show the rows before the add and the rows after it in each format."""import pyarrow as pafrom deltalake import DeltaTable, write_deltalakefrom deltalake.schema import Field, PrimitiveTypefrom pyiceberg.types import IntegerTypefrom lib.lakehouse import ICEBERG_ID, delta_file_count, iceberg_file_count, new_warehouse, read_cut_hour, read_delta, split_nullsdef stamp(rows, hour):    """Return one hourly load with load_batch set to that load's hour number."""    # int32 is the width IntegerType stores, so the Arrow column matches the Iceberg field    return rows.append_column("load_batch", pa.array([hour] * rows.num_rows, type=pa.int32()))with new_warehouse() as wh:    # the schema comes from hour 0, which has no load_batch yet    table = wh.catalog.create_table(ICEBERG_ID, schema=read_cut_hour(0).schema)    for hour in range(3):  # hours 00 to 02, each one commit, all written before the add        table.append(read_cut_hour(hour))    print(f"iceberg snapshots before the add: {len(table.snapshots())}")    print(f"iceberg data files before the add: {iceberg_file_count(table)}")    with table.update_schema() as update:        update.add_column("load_batch", IntegerType())    print(f"iceberg snapshots after the add: {len(table.snapshots())}")    print(f"iceberg data files after the add: {iceberg_file_count(table)}")    for hour in range(3, 6):  # hours 03 to 05, written after the add        table.append(stamp(read_cut_hour(hour), hour))    iceberg_rows = table.scan().to_arrow()    print(f"iceberg rows in the table: {iceberg_rows.num_rows}")    # the split is at 3, the first hour written after the add    split_nulls(wh.con, iceberg_rows, "iceberg", "load_batch", 3, sides=("written before the add", "written after the add"))    path = f"{wh.root}/delta/pageviews_hourly"    for hour in range(3):  # hours 00 to 02, appended as three versions before the add        write_deltalake(path, read_cut_hour(hour), mode="append")    print(f"delta version before the add: {DeltaTable(path).version()}")    print(f"delta data files before the add: {delta_file_count(DeltaTable(path))}")    DeltaTable(path).alter.add_columns([Field("load_batch", PrimitiveType("integer"))])    print(f"delta version after the add: {DeltaTable(path).version()}")    print(f"delta data files after the add: {delta_file_count(DeltaTable(path))}")    for hour in range(3, 6):  # hours 03 to 05, written after the add        write_deltalake(path, stamp(read_cut_hour(hour), hour), mode="append")    delta_rows = read_delta(path)    print(f"delta rows in the table: {delta_rows.num_rows}")    # the same split as the Iceberg half, at 3    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.py
iceberg 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

最終変更:版2026.11.7

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

最終変更:版2026.11.7

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.

rename-by-id.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 合格
"""Renames a column in an Iceberg table and reads the old files back under the new name.Read the field ID lines, the data file lines and the non-null count, which show what the rename kept."""import pyarrow as pafrom lib.lakehouse import (    ICEBERG_ID,    iceberg_file_count,    new_warehouse,    read_cut_hour,    scan_arrow,    snapshot_labels,    sql_rows,)with new_warehouse() as wh:    table = wh.catalog.create_table(ICEBERG_ID, schema=read_cut_hour(0).schema)    for hour in range(3):        table.append(read_cut_hour(hour))    before = table.schema().find_field("page_title").field_id  # the ID is what the reader matches on, not the name    print(f"page_title field ID before the rename: {before}")    print(f"data files before the rename: {iceberg_file_count(table)}")    with table.update_schema() as update:        update.rename_column("page_title", "article_title")    print(f"article_title field ID after the rename: {table.schema().find_field('article_title').field_id}")    print(f"data files after the rename: {iceberg_file_count(table)}")    rows = scan_arrow(table)    print(f"rows: {rows.num_rows}")    # count(column) leaves out nulls, so this counts the rows that have a value under the new name    count = sql_rows(wh.con, "SELECT count(article_title) FROM t", t=rows)[0][0]    print(f"article_title not null: {count}")    labels = snapshot_labels([snapshot.snapshot_id for snapshot in table.snapshots()])    first = table.snapshots()[0].snapshot_id  # the first snapshot, written before the rename    print(f"{labels[first]} columns: {', '.join(scan_arrow(table, snapshot_id=first).column_names)}")
出力python rename-by-id.py
page_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 には列名変更の呼び出しがない

最終変更:版2026.11.7

同じ列名変更を 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"})
delta-rename-trap.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 合格
"""Calls set_column_metadata with a name key on a Delta Lake table with column mapping on, then reads the names back and queriesunder the new name. The columns read back line and the binder error are the lines to read."""from deltalake import DeltaTable, write_deltalakefrom lib.lakehouse import new_warehouse, read_cut_hour, read_delta, safe_error, sql_rowswith new_warehouse() as wh:    path = f"{wh.root}/delta/pageviews_hourly"    # column mapping on: the protocol's route to a rename, which this release does not offer as a call    write_deltalake(path, read_cut_hour(0),                    configuration={"delta.columnMapping.mode": "name"})    print(f"version before the rename: {DeltaTable(path).version()}")    # the call raises nothing and writes a commit, so the names read back below are the only check    DeltaTable(path).alter.set_column_metadata("page_title", {"name": "article_title"})    print("set_column_metadata returned")    table = DeltaTable(path)    print(f"version after the rename: {table.version()}")    page = next(field for field in table.schema().fields if field.name == "page_title")    # the name key the call wrote into the field's metadata, which the reader does not use for the column name    print(f"name in page_title metadata after the rename: {page.metadata['name']}")    print(f"columns read back: {', '.join(read_delta(path).column_names)}")    try:        sql_rows(wh.con, "SELECT article_title FROM t", t=read_delta(path))    except Exception as exc:        print(safe_error(exc, wh))
出力python delta-rename-trap.py
version 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 には、それを実行する呼び出しがない。

delta-rename-by-rewrite.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 合格
"""Renames a Delta Lake column by overwriting the table with renamed data and schema, then reads the version before the rewrite back.Compare the two columns lines: the version before the rewrite, and the version the rewrite makes."""from deltalake import DeltaTable, write_deltalakefrom lib.lakehouse import new_warehouse, read_cut_hour, read_deltawith new_warehouse() as wh:    path = f"{wh.root}/delta/pageviews_hourly"    for hour in range(3):        write_deltalake(path, read_cut_hour(hour), mode="append")    print(f"data files before the rewrite: {len(DeltaTable(path).file_uris())}")    before = DeltaTable(path).version()  # read first, so the old version can be read back after the rewrite    print(f"version before the rewrite: {before}")    print(f"columns before the rewrite: {', '.join(read_delta(path, version=before).column_names)}")    # the new names, in the table's column order: only the third one changes    renamed = read_delta(path).rename_columns(["hour_utc", "domain_code", "article_title", "views", "response_bytes"])    # replace the data and the schema together, in one commit, so readers of the new version see both at once    write_deltalake(path, renamed, mode="overwrite", schema_mode="overwrite")    print(f"data files after the rewrite: {len(DeltaTable(path).file_uris())}")    after = DeltaTable(path).version()    print(f"version after the rewrite: {after}")    print(f"columns after the rewrite: {', '.join(read_delta(path).column_names)}")    print(f"rows after the rewrite: {read_delta(path).num_rows}")
出力python delta-rename-by-rewrite.py
data 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" で書き戻す。この 2 つは、データとスキーマをともに置き換える。テーブルのデータファイルは、書き直しの前には 3 個であり、書き直しの後には 1 個である。書き直しによってバージョン 3 が作られ、そこでは列名は article_title となり、行数は 1499 行である。

書き直しには、テーブルの大きさに応じたコストがかかる。すべての行を読み込み、再び書き込むからである。ここでのテーブルは小さいが、数百万行を持つ本番のテーブルでも行ごとのコストは同じである。したがって、チームは書き直しを独立したジョブとして計画すべきである。書き直し前のバージョン 2 は、依然として page_title と読める。これは例でも出力される。つまり、書き直しが変えるのは現在のバージョンだけであり、古いバージョンは書き込まれたときの名前を保つ。実行する前に、その列を名前で参照しているリーダーを一覧にする。切り替えは 1 回のコミットで行われるので、現在のバージョンを読むすべてのリーダーは同時に移行する。一方、古いバージョンに固定されたジョブは古い名前を保つ。そのようなジョブはリーダーとともに移行し、移行が済むまで、書き直しが置き換えたバージョン番号を記録しておく。

実践ルール: Delta Lake の列名はテーブルの作成時に決める。このバージョンでは、後からの列名変更はテーブル全体の書き直しになるからである。列名の変更に set_column_metadata を使ってはならない。これはバージョンとメタデータを変えるが、列は元の名前のままである。スキーマを変更した後は、落とし穴の例と同様に、ライブラリ経由で列名を読み戻し、クエリがそれらに依存する前に確認する。

本番環境で起こる問題

最終変更:版2026.11.7

スキーマ変更は、明示的なエラーで失敗するよりも、気づかれないまま失敗することの方が多い。以下の各失敗には、監視できる兆候がある。

最初は、何も起こらない列名変更である。set_column_metadata の呼び出しは成功し、履歴にはコミットが現れるが、列は古い名前のままである。この失敗は、article_title を使う最初のクエリで表面化する。DuckDB のクエリが BinderException で失敗するのである。そのようなクエリを実行する定期ジョブは、変更後の最初の実行で失敗するため、エラーは原因の近くで発生する。

次は、履歴に残る古い名前である。書き換えによって現在のバージョンには article_title という名前が付くが、以前のバージョンは書き込まれた当時の名前を保持する。書き換えの例がそれを示しており、バージョン 2 は依然として page_title と読み出される。Iceberg のスナップショットでも同じことが起こる。最初のスナップショットは今でも page_title を報告する。以前のバージョンやスナップショットを article_title で読み出すクエリは、そのような列を見つけられない。バージョン番号やスナップショット番号による読み出しには、その時点で有効だった名前が必要である。したがって、バージョン番号を固定するジョブは、スキーマも固定することになる。

3 つ目は、欠損データのように見える null である。追加された列は、追加前に書き込まれたすべての行で null と読み出される。その列の null の件数は正しい値であり、追加の例が示す前後のパターンから外れる場合に限って障害といえる。追加の例と同様に null を時間ごとに数え、パターンに合わない行があれば調査すること。

最後は、スナップショット一覧に現れないスキーマ変更である。Iceberg での列の追加と列名の変更は、いずれもスナップショット数を変えず、ファイル数も変えなかった。スナップショット数を数えてスキーマ変更を検出するツールは、これらを見逃す。何が変わったかを知る必要があるときは、スナップショット数ではなく、スキーマそのものをフィールド ID と名前で比較する。

実践ルール: スキーマを変更したら、下流のクエリを実行する前に次の 3 つを行う。ライブラリ経由で列名を読み戻すこと。追加した各列の null を時間ごとに数えること(1 時間が 1 回の書き込みに当たる)。そして、スナップショット数ではなくスキーマを、変更が意図した内容と比較することである。

この章での判断

この節の表は、この章で扱った変更について、二つのフォーマットを並べて示したものである。各セルの内容は、この章のいずれかの例に基づいている。

変更 Iceberg Delta Lake
列の追加 可能である。既存の行は null として読み取られ、スナップショット数は 3 のまま変わらない 可能である。既存の行は null として読み取られ、バージョンは一つ上がる
列名の変更 可能である。フィールド ID は変わらず、データファイルは書き換えられない 名前を変更する呼び出しは存在しない。set_column_metadata はコミットされるが名前は変わらず、名前が変わるのは書き換えを行った場合である
古いスナップショットまたはバージョンの読み取り 古い名前が表示される 古い名前が表示される
  • 両方のフォーマットで、すでにデータを保持しているテーブルに列を追加する。既存の行はその列を null として読み取る。追加の例には、このパターンを裏付ける時間帯別の件数が示されている。この方法は古いファイルを書き込まないため、テーブルをコピーする方法よりも、この方法を推奨する。
  • Iceberg の列名は rename_column で変更し、変更の前後でフィールド ID が同じであることを確認する。コストがテーブルの大きさに左右されないため、名前が誤っている Iceberg の列には、この方法を推奨する。
  • Delta Lake の列名は、テーブルを作成する時点で決める。固定したリリースでは、Delta Lake での名前の変更はテーブル全体の書き換えになる。名前が誤っていた場合に見込むべきコストは、この書き換えである。
  • Delta Lake の列名を set_column_metadata で変更してはならない。この呼び出しは成功するが、名前には何も変更を加えない。
  • 固定したリリースでは、名前の変更をカラムマッピングに頼ってはならない。ライブラリには名前の変更を実行する呼び出しがないため、マッピングを有効にしても名前の変更は得られない。
  • スキーマを変更するたびに、両方のフォーマットで列名を読み戻し、クエリがそれらの列名に依存する前に行う。

この部分はまだ翻訳されていないため、英語で表示している。

Sources

最終変更:版2026.11.7
  1. 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.
  2. 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."
  3. deltalake 1.6.6, the methods of DeltaTable.alter in the installed package: add_columns, add_constraint, add_feature, drop_column_not_null, drop_constraint, set_column_metadata, set_table_description, set_table_name and set_table_properties. None renames a column. To list them, run dir(DeltaTable(path).alter).

この版における本章

第2026.11.10版2026年11月20日時点で例が通過この章の4 例件のうち4件が合格

英語版の書籍(版2026.11.10)から翻訳した。

この節を引用する

形式

いずれの形式も、本訳書が従う英語版の書籍を出典として示す。

いずれの形式もこの版を明示している。そのリンクは現行版を開き、節の見出しには本文が最後に変更された日付が示される。アクセス日と取得日は、これを開いた日である。

このページの内容

全10章中の第3章: ファイルを書き換えずに列を追加・名前変更する

  1. 列はIDで追跡される
  2. Add load_batch after three hours
  3. Old files read as null
  4. Rename a column by its ID without rewriting files
  5. この版の Delta Lake には列名変更の呼び出しがない
  6. 本番環境で起こる問題
  7. この章での判断
  8. Sources

ページの先頭に戻るすべての章