テーブルをフォーマット間で移し、コピーを検証する
読了まで約42 分分、7 節 節の 4 例 例。
この章を終えると、あるテーブルを別のフォーマットへコピーし、コピーが同じ行を保持していることを確認できるようになる。コピーが残していかないものを挙げ、どの損失を受け入れ、どの損失で移行を止めるべきかを判断することもできるようになる。
アナリストは、pageviews テーブルを DuckLake に置き、カタログファイルを DuckDB 経由でクエリしたいと考えている。pageviews テーブル wiki.pageviews_hourly は、第1章から Apache Iceberg に置かれている。別のチームは自分たちのテーブルを Delta Lake で管理しており、同じ行を Iceberg に置きたいと考えている。どちらの移行でも、移行元はそのまま残し、移行は新しいテーブルへのコピーとして行う。コピーは一度きりの書き込みであり、作業の大半はその前後の検証にある。この章では二つのコピーを実行し、そのうえで、気づかれにくい損失を検出する検証を加える。
この章の例では、pyiceberg には 0.12.0、deltalake には 1.6.6、DuckLake も実行する DuckDB には 2.0.0 を固定している。各コピーの例は、pageviews の同じ3時間分の切り出しから、一時的なウェアハウス内に小さな移行元を自前で作る。その行数は 1499 行である。
コピーが保持するものと失うもの
コピーは、ある時点における1つのテーブルの行を読み取り、別のテーブルに別の形式で書き込む。コピー先の各ライブラリは、それぞれ独自のデータファイル、独自のメタデータ、独自の履歴を書き出す。移動後に残るのは、双方が表現できるもの、すなわち行と、双方がサポートする型の列である。それ以外はコピー元に残るか、コピー先で手作業により設定し直す必要がある。
失われるものは表にすると見分けやすい。各行は、テーブルの構成要素、コピーによるその扱い、そして本章で結果を示す箇所を表している。
| テーブルの構成要素 | コピー後 | 本章で示す箇所 |
|---|---|---|
| 行とその値 | 保持される | ダイジェストによる検証 |
| 列名と型 | 双方の形式にその型がある場合は保持される | Delta Lake の節 |
| コミット履歴 | 失われる。コピーは独自の履歴を新たに開始する | コピーを扱う両方の節 |
| パーティション仕様 | コピー先で設定しない限り失われる | DuckLake の節 |
| マイクロ秒未満のタイムスタンプ | 形式により異なる。拒否される、切り詰められる、または保持される | タイムスタンプの節 |
履歴の喪失は、読者が見落としやすいものである。Iceberg は変更をスナップショットとして記録し、Delta Lake は各コミットをバージョンとして記録する。スナップショットとタイムトラベルの章では、読み手がそれらをどう使うかを示した。コピーはコピー先で新しい履歴を開始するため、コピー先の履歴はコピーの時点から始まる。コピー元は、コピー元を残しておく限り自身の履歴を保持する。コピーのどこにも、コピー元の履歴を参照する情報はない。
コピーは登録とも異なる。登録されたメタデータファイルは、ファイルには手を加えずにテーブルを2つ目のカタログから見えるようにするので、両方のカタログが同じデータを読む。コピーは新しいファイルを書き出し、コピー元には手を加えない。そのため2つのテーブルがそれぞれ書き込みを受け付けることになり、互いにずれていく可能性がある。コピー先が自身のファイルと履歴を所有しなければならない場合はコピーを選ぶ。2つのカタログが1組のファイルを共有すべき場合は登録を選び、共有するファイルを動かせないことを受け入れる。
行が保持されるのは、コピーが移動するのがファイルではなく値だからである。コピーはデータファイルを移動しない。一方のテーブルから値を読み出し、他方のために新しい Parquet ファイルを書き出す。コピー元とそのコピーでファイル名やファイル数が異なるのはこのためであり、ファイル名やファイル数の比較ではコピーを検証できない理由でもある。検証では行を比較しなければならない。
実践ルール: コピーの前に、コピー先が保持しないものをコピー元から洗い出して列挙する。履歴、パーティション仕様、そしてコピー先が格納できる精度より細かい値である。各項目について、損失を受け入れる、コピー先で手作業により設定する、移行を中止する、のいずれかを1つ決める。手順書にはすべての決定を明記する。
この部分はまだ翻訳されていないため、英語で表示している。
Copy the pageviews table into DuckLake
The copy reads the Iceberg table with scan_arrow, then gives those rows to DuckLake. DuckLake creates an empty table with their columns, sets the partition spec on it, and then inserts the rows with INSERT ... SELECT. Arrow is the bridge because each side keeps its own library. pyiceberg reads the source, and DuckDB writes the DuckLake table through its own ducklake extension. Neither side reads the other's files. The catalog chapter showed how the DuckLake catalog is attached, and the helper in this chapter attaches it the same way.
The source is partitioned by the hour of hour_utc, which is the layout that moving from daily to hourly partitions arrives at. Here pyiceberg builds that source with the hourly spec, then appends three hours, one commit each:
1"""Copy an Iceberg table into DuckLake through Arrow, then print what the copy kept of the layout and the history.23The point rests on the copy partition transforms and copy files per partition lines, which show whether the4layout arrived with the rows, and on the copy snapshot lines, which show the history starting at the copy."""56from pyiceberg.partitioning import PartitionField, PartitionSpec7from pyiceberg.transforms import HourTransform89from lib.lakehouse import (copy_to_ducklake, create_iceberg_table, ducklake_files_by_partition, ducklake_partition_transforms,10 new_warehouse, read_cut_hour, safe_error, scan_arrow, TABLE)111213def main():14 try:15 with new_warehouse() as wh:16 # source_id 1 is the field ID of hour_utc in the table lib creates17 spec = PartitionSpec(PartitionField(source_id=1, field_id=1000, transform=HourTransform(), name="ts_hour"))18 table = create_iceberg_table(wh, partition_spec=spec)19 for hour in range(3):20 table.append(read_cut_hour(hour))21 arrow = scan_arrow(table)22 print(f"source rows: {arrow.num_rows}")23 print(f"source snapshots: {len(table.metadata.snapshots)}")24 for field in table.spec().fields:25 print(f"source partition field: {field.name}")2627 # the helper creates the copy empty, sets this spec with ALTER, and only then inserts the rows28 target = copy_to_ducklake(wh, arrow, partition_by="hour(hour_utc)")29 print(f"copy rows: {wh.con.execute(f'SELECT count(*) FROM {target}').fetchall()[0][0]}")30 # current=True keeps only the spec still in force; an earlier spec would otherwise be listed too31 print(f"copy partition transforms: {ducklake_partition_transforms(wh.con, table=TABLE, current=True)}")32 # one (partition value, files, rows) tuple per partition, in value order33 files = ducklake_files_by_partition(wh.con, "lake", TABLE)34 print(f"copy partition values: {[value for value, _, _ in files]}")35 print(f"copy files per partition: {[count for _, count, _ in files]}")36 print(f"copy rows per partition: {[int(rows) for _, _, rows in files]}")37 changes = wh.con.execute("SELECT changes FROM ducklake_snapshots('lake') ORDER BY snapshot_id").fetchall()38 # labels start at 1, so label N is the snapshot whose snapshot_id is N-139 for number, (change,) in enumerate(changes, start=1):40 print(f"copy snapshot {number}: {', '.join(sorted(change))}")41 except Exception as exc:42 print(safe_error(exc))43 raise SystemExit(1)444546if __name__ == "__main__":47 main()
python iceberg-to-ducklake-copy.pysource rows: 1499
source snapshots: 3
source partition field: ts_hour
copy rows: 1499
copy partition transforms: ['hour']
copy partition values: ['0', '1', '2']
copy files per partition: [1, 1, 1]
copy rows per partition: [499, 500, 500]
copy snapshot 1: schemas_created
copy snapshot 2: schemas_created
copy snapshot 3: tables_created
copy snapshot 4: tables_altered
copy snapshot 5: tables_inserted_into
The helper scan_arrow reads the source at its current snapshot and returns every row of that snapshot as one Arrow table. The copy therefore holds the rows of one moment, the last commit that the scan saw. Writers that commit after the scan are not in the copy, and nothing in the copy tells you so. Commits that land after a copy's scan and never reach the copy are the cutover problem, which the production section returns to.
Two questions decide the copy: did the rows and layout arrive, and what history came with them? The output answers both.
The source comes first. It prints the row count, the number of snapshots and the partition fields. The source has 3 snapshots, one for each append, and one partition field, ts_hour, an hour transform of hour_utc.
The copy's row count comes next, and it is 1499. The row count is the same as the source's. It is a useful first check, but the digest section below explains why it is not enough on its own.
A copy can lose its layout without any error, so the order of the statements matters. The helper creates the copy as an empty table, runs ALTER TABLE ... SET PARTITIONED BY (hour(hour_utc)) on it, and only then inserts the rows. The DuckLake partitioning docs say the partition keys "only affect new data written to the table", so an ALTER after the rows are in place would leave them unpartitioned. The helper keeps only the spec still in force, and it lists one transform, hour. The list says what the copy was given. The files say what it holds: the copy writes [1, 1, 1] files, and the rows are divided between them as [499, 500, 500]. A copy made in one statement carries no partition spec, so its list is empty and its rows sit in unpartitioned files. The rows are all there either way, so the check has to look at the layout.
The partition list reads the catalog table ducklake_partition_column, as the DuckLake specification defines it, through the attached metadata database. No public function returns it at this pin.
Last, the snapshot list shows the copy's history. Each line gives a snapshot's number and the changes it made. The labels count every snapshot DuckLake records, setup included, as in chapter 2. The first two snapshots create the default schema and the wiki schema. The third creates the empty table, the fourth sets its partition spec, and the fifth writes the rows into the table that is already partitioned. The three hourly appends from the source do not appear. The copy's history starts at its own creation, so time travel on the copy reaches back only that far. To read the source as it was after the first hour, you still need the Iceberg table.
The attach helper also sets DATA_INLINING_ROW_LIMIT to 0, so the copied rows are written as Parquet files, and the counts above are of those files.
Working rule: Copy through Arrow with the target's own writer. Create the target empty, set its partition spec with an ALTER, and only then insert the rows. Print the target's partition list and its files per partition. Read the copy's snapshots as the copy's own history, and keep the source until the checks in the last two sections have passed.
この部分はまだ翻訳されていないため、英語で表示している。
Copy the Delta table into a pyiceberg table
The Delta source is built the way a team's pipeline would build it: three appends with deltalake, one per hour. The three appends are versions 0, 1 and 2. The copy reads the current rows with read_delta and appends them to an Iceberg table made with the target schema:
1"""Copy a Delta Lake table into Iceberg through Arrow, then compare the copy with its source.23The point rests on the delta versions and iceberg snapshots lines, which show several commits becoming one,4and on the two column listings, which show the names carried across."""56from deltalake import DeltaTable78from lib.lakehouse import (create_iceberg_table, new_warehouse, print_schema, read_delta, safe_error, scan_arrow,9 write_delta_hours)101112def main():13 try:14 with new_warehouse() as wh:15 path = write_delta_hours(wh.root, range(3))16 source = read_delta(path)17 # Delta numbers its versions from 0, so the count is the last version plus one18 print(f"delta versions: {DeltaTable(path).version() + 1}")19 print(f"delta rows: {source.num_rows}")20 print("delta columns (name, type, nullability):")21 print_schema(source.schema)2223 table = create_iceberg_table(wh)24 table.append(source)25 print(f"iceberg snapshots: {len(table.metadata.snapshots)}")26 print(f"iceberg rows: {scan_arrow(table).num_rows}")27 print("iceberg columns (name, type, requirement):")28 # sorted by name, so the two listings line up row for row29 for field in sorted(table.schema().fields, key=lambda field: field.name):30 # Iceberg calls a nullable field optional, so the listing says optional where Delta says nullable31 requirement = "required" if field.required else "optional"32 print(f"{field.name}\t{field.field_type}\t{requirement}")33 except Exception as exc:34 print(safe_error(exc))35 raise SystemExit(1)363738if __name__ == "__main__":39 main()
python delta-to-iceberg-copy.pydelta versions: 3
delta rows: 1499
delta columns (name, type, nullability):
domain_code string nullable
hour_utc timestamp[us] nullable
page_title string nullable
response_bytes int64 nullable
views int64 nullable
iceberg snapshots: 1
iceberg rows: 1499
iceberg columns (name, type, requirement):
domain_code string optional
hour_utc timestamp optional
page_title string optional
response_bytes long optional
views long optional
The copy has as many rows as the source but leaves its history behind. The Delta table has 3 versions and 1499 rows. The Iceberg table is built from one append of all of them, so it has 1 snapshot, the start of its own history, like the DuckLake copy. Its row count, 1499, is the same as the source's.
The rest of the output lists both schemas, one column per line. Read them side by side:
| Column | Delta Lake (Arrow type) | Iceberg type |
|---|---|---|
domain_code |
string |
string |
hour_utc |
timestamp[us] |
timestamp |
page_title |
string |
string |
response_bytes |
int64 |
long |
views |
int64 |
long |
Names come across unchanged, because the copy takes them from the Arrow schema. The types map one to one. The only spelling change is int64 in Arrow, which Iceberg calls long. Both sides use microseconds for hour_utc, and the timestamp check below explains what happens when they do not.
pyiceberg is strict about names. It checks the Arrow schema against the table's schema before it writes. It stops with a mismatch error when a column name differs, or when a type cannot be promoted to the table's type. It accepts a type it can promote, such as int to long. That check is in the pinned library's _check_pyarrow_schema_compatible function in pyiceberg/io/pyarrow.py. The Delta table also cannot rename a column at this pin, as the rename section of the schema chapter showed. If the two sides disagree on a name, you change the target, not the source. pyiceberg matches the Arrow columns to the table by name, so the target's field IDs come from the schema you write. You write the target schema yourself, rather than letting the first batch decide it.
Working rule: Write the target schema yourself, with the types you want, and print both schemas after the copy, as the example does. Accept a near-equal type such as int64 to long only after you have checked it in the output. Do not accept a name that differs.
コピーの前にタイムスタンプの精度を確認する
タイムスタンプは、フォーマット間で扱いが食い違う箇所であり、その食い違いが通知なく起きることもある。Iceberg 仕様はナノ秒タイムスタンプをバージョン 3 の型として定義しているため、バージョン 2 のテーブルにはナノ秒用の型がない(Iceberg 仕様、バージョン 3 の節)。この例のテーブルは、既定のバージョン 2 である。固定したバージョンの pyiceberg はバージョン 3 への書き込みを拒否するので、ナノ秒の値を保持できるのは Iceberg 以外のフォーマットだけである。この例では、マイクロ秒未満でのみ異なる 2 つの値、すなわち 1000000500 ナノ秒と 1000000999 ナノ秒を、各フォーマットに書き込む。
1"""Write two timestamps that differ only below a microsecond to Iceberg, Delta Lake and DuckLake, and show what each kept.23The point rests on the Iceberg error line and on the Delta and DuckLake read-back lines."""45import pyarrow as pa6from deltalake import write_deltalake7from pyiceberg.schema import Schema8from pyiceberg.types import NestedField, TimestampType910from lib.lakehouse import copy_to_ducklake, new_warehouse, NAMESPACE, read_delta, safe_error, sql_rows1112# nanoseconds since 1970: one second plus 500 and 999 nanoseconds, so the two values differ below a microsecond13NANOSECONDS = pa.table({"hour_utc": pa.array([1000000500, 1000000999], pa.timestamp("ns"))})141516def main():17 try:18 with new_warehouse() as wh:19 # cast to int64 gives the integer behind each timestamp, so distinct values are counted exactly20 print(f"written distinct values: {len(set(NANOSECONDS['hour_utc'].cast(pa.int64()).to_pylist()))}")21 # TimestampType stores microseconds; a version 2 table has no nanosecond type to declare instead22 table = wh.catalog.create_table(23 f"{NAMESPACE}.precision",24 schema=Schema(NestedField(1, "hour_utc", TimestampType(), required=False)),25 )26 try:27 # this append raises, because the table cannot hold nanoseconds; the except prints the error28 table.append(NANOSECONDS)29 except Exception as exc:30 print(f"iceberg append: {safe_error(exc, wh)}")3132 path = str(wh.root / "precision")33 write_deltalake(path, NANOSECONDS, mode="overwrite")34 # the cast reads the count in the column's unit, which Delta wrote as microseconds, so 1000000 is one second35 kept = read_delta(path)["hour_utc"].cast(pa.int64()).to_pylist()36 print(f"delta read back as microseconds: {kept}")37 print(f"delta distinct values read back: {len(set(kept))}")3839 target = copy_to_ducklake(wh, NANOSECONDS)40 # epoch_ns returns nanoseconds since 1970, so a value cut to microseconds would end in three zeros41 rows = sql_rows(wh.con, f"SELECT epoch_ns(hour_utc) FROM {target}")42 print(f"ducklake epoch nanoseconds read back: {[row[0] for row in rows]}")43 except Exception as exc:44 print(safe_error(exc))45 raise SystemExit(1)464748if __name__ == "__main__":49 main()
python timestamp-precision-check.pywritten distinct values: 2
iceberg append: UnsupportedPyArrowTypeException: Column 'hour_utc' has an unsupported type: timestamp[ns]
delta read back as microseconds: [1000000, 1000000]
delta distinct values read back: 1
ducklake epoch nanoseconds read back: [1000000500, 1000000999]
最初の行は入力であり、2 つの異なる値である。続いて、各フォーマットがそれぞれ異なる形で結果を返す。
Iceberg への追記は失敗する。エラーは UnsupportedPyArrowTypeException: Column 'hour_utc' has an unsupported type: timestamp[ns] である。このエラーは列と型を示すため、3 つのケースのうち失敗の様子が最も明確であり、既定では何も黙って変更されない。pyiceberg のエラーは、書き込み時にナノ秒をマイクロ秒へ切り下げる設定 PYICEBERG_DOWNCAST_NS_TIMESTAMP_TO_US_ON_WRITE を示している。この設定を有効にすると、同じ追記が成功し、値は整数のマイクロ秒として読み戻される。このとき出るのは記録された警告だけである。これは Delta が行う切り捨てと同じであるから、値を切り捨てると決めたジョブにだけ設定し、すべての書き込み側が共有する環境には設定してはならない。
Delta への書き込みは成功し、読み戻すと [1000000, 1000000] となる。両方の値が整数のマイクロ秒に切り捨てられ、2 つの異なる値が 1 つになった。書き込みではエラーが出ず、行数も同じである。値を確認して初めて損失がわかる。重複を除いた個数は 2 から 1 に減る。
DuckLake はナノ秒を保持する。そのテーブルは 2 つの値を書き込まれたとおりに格納し、この例では [1000000500, 1000000999] として読み戻される。
pageviews テーブルは時間単位を記録するので、このケースでは問題に行き当たらない。生のリクエストログのテーブルでは問題になる。そのタイムスタンプはマイクロ秒より細かく刻むクロックに由来し、コピーではそれらの桁に対する規則を選ばなければならない。答えは値の中にしか現れないので、最初のコピーの前に、すべてのタイムスタンプ列についてこの問いを立てる。この章のコピーはマイクロ秒のタイムスタンプを使っており、3 つのフォーマットすべてがそれを保持するため、コピー結果は一致する。実際のテーブルは、ソース由来のマイクロ秒未満の値を持つことがあり、コピーでは最初の書き込みの前に、その値をどう扱うかを決めなければならない。
実践ルール: 最初のコピーの前に、マイクロ秒未満の値を使ってタイムスタンプの精度を確認する。規則はあらかじめ選んでおく。列をマイクロ秒にキャストしてキャストで変わる値を数える、コピーを拒否する、ナノ秒を保持するフォーマットに書き込む、のいずれかである。選択を書き込みライブラリに任せてはならない。黙って切り捨てられると、対処の手がかりとなるエラーが出ないからである。
ソート済みダイジェストで各コピーを検査する
行数が一致しても、値が一致することの証明にはならない。コピーは行数を保ったまま1つの値だけを変えてしまうことがあり、行数からはそれが分からない。ダイジェストなら分かる。テーブルのダイジェストとは、ソートした行のハッシュである。digest_rows は行をソートし、各行を1行のテキストとして書き出し、その結果をハッシュする。ソートによって、ダイジェストは行が返ってくる順序に依存しなくなる。したがって、同じ行を持つ2つのコピーは、各フォーマットがどの順序で行を返しても同じダイジェストになる。digest_rows を両方のコピーに対して実行し、さらに閲覧数を1つだけ意図的に変更したコピーに対しても実行する。
1"""Check each copy against its source with a sorted digest, and show that one changed value fails it.23The point rests on the two iceberg to ducklake digest lines: the copy matches its source, and a copy with one4changed count does not."""56from lib.lakehouse import (copy_to_ducklake, create_iceberg_table, digest_rows, new_warehouse, read_cut_hour,7 read_delta, safe_error, scan_arrow, sql_rows, write_delta_hours)8910def same(source, copy):11 return digest_rows(source) == digest_rows(copy)121314def check_iceberg_to_ducklake():15 with new_warehouse() as wh:16 table = create_iceberg_table(wh)17 for hour in range(3):18 table.append(read_cut_hour(hour))19 target = copy_to_ducklake(wh, scan_arrow(table))20 source_rows = sql_rows(wh.con, "SELECT * FROM source", source=scan_arrow(table))21 copy_rows = wh.con.execute(f"SELECT * FROM {target}").fetchall()22 first = copy_rows[0]23 # the copy's columns are hour_utc, domain_code, page_title, views, response_bytes, so index 3 is views24 changed = [(*first[:3], first[3] + 1, first[4]), *copy_rows[1:]]25 print(f"iceberg to ducklake rows: {len(source_rows)} and {len(copy_rows)}")26 matches = same(source_rows, copy_rows)27 # printed before the assert, so a failing run still shows the word28 print(f"iceberg to ducklake digests: {'match' if matches else 'differ'}")29 assert matches30 still_matches = same(source_rows, changed)31 print(f"iceberg to ducklake with one changed view count digests: {'match' if still_matches else 'differ'}")32 # one changed count must change the digest33 assert not still_matches343536def check_delta_to_iceberg():37 with new_warehouse() as wh:38 path = write_delta_hours(wh.root, range(3))39 table = create_iceberg_table(wh)40 table.append(read_delta(path))41 source_rows = sql_rows(wh.con, "SELECT * FROM source", source=read_delta(path))42 copy_rows = sql_rows(wh.con, "SELECT * FROM copy", copy=scan_arrow(table))43 print(f"delta to iceberg rows: {len(source_rows)} and {len(copy_rows)}")44 assert same(source_rows, copy_rows)454647def main():48 try:49 check_iceberg_to_ducklake()50 check_delta_to_iceberg()51 except Exception as exc:52 print(safe_error(exc))53 raise SystemExit(1)545556if __name__ == "__main__":57 main()
python verify-copies-by-digest.pyiceberg to ducklake rows: 1499 and 1499
iceberg to ducklake digests: match
iceberg to ducklake with one changed view count digests: differ
delta to iceberg rows: 1499 and 1499
数値が1つ変わるだけでダイジェストは変わる。そのため、ダイジェストが一致すれば証拠となり、一致しなければ停止の合図となる。Iceberg から DuckLake へのコピーでは、出力にはまず両方の行数が表示され、それらは等しい。続いてダイジェストが表示され、ダイジェストは match である。Delta から Iceberg へのコピーに同じ検査を行っても一致する。閲覧数を1つ変更した場合、ダイジェストは differ である。
ダイジェストはデータベースが返したとおりの値を比較するものであり、限界がある。ハッシュする前に両側をテキストにキャストすると、型の異なる2つの値が同じテキストになることがある。整数 1 とテキスト '1' は同じテキストである。この例のように型付きの値を比較し、Delta から Iceberg へのコピーで行ったようにスキーマを出力すること。ダイジェストは列名や型についても何も語らない。行が同じで列名が異なる2つのテーブルは、同じダイジェストになる。前の節のスキーマ一覧が名前を検査し、ダイジェストが値を検査するので、コピーにはその両方が必要である。
ダイジェストはファイルのハッシュではない。行は型付きの値でソートされ、それぞれが Python での表現による1行になり、連結したテキストが SHA-256 でハッシュされる。値が等しい2つの行は等しい行を生み、比較に必要なのはこの性質である。1つの値が変われば1行が変わり、したがってダイジェスト全体が変わる。
検査の時点も選ぶ必要がある。ダイジェストは、それが実行された時点に存在していた行についてのみ正しい。その後にソースへ書き込みがあればコピーは古くなり、書き込み前のダイジェストはもう当てはまらない。検査はソースへの最後の書き込みの後、かつ誰かがコピーから読み取る前に行うべきである。
実践ルール: ソースへの最後の書き込みの後に、同じ列を対象として、型付きの値で両側のダイジェストを取る。行数とダイジェストを合わせて比較する。両方が一致するまでは、読み手を切り替えたりソースを削除したりしない。コピー中に書き込みが行われていた場合は、コピーとダイジェストをやり直す。
この部分はまだ翻訳されていないため、英語で表示している。
What goes wrong in production
A failed migration usually passes the first check and fails later. These are the failures to look for, and how you would notice each.
- A cutover that races a writer. A digest covers only the rows it read, as the digest section says. The first append after it makes the copy stale, and the digest does not warn you. Stop the writers, copy, digest and then move the readers. If the writers cannot stop, copy in windows and check the rows that arrived after the last window.
- Deleting the source before the checks pass. The source holds the history that the copy does not. Once the source is gone, time travel into its snapshots and versions goes with it. Keep the source until the digests match and every reader has moved. Then decide how long to keep it, in writing.
- A copy with the rows and without the layout. A copy made without the
ALTERwould hold every row and match the digest, with no partition set. The partition list and the files per partition are the checks that show the layout is missing, so print both after the copy. - Timestamps that change without an error. Delta Lake cut the nanosecond values to microseconds and raised no error. The row count stayed the same. A check on the values is the only thing that catches it, so a copy with sub-microsecond data needs that check before it runs.
- Names and types that differ. pyiceberg refuses an append whose column names differ from the table's, or whose type it cannot promote, and that refusal is the clearest failure. The harder case is a column whose name matches and whose type it accepts, such as a
longthat was anint. Print both schemas and read them, rather than trusting that the append succeeded. - Size and memory. The helpers in this chapter read a whole table into memory before they write it. That suits 1499 rows. A table of billions of rows needs a copy that reads and writes in batches, and the digest must then be computed over the same batches on both sides, so it stays a check of the whole table.
- Readers that write to both tables. During a copy, a job that writes to both tables by mistake makes the two tables differ, and the digest will show a mismatch that no single write explains. Name one writer per table in the runbook before the cutover starts.
- A digest over text. A digest over casts can match when the types differ. The check in this chapter compares typed values, and the runbook should say so, so that a later edit to the check does not quietly drop the types.
この部分はまだ翻訳されていないため、英語で表示している。
Decisions this chapter made
- Copies go through Arrow, and each target is written by the library that owns its format. pyiceberg writes Iceberg, DuckDB's
ducklakeextension writes DuckLake, and deltalake writes Delta Lake. This book does not use DuckDB'sicebergordeltaextensions, so no copy in it depends on them. - Delta tables are read through
read_delta, for the reason in chapter 8. Every Delta read in this chapter goes through it. - A copy is one-time, starts a new history and is checked before anyone switches to it. The source stays in place until the digests match and the readers have moved.
- The partition spec is set on the target by hand, with an
ALTERbefore the rows are inserted, and printed. The copy does not bring it across. - Each copy example builds its own source from the same three hours of the cut. Every example runs alone, and each check reads only the rows that its own example wrote.
- Checks run on typed values, after the last write, over the same columns. The row count and the digest are read together, and neither one is used alone to call a copy good.
- The copies use microsecond timestamps, and a separate example checks sub-microsecond values. Each copy in this chapter keeps its microsecond values, so the digests match. The precision example shows what each format does with a value it cannot keep.
- Metadata-only migration is not used here. pyiceberg's
Table.add_filesadds Parquet files that already exist to an Iceberg table as data files (Table.add_filesinpyiceberg/table/__init__.py, pyiceberg 0.12.0). Its API docs, which are not pinned to that version, describe this as committing the files without rewriting them. That keeps the data files in place, which a copy does not. This chapter did not run it, and it copies rows instead.
この版における本章
第2026.11.10版2026年11月20日時点で例が通過この章の4 例件のうち4件が合格
英語版の書籍(版2026.11.10)から翻訳した。