無邊界 Lakehouse 會透過 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 值區) 做為後端，儲存目錄的基礎中繼資料和資料檔案。 |
| 命名空間 | 用於在目錄中整理資料表的邏輯分組，功能類似資料庫、結構定義或目錄。 |
| 資料表 | 資料表包含可查詢的資料列和資料欄定義。 |
產品目錄和儲存位置
目錄的設定會決定目錄的運作方式，以及如何與 Google Cloud 服務整合。您可以設定多儲存空間目錄 (建議) 或單一儲存空間目錄。
這兩種做法都支援憑證販售。
設定用戶端查詢引擎 (例如 Spark 或 Trino) 以連線至 Apache Iceberg REST 目錄端點時，請根據目錄類型指定倉庫路徑：
- 多 bucket 目錄：將倉庫路徑設為
bl://projects/PROJECT_ID/catalogs/CATALOG_ID。 - 單一 bucket 目錄：將倉庫路徑設為
gs://CLOUD_STORAGE_BUCKET_NAME。
多 bucket 目錄 (建議)
這個方法可讓您獨立命名目錄，不必與任何 bucket 名稱相關，並為單一目錄設定多個 bucket。在基礎 API 中，這項設定對應於 CATALOG_TYPE_BIGLAKE 設定。
注意事項：
- 用戶端資料倉儲設定 (
bl://)：設定 Iceberg 用戶端以連線至多 bucket 目錄時，請使用bl://URI 格式指定資料倉儲路徑：bl://projects/PROJECT_ID/catalogs/CATALOG_ID。bl://格式僅用於用戶端設定期間，識別目錄。在 Google Cloud 中建立或設定目錄時，儲存位置 (default_location和restricted_locations) 一律會指定為 Cloud Storage 路徑 (gs://)。 - 最多可有幾個 bucket：每個目錄最多可有 15 個 bucket。
- 預設位置：您提供 bucket 的路徑 (
default_location) 或子路徑 (例如gs://my-bucket/path)，做為預設儲存位置。所有目錄資源 (命名空間和資料表) 都必須位於指定路徑下。舉例來說，如果您指定gs://my-bucket/path，就無法在gs://my-bucket/another/path下代管命名空間或資料表。如果建立命名空間時未指定位置，系統會使用default_location。 - 受限位置：您也可以選擇為其他可建立命名空間和表格的 bucket 或路徑提供
restricted_locations設定。如果您指定子路徑 (例如gs://my-bucket/path)，使用該設定建立的任何資源都必須位於該路徑下 (例如，gs://my-bucket/another/path無法代管命名空間或資料表)。 - 地理區域群組規定：雖然 bucket 可以跨專案、跨區域，且具有不同設定 (例如單一區域、雙區域或多區域)，但預設位置和受限位置的所有 Cloud Storage 位置都必須位於同一個地理區域群組 (例如美國、歐洲、加拿大或亞洲)。舉例來說，您無法將美國多區域 bucket 設定為歐洲或加拿大 bucket。
- 每個 bucket 可有多個目錄：您可以讓多個目錄指向同一個 bucket (例如使用不同的預設位置或受限位置)。不過，我們強烈建議不要採用這種設定，因為這可能會導致中繼資料衝突、資料意外覆寫，或權限外洩等安全性問題。
- 命名空間：允許指定自訂命名空間位置，只要這些位置位於預設或受限制位置中設定的路徑下方即可。請注意，在這些目錄中建立的表格，系統會自動在實體路徑中附加隨機字串後置字元，以避免衝突 (例如
gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix})。詳情請參閱「表格管理和安全性規則」。
單一 bucket 目錄
這是舊版方法，目錄會直接管理您指定的單一 Cloud Storage bucket (gs://) 中的 Apache Iceberg 中繼資料和資料檔案。在基礎 API 中，這項設定對應於 CATALOG_TYPE_GCS_BUCKET 設定。
如果是單一 bucket 目錄，目錄名稱會設為 bucket 的名稱。
舉例來說，如果將 bucket 命名為 iceberg-bucket，目錄和 bucket 都會共用這個名稱。使用 P.C.N.T 語法在 BigQuery 中查詢目錄時，請使用這個名稱，例如 my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table。
注意事項：
舊版目錄類型限制。強烈建議新專案不要使用舊版單一 bucket 設定。這項設定有幾項重大限制：
- 目錄名稱：鎖定為基礎 Cloud Storage bucket 名稱。
- 專案：鎖定至 bucket 的專案 (不支援跨專案目錄)。
- 區域：嚴格來說，這是從 bucket 的位置衍生而來，無法自訂。
- 儲存空間：將目錄限制在單一 bucket (無限制位置)。
用戶端倉庫設定 (
gs://)：為單一 bucket 目錄設定 Iceberg 用戶端時，請將 Cloud Storage bucket 路徑 (gs://CLOUD_STORAGE_BUCKET_NAME) 指定為倉庫位置。每個 bucket 只能有一個目錄：對於這類舊版目錄，每個 bucket 只能有一個目錄，且目錄名稱必須與 bucket 名稱相符。
升級至多 bucket 目錄 (建議做法)：您可以將現有的單一 bucket 目錄升級至多 bucket 目錄 (建議做法)。升級後的目錄會保留原始 bucket 的名稱。之後，您就可以將多個值區與目錄建立關聯，並設定受限位置。
值區和目錄區域
Lakehouse 執行階段目錄中目錄端點的區域，取決於其基礎 Cloud Storage bucket 的區域：
- 多 bucket 目錄 (建議)：目錄區域衍生自
default_location中設定的 bucket。 - 單一 bucket 目錄：目錄區域嚴格來說是從與目錄相關聯的 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多區域值區。- 這些多區域內的單一區域 bucket (例如
us-central1或europe-west4)。 - 這些區域內的雙區域或自訂雙區域值區 (例如
NAM4或EUR4)。
建立目錄時會定義主要副本，但您可以呼叫 FailoverCatalog 動態執行容錯移轉。詳情請參閱「建立目錄」。
如要根據資料落地和主權規定，將要求直接傳送至特定區域，可以使用區域端點 (biglake.LOCATION.rep.googleapis.com)。詳情請參閱「Lakehouse 區域端點」。
從 BigQuery 查詢目錄
從 BigQuery 查詢 Lakehouse 執行階段目錄資料表時，您會使用四部分命名結構，通常稱為 P.C.N.T：
- 專案：擁有目錄的 Google Cloud 專案 ID。
- Catalog：Lakehouse 執行階段目錄的名稱。
- Namespace：Apache Iceberg 命名空間 (相當於 BigQuery 資料集)。
- 資料表：資料表名稱。
例如 my-project.lakehouse-catalog-id.my-namespace.my-table。