關於 Apache Iceberg REST 目錄端點

無邊界 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 Catalog API。用戶端查詢引擎會使用標準 REST 目錄 API 與目錄互動。詳情請參閱「Lakehouse 如何實作 Apache Iceberg REST Catalog API」。

資源階層結構

Apache Iceberg REST 目錄端點會使用資源階層來整理資料。下表概略說明這些資源：

目錄和儲存位置

目錄的設定會決定其運作方式，以及與 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://)。
• 儲存空間位置數量上限：除了 default_location 之外，您最多可以在 restricted_locations 中為每個目錄指定 128 個 Cloud Storage 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 (例如使用不同的預設位置或受限位置)。不過，我們強烈不建議採用這項設定，因為這可能會導致中繼資料衝突、意外覆寫資料，或權限外洩等安全性問題。
• 命名空間：只要自訂命名空間位置位於預設或受限位置設定的路徑下，即可指定。請注意，在這些目錄中建立的資料表，其實體路徑會自動附加隨機字串後置字元，以避免衝突 (例如 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 的名稱。之後，您可以將多個 bucket 與目錄建立關聯，並設定受限制的位置。

值區和目錄區域

Lakehouse 執行階段目錄中，目錄端點的區域取決於基礎 Cloud Storage bucket 的區域：

• 多 bucket 目錄 (建議)：目錄區域衍生自 default_location 中設定的 bucket。
• 單一 bucket 目錄：目錄區域完全取決於與目錄相關聯的 bucket，無法自訂。

對應的目錄區域會因 bucket 的區域類型而異：

• 單一區域：目錄區域與 bucket 區域完全相同。
• 雙區域：目錄區域與 bucket 的雙區域相符 (例如 ASIA1 或 NAM4)。
• 多區域：目錄區域設為多區域地理網域中的特定區域位置。根據預設，這可能與常見的 BigQuery 多區域 (例如 US 和 EU) 不一致 (例如，US 多區域 bucket 會對應至 us-central1 或 us-east4)。

BigQuery 對這些目錄中的資料表執行查詢時，會將查詢轉送至目錄的主要區域。如果您查詢特定虛擬區域 (例如 US 或 EU) 中的資料表，但該位置沒有目錄中繼資料，查詢就會失敗。

多區域的主要區域

如要允許 BigQuery 從 US 或 EU 多區域查詢目錄資料表，請在建立目錄時指定 US 或 EU 做為主要區域。

您可以在下列設定中，將多區域 (US 或 EU) 指定為主要區域：

如果 default_location 值區為：

• US 或 EU 多區域 bucket。
• 這些多區域中的單一區域 bucket (例如 us-central1 或 europe-west4)。
• 這些區域內的雙區域或自訂雙區域 bucket (例如 NAM4 或 EUR4)。

建立目錄時會定義主要副本，但您可以呼叫 FailoverCatalog，動態執行容錯移轉。詳情請參閱「建立目錄」。

如要將要求直接轉送至特定區域，以符合資料落地和主權規定，可以使用區域端點 (biglake.LOCATION.rep.googleapis.com)。詳情請參閱「Lakehouse 區域端點」。

從 BigQuery 查詢目錄

從 BigQuery 查詢 Lakehouse 執行階段目錄資料表時，請使用四部分命名結構，通常稱為 P.C.N.T：

• Project：擁有目錄的 Google Cloud 專案 ID。
• Catalog：Lakehouse 執行階段目錄的名稱。
• Namespace：Apache Iceberg 命名空間 (相當於 BigQuery 資料集)。
• Table：資料表名稱。

例如 my-project.lakehouse-catalog-id.my-namespace.my-table。

後續步驟

• 設定 Apache Iceberg REST 目錄端點
• 使用 Lakehouse 區域端點