Spark SQL 物化湖景參考資料

本文提供 Spark SQL 語法,用於在 Fabric 中建立、列出、重新命名及刪除實體化的湖泊視圖。

小提示

要建立你的第一個實體化湖景,請參考 「開始使用實體化湖景」。

建立具體化的湖景

您可以從任何資料表或湖屋內的另一個具體化湖景定義具體化湖景。

語法

CREATE [OR REPLACE] MATERIALIZED LAKE VIEW [IF NOT EXISTS] [workspace.lakehouse.schema].MLV_Identifier 
[( 
    CONSTRAINT constraint_name1 CHECK (condition expression1) [ON MISMATCH DROP | FAIL],  
    CONSTRAINT constraint_name2 CHECK (condition expression2) [ON MISMATCH DROP | FAIL] 
)]
[(
    REFRESH_HINT <hint_name> UNIQUE (<column1> [, <column2>, ...])
)]
[PARTITIONED BY (col1, col2, ... )] 
[COMMENT "description or comment"] 
[TBLPROPERTIES ("key1"="val1", "key2"="val2", ... )] 
AS select_statement 

備註

  • 目前 REFRESH_HINT 還在預覽階段。 欲了解更多關於使用刷新提示的細節,請參閱 「啟用實體化 lake 檢視中刪除與更新的最佳刷新(預覽)」。
  • 如果您的工作區名稱包含空格,請用反引號包圍:`My Workspace`.lakehouse.schema.view_name
  • 實體化的湖景名稱不區分大小寫,並轉換為小寫(例如, MyTestView 變成 mytestview)。

Arguments

參數 說明
OR REPLACE 覆蓋任何已存在的同名具現化湖泊視圖。 無法與 IF NOT EXISTS合併。
IF NOT EXISTS 只有當湖景尚未存在時才會產生實體化的湖景。 如果視圖已經被定義,該陳述即無誤成功。 無法與 OR REPLACE合併。
MLV_Identifier 具象化湖景的名稱。 可完全限定為 workspace.lakehouse.schema.name。
CONSTRAINT ... CHECK 定義了資料品質規則。 該 CHECK 子句指定了一個布林運算式,每一列必須滿足。 你可以定義多個限制條件。
ON MISMATCH 當某列違反限制時所採取的行動。 DROP 靜默移除該列; FAIL 以錯誤停止刷新。 預設值為 FAIL。
REFRESH_HINT 宣告一個或多個欄位,唯一識別列以進行更新與刪除的增量處理(預覽)。
PARTITIONED BY 欄位用來分割實體化的湖泊視圖,這能提升過濾讀取的查詢效能。
COMMENT 儲存在實體化湖景定義中的自由格式文本描述。
TBLPROPERTIES 鍵值對作為中繼資料儲存在實體化湖泊視圖中。
AS select_statement SELECT定義具體化湖景中資料的查詢。

範例

以下範例建立一個具資料品質約束、註解與分割的實體化湖景。 此 OR REPLACE 子句會覆寫任何同名的現有視圖。

CREATE OR REPLACE MATERIALIZED LAKE VIEW silver.cleaned_order_data
(
    CONSTRAINT valid_quantity CHECK (quantity > 0) ON MISMATCH DROP
)
PARTITIONED BY (category)
COMMENT "Cleaned order data joined from products and orders"
AS SELECT 
    p.productID,
    p.productName,
    p.category,
    o.orderDate,
    o.quantity,
    o.totalAmount
FROM bronze.products p INNER JOIN bronze.orders o
ON p.productID = o.productID

以下範例創造出更簡單的具體湖景。 若視圖已存在,此 IF NOT EXISTS 條款可防止錯誤,使部署腳本安全。

CREATE MATERIALIZED LAKE VIEW IF NOT EXISTS silver.products_with_sales AS
SELECT 
    p.productID,
    p.productName,
    p.category,
    CASE  
        WHEN COUNT(o.orderID) OVER (PARTITION BY p.productID) > 0 THEN TRUE  
        ELSE FALSE  
        END AS has_sales 
FROM bronze.products p LEFT JOIN bronze.orders o 
ON p.productID = o.productID

小提示

從您的 Lakehouse 管理具體化湖檢視重新整理

在你建立實體化湖景後,不要用筆記本來安排它們的刷新。 相反地,請使用湖邊別墅內建的兩項功能:

  • 血緣:Fabric 會根據你的具體化湖泊視圖定義,推導出它們之間的相依順序。 若要開啟系譜視圖,請在功能區中選取具體化湖泊檢視索引標籤,然後選取管理。 接著,你可以追蹤進行中的操作,檢查每個視圖的上游和下游相依關係。
  • 排程刷新:在同一個 「管理」 檢視中,建立一個或多個排程,以刷新所有實體化湖泊檢視或選定子集。 每個排程獨立執行,並依依賴順序刷新檢視,因此下游檢視總是從上游檢視讀取新資料。 Fabric 可以幫你重試暫時性失敗。

