2026-09-30 — ClickHouse 可直接寫入 OneLake 的 Iceberg 目錄

ClickHouse 可直接寫入 Microsoft OneLake 的 Iceberg 目錄

ClickHouse Blog · 2026-09-29

ClickHouse 對 OneLake 的存取從「只能查」變成「能查也能寫」：INSERT INTO 產生的 Iceberg 資料表會直接登錄在 OneLake catalog，Fabric 內的其他引擎立刻看得到。以前要自己把 Iceberg 檔案寫到 S3 或 ADLSgen2 路徑，再另外想辦法註冊。

這項功能由 Melvyn Peignon 與 Karolina Ruiz Rogelj 在官方部落格公布，文章未提及對應的 ClickHouse 版本號。

原本的問題

依部落格說明，ClickHouse 在此之前已能把 Iceberg 資料表寫到物件儲存，但只要沒有登錄到 catalog，組織內的其他工具就無法探索或查詢這些資料表。實務上，資料團隊得在 ClickHouse 寫完後，再靠 Fabric 的 Shortcuts 或 Mirroring 之類的機制把資料接進湖倉，多一道手動流程。

同樣的限制也留在文件裡：OneLake catalog 文件頁目前只示範 SELECT、SHOW TABLES，並未記載寫入，且標示為 beta，需先 SET allow_database_iceberg = 1。

核心改動

做法是用 DataLakeCatalog 引擎建立一個指向 OneLake Iceberg REST 端點的資料庫，身分驗證走 Microsoft Entra ID 的 service principal。同一組身分同時負責在 catalog 內找表，以及讀寫 OneLake 儲存層。

SET allow_database_iceberg = 1;

CREATE DATABASE onelake_catalog
ENGINE = DataLakeCatalog('https://onelake.table.fabric.microsoft.com/iceberg')
SETTINGS
    catalog_type = 'onelake',
    warehouse = '<workspace_id>/<lakehouse_id>',
    onelake_tenant_id = '<tenant_id>',
    oauth_server_uri = 'https://login.microsoftonline.com/<tenant_uuid>/oauth2/v2.0/token',
    auth_scope = 'https://storage.azure.com/.default',
    onelake_client_id = '<client_id>',
    onelake_client_secret = '<client_secret>';

建好之後，寫回只是一般的 SQL。下面的聚合結果會成為 OneLake 中的一張 Iceberg 表，並出現在 catalog 裡：

INSERT INTO onelake_catalog.`<namespace>.<output_table>`
SELECT region, count() AS order_count, sum(revenue) AS total_revenue
FROM onelake_catalog.`<namespace>.<source_table>`
GROUP BY region;

前後對照

項目	之前	現在
寫入位置	直接指定 S3 / ADLSgen2 路徑	OneLake catalog 內的資料表
其他工具能否發現	未登錄 catalog 就不能	登錄後可被相容工具查詢
Fabric 內的格式	需自行處理	寫出的 Iceberg 表在 Fabric 內可當 Delta Lake 讀取

影響範圍

已在用 Fabric 做湖倉、又用 ClickHouse 跑重運算的團隊最直接受益：把重的聚合留在 ClickHouse，結果表交給 Fabric 上的報表與其他引擎，不必再維護搬運腳本。

要檢查的地方有三項：

service principal 需要同時具備 catalog 與儲存層的讀寫權限；部落格說明存取控制沿用 OneLake Security（資料表、列、欄層級）。
表名要用反引號包起來，因為 ClickHouse 不支援多層 namespace，文件也有同樣說明。
文件頁仍寫 beta 且未列寫入，正式導入前應以自己的環境驗證，不要只看文件。

部落格表示 OneLake 是第一個支援寫入的 catalog，並預告未來幾個月會有更多 catalog。哪些 catalog、何時到位，文章未說明。

原始來源：ClickHouse 部落格、OneLake catalog 文件

End of article