啟用對串流資料表與實體化檢視的外部資料存取

如果您已啟用 Unity Catalog 的外部資料存取，就可以為管線管理和獨立的具體化檢視表及串流表新增外部資料存取。這使得外部 Delta 和 Iceberg 用戶端能透過 Unity Catalog 和 Iceberg 目錄的 REST API 存取你的資料集，而不需要完整的資料副本。

外部資料存取適用於由 Lakeflow 管線管理的資料集，以及獨立的實體化檢視與串流資料表。

能力

使用外部資料存取會暴露 Azure Databricks 中相同的資料，供管線管理及獨立實體化檢視與串流資料表使用，且不會建立資料的重複。這在效能與功能上具備以下特性：

無需資料複製： 外部存取啟用時，無需複製完整資料集。
透過 API 進行外部存取： 使用 Delta Lake 或 Iceberg API 閱讀實體化的檢視與串流資料表。
寫後讀一致性： 外部讀者可在資料集更新後存取最新資料，確保資料不會陳舊。重新整理後即可立即取得更新。
單一表格物件： 資料集在外部以 管理資料表 的形式出現，名稱與 Unity Catalog API 中的來源資料集相同。
低成本： 由於完整資料集未被複製，提供外部存取的開銷較低。

要求

你的資料集需求如下：

Unity 目錄： 你的串流資料表和實體化檢視必須使用 Unity Catalog。
Databricks 執行時版本： 你必須使用 Databricks Runtime 17.3 及以上版本。
預設發佈模式： 外部可讀性僅支援預設發佈模式。若要使用外部可讀性，請遷移到預設的發佈模式。依賴外部元資料的功能，如實體化檢視 CDF，則可在舊有發佈模式下運作。

您的客戶需求包括：

Delta API 版本： 用戶端必須支援 Delta Lake API 4.0.0 或以上版本，包括刪除向量，且必須使用 Unity 目錄 API 才能存取。
Iceberg API 版本： 或者，客戶端可使用支援 Iceberg v3 規範的 Iceberg 目錄 API 存取。
Unity 目錄權限： 外部讀取資料集的主體必須對結構擁有外部 USE SCHEMA 權限，對 SELECT 資料表也擁有權限。

備註

如果您的客戶端不支援這些需求，您也可以使用相容模式，該模式支援所有 Delta 與 Iceberg 客戶端，但需建立完整資料集副本。

如何啟用資料集存取權限

啟用外部存取資料集有兩個步驟。

啟用外部元資料，可選擇管線設定或資料表屬性。當兩者皆已設定時，表格層級設定優先於管線設定，且同時支援管線管理及獨立串流資料表及實體化檢視。
- 管線設定： 將 pipelines.externalMetadata.enabled 設為 true，即可為管線中的所有資料集啟用外部中繼資料。使用 Databricks SQL 建立的獨立實體化檢視與串流資料表沒有管線配置;改用 table 屬性。
  
  管線設定介面
  
  在管線設定中，請完成以下步驟：
  1. 打開你的管線並點選設定。
  2. 在設定中，新增一對鍵值：鍵pipelines.externalMetadata.enabled、值true。
  3. 點選 [儲存]。
  管線設定 JSON
  
  在管線 JSON 的 configuration 區段中，新增：
```
{
  "configuration": {
    "pipelines.externalMetadata.enabled": "true"
  }
}
```
- 表格屬性： 將以下屬性加入串流表或具體化視圖定義。關於 Lakeflow Connect 管線，請參閱設定 Delta 表格屬性。
```
CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
TBLPROPERTIES('pipelines.externalMetadata.enabled' = 'true')
```
儲存設定後，執行或重新啟動管線以套用以下變更：
- 已觸發的管線：執行管線一次。
- 連續管線：停止並重新啟動管線。
對於獨立的 Databricks SQL 物件，請使用 CREATE OR REPLACE MATERIALIZED VIEW 或 CREATE OR REFRESH STREAMING TABLE 搭配 table 屬性。建立或重新整理陳述式會套用該屬性。

如果你打算用現代 Iceberg 用戶端讀取資料集，除了外部元資料屬性外，還要新增以下 UniForm Iceberg V3 屬性。關於 Lakeflow Connect 管線，請參閱設定 Delta 表格屬性。

房產	使用
`'pipelines.externalMetadata.enabled' = 'true'`	啟用桌面的外部存取權限。當兩者同時設定時，這個表格層級設定優先於管線配置。
`'delta.columnMapping.mode' = 'name'`	Iceberg 需要進行欄位映射。
`'delta.enableRowTracking' = 'true'`	為 Iceberg 讀取作業啟用資料列追蹤。
`'delta.universalFormat.enabledFormats' = 'iceberg'`	啟用 Iceberg 讀取功能。
`'delta.enableIcebergCompatV3' = 'true'`	使用 Iceberg V3 進行 Iceberg 讀取。

CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableRowTracking' = 'true',
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg',
  'pipelines.externalMetadata.enabled' = 'true')

對於具體化的視圖，你可以使用等效 USING ICEBERG 的語法。

CREATE OR REFRESH MATERIALIZED VIEW tbl_name USING ICEBERG

對於管線管理的資料集，請使用上述管線更新指令來套用 Iceberg 屬性。對於獨立的 Databricks SQL 物件，請重新執行帶有更新屬性的物件定義。對實體化檢視使用 CREATE OR REPLACE MATERIALIZED VIEW，對串流資料表使用 CREATE OR REFRESH STREAMING TABLE。要查看資料集的屬性，請使用 DESCRIBE DETAIL 或 DESCRIBE EXTENDED SQL 語句。