使用筆記本來撰寫並反覆修改你具體化的湖景定義。 讓 lineage 和排程刷新來處理排序、執行與重試——這樣資料可靠且可重複,維護程式碼更少。

使用 USING OneLake_Files 擷取檔案

除了從表格定義具體化的湖景外,你還可以定義一個直接從 OneLake 匯入 CSV 或 Parquet 檔案的湖景。 擷取檔案檢視會使用 USING OneLake_Files 搭配實體 OneLake 資料夾、OneLake 資料夾捷徑或單一檔案路徑。 你也可以選擇使用不含 FROM 的 AS SELECT 子句,在擷取來源資料時對其進行篩選、塑形及彙總。

下表顯示每種創作風格適用的語法:

層面 基於表格的實體化湖景 基於檔案的實體化湖泊視圖
Source 表格或其他具體化的湖景 實體 OneLake 資料夾、OneLake 資料夾捷徑或單一檔案
Definition AS select_statement USING OneLake_Files + OPTIONS + 可選的 FROM-less AS SELECT
格式 任何可查詢的資料表 CSV,帕奎特
架構 源自 SELECT schema_mode = DYNAMIC 或 FIXED
來源譜系 上游資料表/檢視 來源位置;當您需要每列檔案可追溯時,可選擇投影來源 __filepath__ 元資料欄位
典型層 銀、金 青銅
資料品質限制 支持 在攝取時有支撐

語法

CREATE [OR REPLACE] MATERIALIZED LAKE VIEW [IF NOT EXISTS] [workspace.lakehouse.schema].MLV_Identifier
[(
    CONSTRAINT constraint_name CHECK (condition) ON MISMATCH DROP | FAIL
)]
USING OneLake_Files
OPTIONS (
    'format' = 'csv' | 'parquet',
    'path'   = 'abfss://<workspace>@<host>/<lakehouse>/Files/<folder-or-file>',
    ['header' = 'true' | 'false',]
    ['delimiter' = '<char>',]
    [...]
)
[PARTITIONED BY (column_name [, ...])]
[COMMENT "description"]
[TBLPROPERTIES (
    'schema_mode'  = 'DYNAMIC' | 'FIXED',
    'refresh_mode' = 'APPEND_ONLY' | 'FULL' | 'MIRROR'
)]
[AS SELECT select_expression [...] [WHERE condition]
    [GROUP BY expression [, ...]] [HAVING condition]]

備註

請勿在檔案匯入FROM中指定AS SELECT子句。 來源已經受 USING OneLake_Files 和 path 選項約束。

選擇權參考

Option 適用對象 說明
format CSV,帕奎特 原始檔案格式。 支援的值為 csv 和 parquet。
path CSV,帕奎特 實體 OneLake 資料夾、OneLake 資料夾捷徑,或單檔 ABFSS 路徑。 巢狀子資料夾中的檔案會在建立檢視時以遞迴方式被擷取。 資料夾請在結尾加上斜線,單一檔案則請包含副檔名。
header CSV 表示每個檔案的第一列是否包含欄位名稱。 預設為 false。
delimiter CSV 欄位分隔符(例如, , 或 |)。 預設為逗號。
sep CSV delimiter 的別名。
quote CSV 用來引號值的字元。
escape CSV 字元用於逃離已引用的數值內的引號。
nullValue CSV 代表空值的字串。
ignoreLeadingWhiteSpace CSV 是否要從數值中移除前導空格。
ignoreTrailingWhiteSpace CSV 是否要移除數值中的後方空格。
multiLine CSV 是否一個引用的數值可以跨越多行。 預設為 false。
dateFormat CSV Java 日期模式用於解析日期值,例如 MM/dd/yyyy。
timestampFormat CSV Java 時間戳記模式用於解析時間戳記值。
encoding CSV 字元編碼,例如 UTF-8、 ISO-8859-1、 UTF-16、 Windows-1252。
comment CSV 用來將某一行標記為註解以略過的字元。
inferSchema CSV 是否要推斷欄位類型。 當 false時,欄位會被讀取為字串。 關閉推論時請使用 FIXED 模式模式。
columnNameOfCorruptRecord CSV 一個字串欄位名稱,該欄位接收格式錯誤列的原始文字。 此欄中的有效資料列包含 NULL。 在 AS SELECT 輸出中包含此欄。

Important

Fabric 負責處理格式錯誤的資料列。 不要設定 Spark CSV mode 選項。

TBLPROPERTIES 參考資料

