建立第一個資料表:從頭到尾
閱讀約需 40 分鐘 分鐘,10 節 中共有 3 個範例。
讀完本章後,你可以將多批資料列提交到資料表、在 DuckDB 中讀回該資料表,並核對總計。本書的讀者是撰寫 SQL 與 Python 的資料工程師與分析工程師,他們必須決定湖倉(lakehouse)資料表要如何儲存、變更、清理、共用,以及在不同格式之間搬移。本書會建立一個成果:pageviews 資料表。你會儲存它、變更它、以較早的快照讀取它、清理它、在目錄中註冊它,並在不同格式之間搬移它。
放在資料夾裡的六個小時 Wikimedia 瀏覽量資料,還不算是資料表。資料夾沒有說明哪些檔案屬於該資料表,而載入到一半中斷時,留下的檔案看起來與其他檔案毫無差別。本書建立的資料表以小時為單位:每一列記錄一篇公開的 Wikipedia 文章,在某一個小時內、於某一種語言版次中被瀏覽了多少次。我們稱它為 pageviews 資料表。
本章建立這個資料表的粗略版本。它以三種格式(Apache Iceberg、Delta Lake 與 DuckLake)寫入資料表,並將每一種格式讀回 DuckDB,讓你比較各自的總計。後續每一章會讓其中一個步驟更為穩固:
- 第 2 章以較早的快照讀取資料表在當時的樣貌。
- 第 3 章新增與重新命名欄位,而不必重寫檔案。
- 第 4 章變更分割方式,而不必重寫舊檔案。
- 第 5 章以刪除、更新與合併來修正資料列。
- 第 6 章壓實每小時附加資料所留下的小檔案。
- 第 7 章讓快照過期,並移除沒有任何快照會用到的檔案。
- 第 8 章在目錄中註冊資料表,並從 DuckDB 查詢。
- 第 9 章在格式之間搬移資料表,並檢查複本。
- 第 10 章依據你的工具所支援的項目來選擇格式。
你已經懂 SQL、Python 與 Parquet,也知道什麼是分割區。本章不會說明這些內容。
pageviews 資料表的資料列涵蓋 2024 年 6 月 3 日的六個小時,從 UTC 00:00 到 05:59。它們來自 Wikimedia pageviews dumps,這些資料由 Wikimedia 專案以 CC0 釋出。本書在移除特殊頁面之後,保留英文、德文、法文與日文版次中每個小時瀏覽量最高的 500 個標題。這一天是固定的,而且已經過去,因此該日的傾印檔不會再改變,儲存庫中的資料也不會過時。資料資料夾的 README 載明了來源、授權條款與確切的擷取範圍。
這些資料刻意保持雜亂。標題帶有底線與非拉丁文字,計數也呈現偏斜:第 00 小時中瀏覽量最高的標題,其瀏覽次數遠多於排名第 500 的標題。如資料資料夾的 README 所記錄,這份擷取資料中的每一列,其 response_bytes 都是 0。本書保留該欄位在擷取資料中的原貌,因此它全部都是 0。這些值會留在資料中,因為資料表格式必須原樣儲存它們。
資料表格式為檔案增加了什麼
任何讀取該資料夾的程式,都會看到其中的每一個檔案。資料表格式以中繼資料(metadata)回應這個問題。資料表的中繼資料,記錄了資料表的結構描述(schema),以及在其歷史中每個時間點組成該資料表的資料檔案。對資料表所做的變更稱為提交(commit),提交會一次寫入新的中繼資料。這個步驟是將資料表從一個狀態推進到下一個狀態的唯一變更。
每種資料表格式都有自己的中繼資料,以及描述這些概念的用語。Iceberg 將提交之後的狀態稱為快照(snapshot)。Delta Lake 為其版本編號。DuckLake 則將快照記錄在目錄檔案(catalog file)中。本章會將資料寫入這三種格式,讓你在每一種格式中看到相同的資料列。
中繼資料存放的位置也各不相同。Iceberg 資料表會保存一個中繼資料檔案,其中指明目前的快照。在 pyiceberg 所寫出的格式版本 2 中,每個快照指向一份資訊清單清單(manifest list),資訊清單清單指明各個資訊清單(manifest),而每個資訊清單則指明資料檔案及其統計資訊。Iceberg 規格定義了其中每一層。Delta Lake 資料表則在其資料旁的 _delta_log 資料夾中,保存一份依序排列的提交檔案日誌,如 Delta Lake 協定所述。DuckLake 資料表將其中繼資料保存在你所附加(attach)的目錄檔案中,並將資料檔案寫入該檔案旁的資料夾。
六個小時的資料會一次一小時地寫入三種格式,接著讀回每個資料表並比較其總計。
1"""Load six hours into Iceberg, Delta Lake and DuckLake, then read each table back.23The rows and views lines print each format's totals, and the assert after them checks that the three agree.4The titles at the end come from the Iceberg table alone.5"""67from lib.lakehouse import (8 format_report,9 load_three_formats,10 new_warehouse,11 print_rows,12 safe_error,13 sql_rows,14 scan_arrow,15)1617# page_title breaks ties in views, so titles with equal views always print in the same order.18TOP_THREE = """19 SELECT sum(views) AS views, page_title FROM pageviews20 GROUP BY page_title ORDER BY views DESC, page_title LIMIT 321"""222324def main():25 try:26 with new_warehouse() as wh:27 # range(6) is hours 0 to 5, the six hours of the cut, one commit per hour in each format.28 iceberg, delta_path, lake = load_three_formats(wh, range(6))29 report = format_report(wh, iceberg, delta_path, lake)3031 for name, (rows, views, files) in report.items():32 print(f"{name} rows: {rows}")33 print(f"{name} views: {views}")34 print(f"{name} data files: {files}")35 # A set of (rows, views) pairs has one entry only when all three formats agree.36 totals = {(rows, views) for rows, views, _ in report.values()}37 assert len(totals) == 1, "the three formats disagree on rows or views"3839 print("top three page titles over six hours (views, page_title):")40 # pageviews names the Arrow table for the SQL; keep_order prints the rows in the SQL's order, not re-sorted.41 print_rows(sql_rows(wh.con, TOP_THREE, keep_order=True, pageviews=scan_arrow(iceberg)), keep_order=True)42 except Exception as exc:43 print(safe_error(exc))44 raise SystemExit(1)454647if __name__ == "__main__":48 main()
python rough-lakehouse.pyiceberg rows: 2999
iceberg views: 1807299
iceberg data files: 6
delta rows: 2999
delta views: 1807299
delta data files: 6
ducklake rows: 2999
ducklake views: 1807299
ducklake data files: 6
top three page titles over six hours (views, page_title):
399885 Main_Page
102089 メインページ
54796 Wikipedia:Hauptseite
三種格式回報相同的資料列數與相同的瀏覽次數總計,而且每一種格式都為每個小時各寫出一個資料檔案:
- Iceberg:2999 列、1807299 次瀏覽、6 個資料檔案。
- Delta Lake:2999 列、1807299 次瀏覽、6 個資料檔案。
- DuckLake:2999 列、1807299 次瀏覽、6 個資料檔案。
只要三種格式的資料列數或瀏覽次數總計出現任何差異,斷言(assert)就會使執行中止。接著輸出會列出六小時內瀏覽次數最高的三個標題,僅取自 Iceberg 資料表:Main_Page、メインページ 與 Wikipedia:Hauptseite,分別是英文版、日文版與德文版的首頁。
輸出中不含快照 ID、版本號碼或檔案名稱,因為這些內容每次執行都會改變;逐小時附加一節則說明快照改以什麼方式標示。
DuckLake 在你自己的機器上需要多做一個步驟。在 DuckDB 中先執行 INSTALL ducklake,再執行 LOAD ducklake。本書的執行則改為從儲存庫中的檔案載入一份 DuckDB 官方簽署的 ducklake 擴充套件,因此不需要網路連線即可執行。DuckLake 還有一個影響檔案數量的內嵌(inlining)預設值:預設情況下,10 列或更少的插入會保留在其目錄檔案中,而不寫入 Parquet 檔案。DuckLake 資料內嵌頁面說明了這個預設值:「Data inlining is enabled by default with a row limit of 10.」本範例將上限設為 0,使每次插入都會寫出一個檔案,如此各章中的檔案數量所代表的意義都相同。
此部分尚未翻譯,因此以英文呈現。
One load loop, three commit styles
The helper load_three_formats() in examples/lib/lakehouse.py holds the loop that rough-lakehouse calls. The loop writes each hour to all three tables, and each line that writes is one commit in one format:
for hour in hours:
rows = read_cut_hour(hour)
iceberg.append(rows)
write_deltalake(delta_path, rows, mode="append")
lake.register("hour", rows)
lake.execute(f"INSERT INTO {DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE} SELECT * FROM hour")
lake.unregister("hour")
read_cut_hour returns one hour of the cut as an Arrow table, with the same five columns in every format. The Iceberg append creates a snapshot. The Delta append creates a new version, and it creates the table on the first call, when the path does not yet hold one. The DuckLake insert writes a Parquet file and records a snapshot in the catalog file. The three calls differ, and the table each one writes is the same six hours of rows. The loop itself checks nothing. It runs the six loads in order and stops if one of them raises an error. The checks come after all six hours are in, when rough-lakehouse reads back each format's totals and compares them.
一次提交會指明資料表所含的檔案
Apache Iceberg 資料表規格將快照(snapshot)定義為資料表在某個時間點的狀態,讀取端藉由快照找出資料表中的每一個資料檔案。因此,快照做了兩件事:一是指明資料表在該時間點所包含的資料檔案,二是記錄產生這個快照的操作。規格中列出了各種操作類型。對於附加寫入(append)而言,其操作類型為 append,Iceberg 規格對它的描述是「只新增了資料檔案,沒有移除任何檔案」。
以 pageviews 資料表為例,可以看得更清楚。每載入一個小時的資料,就會產生一個資料檔案,每次載入則是一次提交。第一次提交之後,資料表只包含第 00 小時的檔案,沒有其他檔案。第二次提交之後,資料表包含兩個檔案,依此類推。資料檔案從不被修改。一次提交會新增檔案,而新的快照則指明提交之後資料表所包含的檔案。
資料表的資料檔案數量來自它的快照,而不是來自它的資料夾。rough-lakehouse會印出各種格式為該資料表回報的資料檔案數量。這個數字是資料表自己宣稱所包含的檔案數量,而列出資料夾內容所看到的數量可能與它不同。
**實用原則:**要透過目前的快照來詢問資料表包含了什麼,而不是列出它的資料夾。資料夾裡有寫入端放進去的每一個檔案,而快照則說明這些檔案之中哪些是資料表實際讀取的。
為什麼每種格式都透過 Python 函式庫來講解
rough-lakehouse 範例以不同的函式庫寫入各個格式,本節說明原因。本書以讀者實際會用來操作的 Python 函式庫來寫入 Apache Iceberg 與 Delta Lake:pyiceberg(版本 0.12.0)與 deltalake(版本 1.6.6)。DuckDB(版本 2.0.0)則讀取這些函式庫寫出的內容。它從 scan 讀取 Iceberg 資料表,得到 Arrow 資料表;也從 deltalake 執行的查詢讀取 Delta 資料表,同樣得到 Arrow 資料表。DuckLake 是例外:DuckDB 透過其 ducklake 擴充套件自行執行 DuckLake,並掛載該資料表的目錄檔案(catalog file)。本書不使用 DuckDB 的 iceberg 或 delta 擴充套件,也沒有任何範例執行它們。
| 格式 | 寫入者 | DuckDB 讀取方式 |
|---|---|---|
| Apache Iceberg | pyiceberg,0.12.0 | 由 scan 取得 Arrow 資料表 |
| Delta Lake | deltalake,1.6.6 | 由 deltalake 的 QueryBuilder 取得 Arrow 資料表 |
| DuckLake | DuckDB 的 ducklake 擴充套件,執行於 DuckDB 2.0.0 |
以 ATTACH 連到目錄檔案 |
這個選擇有其代價。若讀者以 Spark 或 Trino 執行 Iceberg,會在那裡接觸到更多該格式的內容,包括本書未涵蓋的功能。本書會指出這些地方,但不講授那些引擎。換來的好處是變動的零件較少:每種格式由其自身的函式庫寫入,再由 DuckDB 讀取輸出。每個函式庫的版本都已固定,各章所指的是固定的函式庫版本,而非該格式規格的版本。這些固定的版本記錄在 examples/requirements.txt,該檔每行列出一個套件及其唯一確切的版本。依該檔安裝的讀者,會得到本章執行時所用的函式庫。請使用 examples/.python-version 指定的 Python 版本,因為 pip 不會替你選擇 Python 版本。
實用原則: 以你固定版本的函式庫來寫入與讀取每個資料表,並說明你的讀取使用哪個版本。只有在你實際量測過函式庫無法替你做到的事之後,才改用引擎自身的擴充套件。
將三個小時的資料寫入資料表
rough-lakehouse 範例展示了完整的流程,因此本節放慢腳步,只談一張資料表。寫入一批資料需要兩個步驟:先建立資料表,再把每一批資料提交(commit)到資料表中。pageviews 資料表會先寫入 00、01 和 02 這三個小時的資料,因此每個小時各為一次提交。該範例在前三個小時之後,以相同的方式載入 03 至 05 時的資料。本節其餘部分只針對 Iceberg 資料表進行說明,因為它能呈現的內容最多。
此部分尚未翻譯,因此以英文呈現。
Create the table in a catalog
An Iceberg table needs a catalog, which is the registry that maps a table name to the table's current metadata. A Delta Lake table is found by its path, with no catalog, and a DuckLake table lives in its catalog file. The book uses pyiceberg's SQL catalog on SQLite for the Iceberg table. The catalog is one file, and the table's data files go in a warehouse folder beside it. The catalog holds pointers and metadata, not rows. Inside the catalog file, a table name such as wiki.pageviews_hourly maps to the location of the table's current metadata file. A commit writes a new metadata file and moves that mapping, so anyone who asks the catalog for the table gets the metadata that the most recent commit wrote. The helper new_warehouse() in examples/lib/lakehouse.py makes a temporary catalog and warehouse for each run, and removes them when the run ends. Because SQLite is a file and needs no server, the whole catalog runs on a laptop with the network off.
The table has five columns, and its schema says what each one holds:
Schema(
NestedField(1, "hour_utc", TimestampType(), required=False),
NestedField(2, "domain_code", StringType(), required=False),
NestedField(3, "page_title", StringType(), required=False),
NestedField(4, "views", LongType(), required=False),
NestedField(5, "response_bytes", LongType(), required=False),
)
The hour_utc column holds a timestamp without a time zone, in UTC, and the two counts are 64-bit integers. The helper create_iceberg_table() creates the table in the catalog, unpartitioned. Chapter 4 adds a partition spec to it.
Working rule: Write the schema out in code, with the type each column really has, before the first commit. The types are then decided on purpose, and not by whichever batch happens to arrive first.
將每小時的資料以一次提交(commit)附加
一次附加(append)就是一次提交。下方範例中,pyiceberg 先建立資料表,依序附加 00、01 與 02 時的資料,接著依提交順序列出各快照(snapshot),並附上其操作類型與每次提交新增的資料列數:
1"""Create the Iceberg table, append hours 00 to 02 as three commits, then repeat hour 00.23The hour 00 point rests on the `snapshot 1 rows added` and `snapshot 2 rows added` lines, and the repeated-load point on the two `repeat of hour 00` lines.4"""56from lib.lakehouse import (7 create_iceberg_table,8 iceberg_file_count,9 new_warehouse,10 read_cut_hour,11 safe_error,12 scan_arrow,13 snapshot_labels,14)151617def main():18 try:19 with new_warehouse() as wh:20 table = create_iceberg_table(wh)21 for hour in range(3):22 table.append(read_cut_hour(hour))2324 # pyiceberg returns the snapshots in commit order, which the labels below depend on.25 snapshots = table.snapshots()26 # Snapshot IDs change from run to run, so each one prints as its position in commit order.27 labels = snapshot_labels([snap.snapshot_id for snap in snapshots])28 for snap in snapshots:29 label = labels[snap.snapshot_id]30 print(f"{label} operation: {snap.summary.operation.value}")31 # The commit's own summary holds the rows it added, not a count of the whole table.32 print(f"{label} rows added: {snap.summary['added-records']}")3334 print(f"rows in table: {scan_arrow(table).num_rows}")35 # Counted from the current snapshot, not from the folder.36 print(f"data files: {iceberg_file_count(table)}")3738 # Hour 00 again.39 table.append(read_cut_hour(0))40 repeat = table.current_snapshot()41 print(f"repeat of hour 00 operation: {repeat.summary.operation.value}")42 print(f"repeat of hour 00 rows added: {repeat.summary['added-records']}")43 print(f"rows in table after the repeat: {scan_arrow(table).num_rows}")44 except Exception as exc:45 print(safe_error(exc))46 raise SystemExit(1)474849if __name__ == "__main__":50 main()
python append-hours.pysnapshot 1 operation: append
snapshot 1 rows added: 499
snapshot 2 operation: append
snapshot 2 rows added: 500
snapshot 3 operation: append
snapshot 3 rows added: 500
rows in table: 1499
data files: 3
repeat of hour 00 operation: append
repeat of hour 00 rows added: 499
rows in table after the repeat: 1998
00 時的資料少了一列:第一次提交新增 499 列,後兩次各新增 500 列。如資料說明文件(README)所述,隱私檢查從 00 時的資料中移除了一列。三次提交之後,資料表共有 1499 列,分布在 3 個資料檔中,每次提交各對應一個檔案。
每次提交也會寫入一份摘要,而 pyiceberg 會依提交順序傳回各快照,操作類型與新增列數即取自這份摘要。每次提交的操作類型都是 append,也就是規格(spec)所定義的附加操作。快照摘要是資料表對自身提交所做的紀錄,因此當筆數有誤時,應先查看這裡。
輸出中的標籤 snapshot 1、snapshot 2 與 snapshot 3 用來代表快照 ID。Iceberg 的快照 ID 是一個長整數,規格要求其必須唯一,並由 pyiceberg 在提交時選定,因此每次執行都會不同。將每個 ID 對應到它在提交順序中的位置,可使每次執行的輸出保持一致。
實用原則: 每個你能指名的批次只做一次提交,並在進行下一次提交之前,將每次提交所新增的資料列數與來源端預期的筆數相互比對。筆數有誤時,趁該次提交仍是最新的一筆最容易追查;一旦其上又疊了更多提交,就困難得多。
使用 DuckDB 查詢資料表
資料表建立完成後,接下來就是對它提出問題。DuckDB 執行的是 SQL,但 Iceberg 資料表並不是 DuckDB 的資料表。本書的做法是:將資料表目前的快照讀成 Arrow 資料表(這是 pyiceberg 掃描後回傳的結果),再以名稱 pageviews 將該 Arrow 資料表註冊到 DuckDB。之後 DuckDB 便能對它執行一般的 SQL,不需要任何 Iceberg 擴充套件。掃描是資料表自身讀取快照的方式:它列出快照所指定的資料檔案,讀取這些檔案,只交出檔案中的資料列。DuckDB 看到的正是這些資料列,快照未指定的內容一概看不到。
下一個範例會將 00 至 02 時的資料附加到一個全新的資料表,並提出兩個問題:00 時瀏覽次數最多的五個標題是哪些,以及這三個小時共有多少次瀏覽。範例還會將此總數與掃描本身算出的加總相互核對。
1"""Read the current Iceberg snapshot into DuckDB and check the totals.23The point that DuckDB received every row rests on the two total views lines, which the assert compares.4"""56from lib.lakehouse import (7 create_iceberg_table,8 new_warehouse,9 print_rows,10 read_cut_hour,11 safe_error,12 scan_arrow,13 sql_rows,14)151617def main():18 try:19 with new_warehouse() as wh:20 table = create_iceberg_table(wh)21 for hour in range(3):22 table.append(read_cut_hour(hour))23 # The current snapshot's rows as one Arrow table, sorted by every column.24 arrow = scan_arrow(table)2526 top = sql_rows(27 wh.con,28 # hour_utc is UTC, so this is hour 00 of 3 June 2024; page_title breaks ties in views.29 """30 SELECT views, page_title FROM pageviews31 WHERE hour_utc = TIMESTAMP '2024-06-03 00:00:00'32 ORDER BY views DESC, page_title LIMIT 533 """,34 # keep_order returns the rows in the order the SQL sorted them, not sorted again.35 keep_order=True,36 pageviews=arrow,37 )38 print("top five pages for hour 00 (views, page_title):")39 print_rows(top, keep_order=True)4041 # One row with one column: the sum.42 duckdb_total = sql_rows(wh.con, "SELECT sum(views) FROM pageviews", pageviews=arrow)[0][0]43 # A second route to the same total, summed in Python from the scan's own rows.44 pyiceberg_total = sum(arrow["views"].to_pylist())45 print(f"total views in DuckDB: {duckdb_total}")46 print(f"total views in the scan: {pyiceberg_total}")47 assert duckdb_total == pyiceberg_total, "DuckDB and the scan disagree on the total"48 except Exception as exc:49 print(safe_error(exc))50 raise SystemExit(1)515253if __name__ == "__main__":54 main()
python scan-into-duckdb.pytop five pages for hour 00 (views, page_title):
61107 Main_Page
13791 メインページ
9492 Wikipedia:Hauptseite
7511 Wikipédia:Accueil_principal
3781 笹生優花
total views in DuckDB: 899451
total views in the scan: 899451
清單列出 00 時瀏覽次數最多的五個標題,依瀏覽次數由大到小排列,次數相同時以標題作為排序依據;每一行依序顯示瀏覽次數、一個跳位字元(tab)與標題。DuckDB 算出的總數為 899451 次瀏覽,與掃描本身的加總 899451 相同;若兩者不一致,assert 會讓程式中止。
總數與掃描的加總相符,只能證明 DuckDB 收到了掃描回傳的每一列資料。它並不檢查資料列本身的內容,也不檢查前五名的查詢。對總數做檢查只需要一行程式碼,因此每次修改查詢之後都值得執行一次。將資料列與其來源逐一核對,則是後續各章的工作:那些章節會把每一項變更與其所取自的資料相互比較。
實用原則: 將 Iceberg 資料表讀成掃描所得的 Arrow 資料表再交給 DuckDB,並以總數與掃描本身的加總相互比對,藉此確認 DuckDB 收到了每一列資料。接著,再將每個查詢的結果與可供比對的來源核對。
正式環境中會出什麼問題
第 1 章的路徑很短,卻隱藏了四個在正式環境中會遇到的問題。
重複載入會再次加入相同的資料列。 如規格對該操作的定義所述,append 只會加入所給定的資料檔案,不會移除任何檔案。資料表中沒有任何機制能擋下第二份 00 時的資料。帶有第二份 00 時資料的提交,看起來與其他提交並無不同。append-hours 展示了這一點:重複提交的操作是 append,它加入了 499 筆資料列,與第一份的筆數相同,之後資料表共有 1998 筆資料列,過程中沒有任何錯誤。唯一能說明這次載入原本只應執行一次的紀錄,是你在載入前寫下的筆數。第 5 章會說明如何修正被錯誤載入的資料列。
資料夾中的內容多於資料表所含的內容。 計算倉儲資料夾中的檔案數量,所回答的問題與計算資料表的檔案數量不同。資料夾中有寫入者放進去的每一個檔案,而資料表所含的內容是由快照定義的。若有工具計算資料夾中的 Parquet 檔案數,所回報的數字是資料表從未承諾過的。第 6 章與第 7 章會處理資料表已不再引用的檔案。
快照 ID、版本與快照編號是不同種類的數字。 Iceberg 的 ID 是 64 位元的值。Delta Lake 的版本依提交順序從 0 開始計數。DuckLake 同樣為其快照編號,並且在每次建立結構描述或資料表時,以及每次插入資料列時,都會記錄一個快照。若腳本儲存了某一種格式的數字,卻把它當成另一種格式的版本來讀取,讀到的就是錯誤的狀態。
小量的 DuckLake 插入不會寫出檔案。 預設情況下,DuckLake 會把 10 筆(含)以下資料列的插入保留在它的目錄(catalog)中,因此小量插入後檔案數為零是預期的結果,而不是失敗。本書的 DuckLake 範例都把資料列上限設為 0,唯有第 10 章的 ducklake-inlined-delete 保留預設值,以展示小量刪除不會寫出刪除檔案。讀者若把某個插入操作複製到自己的目錄中執行,應先了解這個預設值。
實用原則: 在每次載入旁寫下該次提交應加入的資料列筆數,並在每次載入後,將該筆數與提交的摘要比對。資料表不會檢查重複載入。事先寫下的筆數,才是能發揮檢查作用的依據。
本章做出的決定
- 本章有三個範例。
rough-lakehouse以三種格式處理完整的結果,因此後面每一章都只改變讀者已經執行過的結果中的一個部分。另外兩個範例append-hours與scan-into-duckdb,則是一次一個 commit 地建立 Iceberg 資料表,並在 DuckDB 中讀取。 - **先處理 00 到 02 時,再處理 03 到 05 時。**Iceberg 範例寫入三個小時的資料,粗略版範例則寫入六個小時。只有
rough-lakehouse會加總全部六個小時。 - **資料表不分區。**第 1 章建立資料表時不使用分區規格(partition spec),第 4 章才會更改分區方式。pyiceberg-core 套件與 pyiceberg 一同固定版本,因為第 4 章的日與小時轉換需要用到它。
- **範例中關閉 inlining。**DuckLake 範例把
DATA_INLINING_ROW_LIMIT設為 0,讓每次插入都寫出一個 Parquet 檔案,如此本書各處印出的檔案數量意義一致。第 10 章的ducklake-inlined-delete則保留預設值,因為該範例要說明的重點是:小量刪除之後不會寫出刪除檔。 - Delta 資料表只透過 deltalake 的
QueryBuilder讀取。examples/lib/lakehouse.py中的讀取輔助函式採用這條路徑,後面每一章只要讀取 Delta 資料表,都使用同一個輔助函式。 - **使用真實資料,而非替代資料。**本章每個範例都讀取資料說明文件所描述的、從六份公開傾印檔(dump)中截取的資料。本書不為本章提供任何產生的資料。
- **Iceberg 目錄使用 SQLite。**SQLite 檔案不需要伺服器,因此 Iceberg 範例可以在關閉網路的筆電上執行。這些執行也會關閉 DuckDB 的擴充套件自動下載功能,所以需要網路的執行會失敗,而不是去下載。
- **以標籤代替 ID。**書中印出的
snapshot 1、snapshot 2等標籤,代表快照 ID,因此輸出不會隨每次執行而改變。
本章,於本版次中
版次 2026.11.10範例於 2026年11 月 20 通過測試本章 3 個範例 個範例中有 3 個通過
譯自英文書,版次 2026.11.10。