Lakehouse for Apache Iceberg 會透過 Lakehouse 執行階段目錄管理中繼資料。使用 Apache Iceberg REST 目錄端點時，系統會將資料整理成嚴格的資源階層。目錄設定會決定支援的儲存空間類型、區域路由行為和查詢聯合選項。
資源階層
Apache Iceberg REST 目錄端點會使用資源階層來整理資料。下表概略說明這些資源：
| 資源 | 說明 |
|---|---|
| 目錄 | 目錄是頂層容器，可讓您將命名空間和資料表劃分成不同目錄，整理成邏輯群組。每個目錄都由指定的倉儲儲存空間位置 (例如 Cloud Storage 值區或 BigQuery 聯合代理伺服器) 做為後端，儲存其基礎中繼資料和資料檔案。 |
| 命名空間 | 用於整理目錄中資料表的邏輯分組，功能類似於資料庫、結構定義或目錄。 |
| 資料表 | 資料表包含可查詢的資料列和資料欄定義。 |
倉庫儲存位置
設定用戶端以連線至 Apache Iceberg REST 目錄端點時，請指定倉庫儲存位置。在基礎 API 中，這對應於 CATALOG_TYPE_GCS_BUCKET 設定。選擇 Cloud Storage bucket 做為倉庫位置，會決定目錄的運作方式，以及如何與其他 Google Cloud 服務整合。
Cloud Storage
建議
這是標準做法，目錄的所有中繼資料和資料檔案都會儲存在單一指定 Cloud Storage 值區 (gs://) 中。如果工作負載需要在多個獨立值區之間共用資料，您必須建立多個不同的目錄。
使用 Cloud Storage bucket 可直接控管資料版面配置，並支援儲存空間存取權委派 (憑證販售)，直接向用戶端引擎販售短期存取權權杖。這樣一來，引擎就能安全地讀取及寫入資料檔案，不必在底層值區中擁有廣泛的直接 IAM 權限，讓您直接透過 Lakehouse 執行階段目錄建立及管理 Apache Iceberg 資料表。
舉例來說，如果您建立 bucket 來儲存目錄，並將其命名為 iceberg-bucket，則目錄名稱和 bucket 名稱都是 iceberg-bucket。稍後在 BigQuery 中使用 P.C.N.T 語法查詢目錄時，就會用到這項資訊。例如 my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table。
BigQuery
替代做法
這是一種替代方法，稱為 BigQuery 目錄同盟，其中 Apache Iceberg REST 目錄端點會做為 Proxy 閘道，而不是建立專屬的 Lakehouse 目錄容器。在基礎 API 中，這對應於 CATALOG_TYPE_BIGQUERY 設定。外部引擎使用 bq:// 倉庫前置字元連線時，閘道會將目錄要求直接傳送至 BigQuery 的內部目錄。
使用 BigQuery 目錄同盟，您就能直接在 BigQuery 中，使用標準 BigQuery DDL 或 API 建立及管理資料表，同時透過 REST 目錄端點，授予外部 OSS 引擎查詢這些資料表的唯讀存取權。由於存取權是由 BigQuery 直接管理，外部引擎完全依賴 BigQuery 的內部 IAM 權限和存取控制清單 (ACL)。請注意，BigQuery 聯盟目錄不支援儲存空間存取權委派 (憑證販售)。
舉例來說，如果資料表位於專案 my-project 中，倉庫路徑就是 bq://projects/my-project。與 Cloud Storage bucket 目錄不同，聯合資料表會直接顯示在 BigQuery 中，不需要四部分 P.C.N.T 名稱。例如：SELECT * FROM my_namespace.my_table。
BigQuery 目錄聯盟與跨雲端 Lakehouse 不同，後者會 Google Cloud 連結至遠端外部目錄 (例如 Databricks Unity Catalog)，以便查詢不同雲端供應商的資料。
如要進一步瞭解如何設定及使用這項工作流程，請參閱「搭配使用目錄同盟與 BigQuery」。
值區和目錄區域
如果是 Lakehouse 執行階段目錄中的 Cloud Storage bucket 倉庫，系統會選取與基礎 bucket 區域相符的目錄區域：
單一區域 bucket：目錄區域與 bucket 區域完全相符。
雙區域值區：包括預先定義和使用者定義的雙區域，例如
ASIA1和NAM4。目錄區域與雙區域相符。多區域值區：系統會為多區域地理網域內的目錄選取區域位置。根據預設，這些位置可能與常見的 BigQuery 位置 (例如
US和EU) 不符。而是地理網域內的區域位置 (例如US多區域值區的us-central1和us-east4)。
當 BigQuery 對這些目錄中的資料表執行查詢時，BigQuery 會將查詢導向目錄主要區域中的區域。如果您在特定虛擬區域 (例如 US 或 EU) 執行查詢，但該位置沒有目錄中繼資料，查詢可能會失敗。
為美國和歐盟多區域指定主要區域
如果目錄使用 US 或 EU 多區域值區，您可以在建立目錄時指定主要區域，確保 BigQuery 能從對應區域存取目錄。
- Cloud Storage 歐盟多區域：指定
EU或europe-west4。 - Cloud Storage 美國多區域：指定
US或us-central1。
建立目錄時，系統會選取目錄的主要副本，但您可以呼叫 FailoverCatalog 動態更新。如要進一步瞭解如何定義主要位置，請參閱「建立目錄」。
從 BigQuery 查詢目錄
從 BigQuery 查詢 Lakehouse 執行階段目錄資料表時，您會使用四部分命名結構，通常稱為 P.C.N.T：
- 專案：擁有目錄的 Google Cloud 專案 ID。
- Catalog：Lakehouse 執行階段目錄的名稱。
- Namespace：Apache Iceberg 命名空間 (相當於 BigQuery 資料集)。
- Table：資料表名稱。
例如 my-project.lakehouse-catalog-id.my-namespace.my-table。