Property 價值 說明
schema_mode DYNAMIC (預設), FIXED DYNAMIC 新增新發現的欄位,並在當檔案不包含既有欄位時寫入 NULL。 FIXED 在建立時固定結構描述,並拒絕後續變更。
refresh_mode APPEND_ONLY、FULL、MIRROR 對於資料夾,會 APPEND_ONLY 新增新檔案的列, FULL 將目前資料夾重新處理為快照,並 MIRROR 反映檔案的新增與刪除。 單一檔案來源使用 FULL 刷新語意。

範例

以下範例會將一個包含含有標頭列之 CSV 檔案的資料夾擷取至青銅檢視表。 每一列也會有一 __filepath__ 欄記錄讀取來源檔案。

CREATE MATERIALIZED LAKE VIEW bronze.raw_orders
USING OneLake_Files
OPTIONS (
    'format' = 'csv',
    'path'   = 'abfss://SalesWorkspace@onelake.dfs.fabric.microsoft.com/SalesLake.Lakehouse/Files/orders/',
    'header' = 'true'
)
TBLPROPERTIES (
    'schema_mode'  = 'DYNAMIC',
    'refresh_mode' = 'APPEND_ONLY'
);

接著,你可以建立下游的銀層和金層實體化 Lake 檢視,從 bronze.raw_orders 中選取資料;Fabric 會記錄相依性,並依序重新整理這些檢視。 若要追蹤檔案,請參見管理 Fabric 實體化湖泊視圖的沿革。

在擷取過程中過濾、轉換並驗證檔案

使用不含 FROM 子句的 AS SELECT 來選取欄位、篩選資料列、轉換值的型別、新增計算欄位、彙總資料,或套用視窗函式。 檔案擷取限制會針對投影輸出執行,因此限制可以參考計算出的別名。

以下範例捕捉格式錯誤的資料列,套用列層級資料品質規則,過濾輸入,並分割具體化的輸出:

CREATE MATERIALIZED LAKE VIEW silver.valid_orders
(
    CONSTRAINT positive_amount
        CHECK (order_amount > 0) ON MISMATCH DROP
)
USING OneLake_Files
OPTIONS (
    'format' = 'csv',
    'path' = 'abfss://SalesWorkspace@onelake.dfs.fabric.microsoft.com/SalesLake.Lakehouse/Files/orders/',
    'header' = 'true',
    'multiLine' = 'true',
    'dateFormat' = 'MM/dd/yyyy',
    'timestampFormat' = 'MM/dd/yyyy HH:mm:ss',
    'encoding' = 'ISO-8859-1',
    'comment' = '#',
    'columnNameOfCorruptRecord' = '_corrupt_record'
)
PARTITIONED BY (region)
COMMENT "Valid orders ingested from CSV"
TBLPROPERTIES (
    'schema_mode' = 'DYNAMIC',
    'refresh_mode' = 'FULL'
)
AS SELECT
    order_id,
    region,
    CAST(amount AS DECIMAL(18,2)) AS order_amount,
    CASE WHEN amount >= 1000 THEN 'high' ELSE 'standard' END AS order_band,
    _corrupt_record,
    __filepath__,
    current_timestamp() AS ingested_at;

查詢擷取的列以供檢查或修復:

SELECT
    _corrupt_record,
    __filepath__,
    ingested_at
FROM silver.valid_orders
WHERE _corrupt_record IS NOT NULL;

你也可以直接從檔案建立聚合或視窗化的實體化結果:

CREATE MATERIALIZED LAKE VIEW gold.sales_by_region
USING OneLake_Files
OPTIONS (
    'format' = 'parquet',
    'path' = 'abfss://SalesWorkspace@onelake.dfs.fabric.microsoft.com/SalesLake.Lakehouse/Files/sales/'
)
TBLPROPERTIES ('schema_mode' = 'DYNAMIC', 'refresh_mode' = 'FULL')
AS SELECT
    region,
    COUNT(*) AS order_count,
    SUM(amount) AS total_amount,
    AVG(amount) AS average_amount
GROUP BY region
HAVING SUM(amount) > 0;

支援的表達式包括標準的 Spark SQL 算術、彙總、統計、視窗及排名函式。

匯入單一檔案

設定 path 成 CSV 或 Parquet 檔案,而不是資料夾。 單一檔案來源使用 FULL 刷新語意,因此替換檔案會取代實體化的結果。

CREATE MATERIALIZED LAKE VIEW bronze.monthly_snapshot
USING OneLake_Files
OPTIONS (
    'format' = 'parquet',
    'path' = 'abfss://SalesWorkspace@onelake.dfs.fabric.microsoft.com/SalesLake.Lakehouse/Files/snapshots/2026-08.parquet'
)
TBLPROPERTIES (
    'schema_mode' = 'FIXED',
    'refresh_mode' = 'FULL'
);

備註

當你使用 FIXED schema 時,且來源資料夾在初始 CREATE時包含多個不同結構的檔案,視圖會失敗,因為它無法對照單一固定結構。 將 FIXED 視圖指向共用同一結構描述的檔案,或使用 DYNAMIC。 這是一個已知的限制,類似於捷徑轉換中的固定模式行為。

