Lakehouse for Apache Iceberg 會透過 Lakehouse 執行階段目錄管理中繼資料。使用 Apache Iceberg REST 目錄端點時，系統會將資料整理成嚴格的資源階層。目錄設定會決定支援的儲存空間類型、區域路由行為和查詢聯合選項。
功能和法規遵循
Lakehouse 執行階段目錄支援標準資料表格式，並符合開放式 API，可與 Iceberg 相容的查詢引擎整合。
支援的表格格式
支援 Apache Iceberg V2 資料表 (正式發布版) 和 V3 資料表 (預先發布版)。不支援 Iceberg V1 資料表。如要透過 Apache Iceberg REST 目錄端點使用現有的 V1 表格，必須先將這些表格升級至支援的版本。詳情請參閱「將 Iceberg V1 資料表升級至 V2」。
API 規範和 REST 作業
Lakehouse 執行階段目錄會實作開放標準 Apache Iceberg REST 目錄 API。用戶端查詢引擎會使用標準 REST 目錄 API 與目錄互動。詳情請參閱「Lakehouse 如何實作 Apache Iceberg REST 目錄 API」。
資源階層
Apache Iceberg REST 目錄端點會使用資源階層來整理資料。下表概略說明這些資源：
| 資源 | 說明 |
|---|---|
| 目錄 | 目錄是頂層容器，可將命名空間和資料表劃分成不同目錄，歸入邏輯群組。每個目錄都由指定的倉儲儲存空間位置 (例如 Cloud Storage 值區或 BigQuery 聯合代理伺服器) 做為後端，儲存其基礎中繼資料和資料檔案。 |
| 命名空間 | 用於整理目錄中資料表的邏輯分組，功能類似於資料庫、結構定義或目錄。 |
| 資料表 | 資料表包含可查詢的資料列和資料欄定義。 |
目錄和儲存位置
目錄的設定決定了目錄的運作方式，以及如何與 Google Cloud 服務整合。您可以設定多 bucket (bl://) 目錄 (建議) 或單一 bucket (gs://) 目錄。
這兩種選項都支援憑證販售，可進行精細的存取控管。
多 bucket (bl://) 目錄 (建議)
這種方法可讓您獨立命名目錄，不必與任何 bucket 名稱相關，而且可為單一目錄設定多個 bucket。在基礎 API 中，這項設定對應於 CATALOG_TYPE_BIGLAKE 設定。
注意事項：
- 預設位置：您提供 bucket 的路徑 (
default_location) 或子路徑 (例如gs://my-bucket/path)，做為預設儲存位置。所有目錄資源 (命名空間和資料表) 都必須位於指定路徑下。舉例來說，如果您指定gs://my-bucket/path，就無法在gs://my-bucket/another/path底下代管命名空間或資料表。如果建立命名空間時未指定位置，系統會使用default_location。 - 受限位置：您也可以選擇提供額外的
restricted_locations設定，指定可建立命名空間和表格的其他值區或路徑。如果您指定子路徑 (例如gs://my-bucket/path)，使用該設定建立的任何資源都必須位於該路徑下 (例如gs://my-bucket/another/path無法代管命名空間或資料表)。 - 地理區域群組規定：雖然 bucket 可以跨專案、跨區域，且具有不同設定 (例如單一區域、雙區域或多區域)，但預設位置和受限位置的所有 Cloud Storage 位置都必須位於同一個地理區域群組 (例如美國、歐洲、加拿大或亞洲)。舉例來說，您無法使用歐洲或加拿大的值區設定美國多區域值區。
- 每個 bucket 可有多個目錄：您可以讓多個目錄指向同一個 bucket (例如使用不同的預設位置或受限位置)。不過，我們強烈建議不要採用這種設定，因為這可能會導致中繼資料衝突、意外覆寫資料，或發生權限外洩等安全性問題。
- 命名空間：允許指定自訂命名空間位置，只要這些位置位於預設或受限位置中設定的路徑下即可。請注意，在這些目錄中建立的表格，其實體路徑會自動附加隨機字串後置字元，以避免衝突 (例如
gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix})。詳情請參閱「表格管理和安全防護規則」。
單一 bucket (gs://) 目錄
這是舊版方法，目錄會直接管理您指定的單一 Cloud Storage bucket 中的 Apache Iceberg 中繼資料和資料檔案。在基礎 API 中，這項設定對應於 CATALOG_TYPE_GCS_BUCKET 設定。
如果是單一 bucket 目錄，目錄名稱會設為 bucket 的名稱。
舉例來說，如果您建立 bucket 來儲存目錄，並將其命名為 iceberg-bucket，則目錄名稱和 bucket 名稱都是 iceberg-bucket。稍後在 BigQuery 中使用 P.C.N.T 語法查詢目錄時，就會用到這項資訊。例如 my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table。
注意事項：
舊版目錄類型限制。強烈建議新專案不要使用舊版單一儲存空間設定。這項設定有幾個重大限制：
- 目錄名稱：鎖定為基礎 Cloud Storage bucket 名稱。
- 專案：鎖定至 bucket 的專案 (不支援跨專案目錄)。
- 區域：嚴格來說，這是從 bucket 的位置衍生而來，無法自訂。
- 儲存空間：將目錄限制在單一 bucket (無限制位置)。
每個 bucket 只能有一個目錄：對於這類舊版目錄，每個 bucket 只能有一個目錄，且目錄名稱必須與 bucket 名稱相符。
升級至多 bucket (
bl://) 目錄 (建議)：你可以將現有的單一 bucket (gs://) 目錄升級至多 bucket (bl://) 目錄 (建議)。升級後的目錄會保留原始 bucket 的名稱。之後，您就可以將多個值區與目錄建立關聯，並設定受限位置。
值區和目錄區域
Lakehouse 執行階段目錄中目錄端點的區域，取決於其基礎 Cloud Storage bucket 的區域：
- 多 bucket (
bl://) 目錄 (建議做法)：目錄區域衍生自default_location中設定的 bucket。 - 單一 bucket (
gs://)：目錄區域嚴格衍生自與目錄相關聯的 bucket，無法自訂。
對應的目錄區域會因 bucket 的區域類型而異：
- 單一區域：目錄區域與 bucket 區域完全相符。
- 雙區域：目錄區域與值區的雙區域相符 (例如
ASIA1或NAM4)。 - 多區域：目錄區域設為多區域地理網域內的特定區域位置。根據預設，這可能與常見的 BigQuery 多區域 (例如
US和EU) 不一致 (舉例來說，US多區域值區會對應至us-central1或us-east4)。
當 BigQuery 對這些目錄中的資料表執行查詢時，會將查詢路徑導向目錄的主要區域。如果您在特定虛擬區域 (例如 US 或 EU) 中查詢資料表，但該位置沒有目錄中繼資料，查詢就會失敗。
多區域的主要區域
如要允許 BigQuery 從 US 或EU多區域查詢目錄資料表，請在建立目錄時指定 US 或 EU 做為主要區域。
您可以在下列設定中，將多區域 (US 或 EU) 指定為主要區域：
如果 default_location 值區為：
US或EU多區域值區。- 這些多區域中的單一區域值區 (例如
us-central1或europe-west4)。 - 這些區域內的雙地區或自訂雙地區值區 (例如
NAM4或EUR4)。
建立目錄時會定義主要副本，但您可以呼叫 FailoverCatalog 動態執行容錯移轉。詳情請參閱「建立目錄」。
從 BigQuery 查詢目錄
從 BigQuery 查詢 Lakehouse 執行階段目錄資料表時，您會使用四部分命名結構，通常稱為 P.C.N.T：
- 專案：擁有目錄的 Google Cloud 專案 ID。
- 目錄：Lakehouse 執行階段目錄的名稱。
- Namespace：Apache Iceberg 命名空間 (相當於 BigQuery 資料集)。
- Table：資料表名稱。
例如 my-project.lakehouse-catalog-id.my-namespace.my-table。