外部資料存取故障排除

如果你認為外部元資料已經過時，擁有 MODIFY 資料表權限的主體可以用 Databricks Runtime 17.3 或更高版本手動觸發共享叢集運算的元資料更新：

REPAIR TABLE <catalog>.<schema>.<table-name> SYNC METADATA;

你可以在目錄總管介面的表格細節頁面中檢查 Iceberg 元資料的存在。或者，您也可以在 SQL 編輯器或 Azure Databricks 筆記本中執行以下指令：

DESCRIBE DETAIL <catalog>.<schema>.<table-name>;
DESCRIBE EXTENDED <catalog>.<schema>.<table-name>;

針對串流資料表，比較 Iceberg 的中繼資料版本與最新的串流資料表版本。具體化視圖的版本比較尚未提供。

從外部用戶端讀取資料

以下章節提供如何從不同客戶端和環境中讀取資料集的範例。

關於設定細節，請參見 Delta 用戶端存取與 Iceberg 用戶端存取。

使用 Unity REST API 搭配 Spark Delta 閱讀器

請使用 Apache Spark™ 4.0 或更新版本。你可以從 https://spark.apache.org/downloads.html 下載。

根據你的雲端供應商，執行以下指令啟動一個包含 Delta 4.0 和 Unity Catalog 的 Spark SQL shell。

AWS

bin/spark-sql \
    --packages org.apache.spark:spark-hadoop-cloud_2.13:4.0.0,io.unitycatalog:unitycatalog-spark_2.13:0.3.1 \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.hadoop.fs.s3.impl=org.apache.hadoop.fs.s3a.S3AFileSystem \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

Azure雲服務

bin/spark-sql \
    --packages org.apache.hadoop:hadoop-azure:3.3.6,io.unitycatalog:unitycatalog-spark_2.13:0.3.1 \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

GCP

bin/spark-sql \
    --packages io.unitycatalog:unitycatalog-spark_2.13:0.3.1  \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.hadoop.fs.gs.impl=com.google.cloud.hadoop.fs.gcs.GoogleHadoopFileSystem \
    --conf spark.hadoop.fs.AbstractFileSystem.gs.impl=com.google.cloud.hadoop.fs.gcs.GoogleHadoopFS \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

從 SQL shell 中，你現在可以用 Spark SQL 存取你的資料集。例如：
```
spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;
```

使用 Snowflake Iceberg 讀取器

在 Snowflake 裡，你可以使用 Iceberg Reader。這需要 Snowflake 支援 Iceberg v3。

在 Snowflake 裡架設 Iceberg REST 目錄。

CREATE OR REPLACE CATALOG INTEGRATION my_uc_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest'
    CATALOG_NAME = '<uc-catalog-name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<PAT>'
  )
  ENABLED = TRUE;

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = 'my_uc_int'
  CATALOG_TABLE_NAME = '<uc-table-name>';

從 Snowflake SQL 存取你的資料集。

ALTER ICEBERG TABLE my_table REFRESH;
SELECT * FROM my_table;

使用 Iceberg REST 目錄搭配 Spark Iceberg 閱讀器

請使用 Apache Spark™ 4.0 或更新版本。你可以從 https://spark.apache.org/downloads.html 下載。

在 AWS 中，執行以下指令以啟動 Iceberg v3 的 Spark SQL shell。

bin/spark-sql \
  --packages org.apache.iceberg:iceberg-spark-runtime-4.0_2.13:1.10.0,org.apache.iceberg:iceberg-aws-bundle:1.10.0 \
  --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
  --conf spark.sql.catalog.<uc-catalog-name>=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.<uc-catalog-name>.io-impl=org.apache.iceberg.aws.s3.S3FileIO \
  --conf spark.sql.catalog.<uc-catalog-name>.type=rest \
  --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url>/api/2.1/unity-catalog/iceberg-rest \
  --conf spark.sql.catalog.<uc-catalog-name>.token='<PAT>' \
  --conf spark.sql.catalog.<uc-catalog-name>.warehouse=<uc-catalog-name> \
  --conf spark.sql.iceberg.vectorization.enabled=false

從 Spark SQL 存取你的資料集。

spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;

從相容模式遷移

如果你目前用相容模式分享資料集，可以遷移到使用外部資料存取模式。

請依照「如何啟用資料集存取」中的步驟啟用此功能。
關閉相容模式。請參見「停用相容模式」

局限性

以下是串流資料表和實體化檢視在外部資料存取方面的已知限制。

外部寫入： 不支援對管線資料集進行外部寫入。
Path-Based 存取： 需要路徑存取（直接透過儲存位置而非 UC API 介面讀取）的外部讀取器則不被支援。為了支援路徑存取，可以使用相容模式，該模式確實支援路徑存取，但需要完整的資料集副本。
安全特性： 不支援外部讀取的 列級安全性 或 欄級遮蔽 。
時間旅行：不支援透過此功能進行時間旅行。
目錄提交（測試版）：目錄提交與外部資料存取不相容。若要在串流資料表或實體化視圖上使用外部資料存取，必須先停用目錄提交。
Fabric：不支援從 Microsoft Fabric 讀取資料。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-09-11