Important

目前不接受包含原始空格或 %20 的來源路徑。 你可以使用 OneLake 資料夾捷徑作為來源:建立時會匯入捷徑根資料夾及其巢狀資料夾中可用的檔案。 管理式刷新會發現在快捷鍵根目錄新增的檔案,但不會以遞迴方式發現巢狀捷徑資料夾下新增的檔案。

小提示

若要按需重新處理整個來源資料夾,請執行 REFRESH MATERIALIZED LAKE VIEW <name> FULL;。 和資料表檢視一樣,不要在筆記本中協調持續刷新——使用 Lineage 和 排程刷新 來自動擷取新檔案。

取得具體化的湖景清單

要取得所有具體化湖泊視圖的清單,請使用以下語法:

SHOW MATERIALIZED LAKE VIEWS <IN/FROM> Schema_Name;

例如,若要列出結構中 silver 所有具體化的湖泊景觀:

SHOW MATERIALIZED LAKE VIEWS IN silver;

若要使用 Skills for Fabric 列出實體化湖檢視,請替換佔位符並使用此提示:

Use Skills for Fabric. In workspace <workspace-name> and lakehouse
<lakehouse-name>, use Spark SQL to run
`SHOW MATERIALIZED LAKE VIEWS IN <schema-name>` and return schema-qualified
names. Don't change tables, views, notebook definitions, or refresh settings.
If a helper notebook is needed, show its name and purpose and wait for my
confirmation before creating it.

擷取建立具體化湖景的陳述式

要取得 CREATE 具體化湖景的語句,請使用以下語法:

SHOW CREATE MATERIALIZED LAKE VIEW MLV_Identifier;

例如,要取得 的 products_with_sales定義:

SHOW CREATE MATERIALIZED LAKE VIEW products_with_sales;

更新具現化資料湖視圖

若要修改實體化湖景的定義(例如 SELECT 查詢、限制或分割),請使用 CREATE或REPLACE 指令。 或者,你也可以 刪除 現有的檢視並重新建立。

將實體化的湖景重新命名

若要重新命名已具現化的湖景,請使用指令 ALTER MATERIALIZED LAKE VIEW 。 語法為:

ALTER MATERIALIZED LAKE VIEW MLV_Identifier RENAME TO MLV_Identifier_New;

例如,要重新命名 products_with_sales:

ALTER MATERIALIZED LAKE VIEW products_with_sales RENAME TO products_with_sales_v2;

備註

此 ALTER MATERIALIZED LAKE VIEW 指令僅支援重新命名。 若要修改定義或其他屬性(如 SELECT 查詢、限制或分割),請參見 「更新實體化湖景」。

刪除實體化的湖景

你可以透過 lakehouse 物件總管中的 刪除 選項或執行 DROP 指令刪除實體化的湖景。 語法為:

DROP MATERIALIZED LAKE VIEW MLV_Identifier;

例如,要刪除 products_with_sales:

DROP MATERIALIZED LAKE VIEW products_with_sales;

備註

卸除或重新命名具體化湖檢視會影響譜系檢視和排程重新整理。 請務必更新所有相依具體化湖景中的參考。

目前的限制

以下限制適用於實體化湖景的 Spark SQL 語句:

  • Schema 名稱 — 不支援全大寫的 Schema 名稱(例如 MYSCHEMA)。 使用混合大小寫或小寫。
  • 無資料操作語言(DML)陳述式 — 您無法對實體化湖泊檢視執行 INSERT、UPDATE 或 DELETE 陳述式。 資料僅由 SELECT 定義中的查詢填充。
  • 不支援時間旅行查詢 — SELECT 物化湖泊視圖定義中的查詢不能使用 Delta Lake 時間旅行 語法(例如 VERSION AS OF 或 TIMESTAMP AS OF)。
  • 不支援使用者自訂函數 — 在定義物化湖景的查詢中,不支援 SELECT 使用者自訂函數(UDF)。
  • 沒有暫存檢視作為來源 — 查詢 SELECT 可以參考資料表及其他實體化的湖泊檢視,但不能參考暫存檢視。
  • 會話層級的 Spark 屬性 — 在會話層級設定的 Spark 配置屬性(例如 spark.conf.set(...))不會在排程重新整理時套用。 請在湖倉或工作區層級設定屬性。
  • 檔案擷取 — 檔案匯入檢視僅支援 CSV 與 Parquet。 FIXED如果 -schema 檢視在建立時原始資料夾中存放的檔案結構不同,則該檢視失敗。 來源路徑不能包含空格。 OneLake 資料夾捷徑支援作為來源,但受管理刷新不會遞迴地發現巢狀捷徑資料夾下新增的檔案。