具體化湖檢視中的數據品質

在 medallion 架構中,你必須在每個階段都嚴格執行資料品質。 數據品質不佳可能會導致不正確的深入解析和作效率不佳。

本文說明如何在 Microsoft Fabric 中實作實體化湖泊視圖(MLV)的資料品質檢查。

實作數據品質

列層級限制會單獨驗證每一列(例如,「customerName 在此列中不為 null」)。 然而,許多真正的品質問題是整個 欄的性質:

  • 唯一性——主鍵或商業鍵(例如 order_id)沒有重複值。
  • 完備性 — 像 customer_id 這樣的關鍵欄位不包含 null。
  • 統計形狀 ——欄位的平均值、大小或分布都維持在預期範圍內。

在刷新時發現這些問題,可以防止不良資料透過銅→銀→金鏈向下傳播,並且每次運行都能獲得可審計的高品質訊號。

列層級資料品質約束

在 Fabric 中的物化湖泊檢視(MLV)中,透過定義視圖的條件約束來維持資料品質。 若無明確檢查,輕微資料問題可能增加處理時間或導致管線失效。

當一列違反限制時,你可以使用以下動作之一:

  • FAIL:在第一次違反限制時停止 MLV 刷新。 這是預設行為,即使你沒有特別說明 FAIL。

  • DROP:繼續處理並移除違反限制的紀錄。 血統視圖顯示被丟棄紀錄的數量。

備註

如果你在 MLV 中同時定義了 DROP 和 FAIL 動作,FAIL 動作會優先。

在實體化湖景中定義資料品質檢查

當你建立實體化的湖景時,可以定義約束——資料品質規則,在刷新時驗證每一列。 約束是一種布林運算式,每一列都必須滿足。 通過的列會寫入輸出表。 當資料列失敗時,會按照當違規發生時的設定來處理:要麼靜默丟棄,要麼導致整個更新失敗。

下列範例會定義 條件約束 cust_blank,這會檢查欄位是否 customerName 不是 Null。 該限制排除了帶有空 customerName 值的列。

CREATE OR REPLACE MATERIALIZED LAKE VIEW IF NOT EXISTS silver.customers_enriched  
(CONSTRAINT cust_blank CHECK (customerName is not null) on MISMATCH DROP)
AS
SELECT
    c.customerID,
    c.customerName,
    c.contact, 
    CASE  
       WHEN COUNT(o.orderID) OVER (PARTITION BY c.customerID) > 0 THEN TRUE  
       ELSE FALSE  
    END AS has_orders 
FROM bronze.customers c LEFT JOIN bronze.orders o 
ON c.customerID = o.customerID;

系統內建函數

內建的 Spark/SQL 函式如 UPPER()、LOWER()、TRIM()、COALESCE()、INITCAP(及 DATE_FORMAT() 在所有 MLV 情境中均被完整支援,適用於 CREATE 與 LINEAGE 刷新。

CREATE MATERIALIZED LAKE VIEW sample_lakehouse.silver.names (
CONSTRAINT substring_check
CHECK (SUBSTRING(name, 1, 2) = 'Al') ON MISMATCH drop
) AS
SELECT id, name
FROM (VALUES (1, 'Alice'), (2, 'Bob'), (3, 'Ann')) AS t(id, name)

備註

系統功能是最簡單且最可靠的選項。 它們不需註冊,適用於所有情境,且在 LINEAGE 更新期間獲得完整支援。

UDF – 在同一個筆記本中定義並註冊

在同一筆記本中以 spark.udf.register() 註冊的 UDF,在所有情境下都支援 CREATE。 對於 LINEAGE 刷新,只支援 PySpark 環境,因為 UDF 定義在排程的筆記本執行中執行。

from pyspark.sql import SparkSession
from pyspark.sql.types import StringType
from pyspark.sql.functions import expr

spark = SparkSession.builder.getOrCreate()

# UDF: Extract domain from email
def extract_email_domain(email):
    if email is None or '@' not in email:
        return None
    return email.split('@')[1]

# Registration
spark.udf.register(
    "udf_email_domain",
    extract_email_domain,
    StringType()
)

@fmlv.materialized_lake_view(
    name="udf_testing_silver.mlv_high_value_customers",
    comment="High-value customers identified by UDF criteria",
    table_properties={"delta.enableChangeDataFeed": "true"}
)
def mlv_high_value_customers():
    return spark.sql("""
        SELECT 
            c.customer_id,
            c.name,
            c.email,
            udf_email_domain(c.email) as email_domain,
            c.segment,
            c.lifetime_value,
            total_transactions.total_amount,
            total_transactions.txn_count
        FROM udf_testing_bronze.customers c
        INNER JOIN (
            SELECT 
                customer_id,
                SUM(amount) as total_amount,
                COUNT(*) as txn_count
            FROM udf_testing_bronze.transactions
            WHERE udf_is_positive(amount)
            GROUP BY customer_id
            HAVING SUM(amount) > 1000
        ) total_transactions ON c.customer_id = total_transactions.customer_id
        WHERE udf_validate_customer(c.email, c.age)
            AND c.segment IN ('premium', 'vip')
    """)

print("✓ Created mlv_high_value_customers")

第三方函式庫 - Pandas UDFs

第三方函式庫如 Pandas UDF 允許以向量化處理實作資料品質規則。 它們能實現進階驗證,如自訂商業邏輯、統計檢查或模式偵測,這些是內建函式無法實現的。 這有助於在 MLV 建立與更新時建立可擴展且可重用的資料品質約束。

  import fmlv
  from pyspark.sql.types import StructType, StructField, IntegerType, TimestampType, StringType, DoubleType, BooleanType
  from datetime import datetime

  import pandas as pd
  from pyspark.sql.types import BooleanType
  def pandas_check_impl(val):
    # Reject if value < median of [100, 200, 300]
    return val >= pd.Series([100, 200, 300]).median()
  spark.udf.register("pandas_check", pandas_check_impl, BooleanType())

  @fmlv.materialized_lake_view(
    name="silver.pyspark_from_two_sqlmlv_inner_pandas",
    comment="PySpark MLV INNER JOIN using pandas-based constraint and DROP violations"
  )
  @fmlv.check(
    name="dq_pandas_check",
    condition="pandas_check(l3)",
    action="DROP"
  )
  def pyspark_from_two_sqlmlv_inner_pandas():
    # Define the function

    # Register the function as a Spark UDF

    # Read source tables
    df1 = spark.table("silver.base_sqlmlv")
    df2 = spark.table("silver.base_sqlmlv")

    # Rename columns for unique join
    df_left = df1.select([df1[col].alias(f"l{i+1}") for i, col in enumerate(df1.columns)])
    df_right = df2.select([df2[col].alias(f"r{i+1}") for i, col in enumerate(df2.columns)])

    # Perform INNER JOIN
    df = df_left.join(df_right, df_left.l1 == df_right.r1, "inner")
    return df


  df = spark.table("silver.pyspark_from_two_sqlmlv_inner_pandas")
  # All amounts should be >= median (200)
  assert all(df.select("l3").rdd.map(lambda r: r[0] >= 200).collect()), "Unexpected low-value rows found"
  print("PySpark MLV INNER JOIN with pandas-based DQ DROP passed")

自訂函式庫 – Python wheel (.whl)

以 jar 檔案或輪子檔案形式打包的函式可安裝於 Fabric 叢集(透過環境設定),並用於 MLV 定義中。 CREATE 與 LINEAGE REFRESH 支援 PySpark 環境。 更多細節請參閱 「管理 Fabric 環境中的自訂函式庫 」。

  %%pyspark
  import fmlv
  from pyspark.sql.types import StructType, StructField, IntegerType, TimestampType, StringType, DoubleType, BooleanType
  from datetime import datetime

  from pyspark.sql.types import BooleanType
  from custom_dq_lib import threshold_check
  def custom_check_impl(val):
    return threshold_check(val, threshold=200)
  spark.udf.register("custom_check", custom_check_impl, BooleanType())

  @fmlv.materialized_lake_view(
    name="silver.pyspark_from_two_sqlmlv_inner_custom_whl",
    comment="PySpark MLV INNER JOIN using custom DQ library and DROP violations",
    replace=True
  )
  @fmlv.check(
    name="dq_custom_check",
    condition="custom_check(l3)",
    action="DROP"
  )
  def pyspark_from_two_sqlmlv_inner_custom():
    # Wrap the custom function as Spark UDF


    # Read source tables
    df1 = spark.table("silver.base_sqlmlv")
    df2 = spark.table("silver.base_sqlmlv")

    # Rename columns for unique join
    df_left = df1.select([df1[col].alias(f"l{i+1}") for i, col in enumerate(df1.columns)])
    df_right = df2.select([df2[col].alias(f"r{i+1}") for i, col in enumerate(df2.columns)])

    # Perform INNER JOIN
    df = df_left.join(df_right, df_left.l1 == df_right.r1, "inner")
    return df


    df = spark.table("silver.pyspark_from_two_sqlmlv_inner_custom_whl")
    # All amounts should be >= threshold (200)
    assert all(df.select("l3").rdd.map(lambda r: r[0] >= 200).collect()), "Unexpected low-value rows found"
    print("PySpark MLV INNER JOIN with custom DQ library passed")

Fabric 使用者資料功能

Fabric 使用者資料功能(UDF)由 Fabric 工作空間集中定義與管理。 它們可在任何筆記本或管道中使用,且每個會話都不需要重新註冊,非常適合用於生產型 MLV 管道。 此功能僅支援在 PySpark 環境中的 CREATE 和 LINEAGE 刷新。 在此了解更多關於使用者資料功能。 欲了解更多資訊,請參閱 Fabric 使用者資料功能總覽。

  %%pyspark
  import fmlv
  from pyspark.sql import functions as F
  from notebookutils import udf

  myFuncs = udf.getFunctions("UserDataFunction_1")

  def add_greeting_column(df):
    pdf = df.toPandas()
    pdf["greeting"] = pdf["name"].apply(lambda n: myFuncs.hello_fabric(n))
    return spark.createDataFrame(pdf)
  import fmlv
  from pyspark.sql.types import StructType, StructField, IntegerType, StringType, DoubleType

  # -------------------------------------------------------------
  # Define base PySpark MLV (no SQL)
  # -------------------------------------------------------------
  @fmlv.materialized_lake_view(
    name="silver.base_pysparkmlv",
    comment="Base MLV created using PySpark",
    replace=True
  )
  def base_pysparkmlv():

    schema = StructType([
        StructField("id", IntegerType(), True),
        StructField("name", StringType(), True),
        StructField("amount", DoubleType(), True),
        StructField("country", StringType(), True)
    ])

    data = [
        (1, "Alice", 100.0, "US"),
        (2, "Bob", 200.0, "UK"),
        (3, "Charlie", 300.0, "UK")
    ]

    return spark.createDataFrame(data, schema)

  @fmlv.materialized_lake_view(
    name="silver.mlv_udfn_null_test",
    replace=False
  )
  @fmlv.check(
    name="null_check",
    condition="greeting IS NOT NULL",
    action="FAIL"
  )
  def mlv_udfn_null_test():
    df = spark.table("silver.base_pysparkmlv")
    return add_greeting_column(df)

欄位層級資料品質檢查

運作原理

用三個 Python 裝飾器定義欄位層級的資料品質(DQ)檢查,這些工具放在筆記本儲存格裡,與 MLV 定義分開:

裝飾項目 Purpose
@fmlv.dq_suite(mlv_name=…) 針對已命名且已存在的 MLV 註冊資料品質套件,並載入其資料供檢查執行。
@fmlv.validate("<fn>", "FAIL"\|"WARN") 執行一個驗證檢查,包含通過/失敗結果及所選動作(見下文 控制結果)。
@fmlv.analyze("<fn>") 執行剖析程序,計算欄位指標(大小、完整性、平均值等)。 它只產生指標——絕不會讓執行失敗。

由於套件會依名稱鎖定 MLV,因此資料品質作業可獨立於 MLV 定義進行管理、執行與排程,而且你可以在不觸發刷新的情況下執行檢查。

步驟 1:設定執行階段

在定義欄位層級的資料品質檢查之前,先設定 Fabric 執行時版本的相依關係。

2.0 之前的 Fabric 執行環境

下載 PyDeequ 1.7.0 wheel,並將其上傳為自訂函式庫,放進你的 Fabric 環境中。 相關說明請參見「上傳自訂函式庫」。

Fabric 執行環境 2.0 或更新版本

新增以下 Spark 屬性:

Spark 屬性 Value
spark.driver.extraClassPath /opt/deequ/jars/*
spark.executor.extraClassPath /opt/deequ/jars/*

你可以在環境或筆記本中加入這些屬性:

步驟 2:定義欄位層級檢查

在此範例中,定義由 mlv_name 中的 @fmlv.dq_suite 指定之 sales_db.daily_orders 實體化 Lake view 的欄位層級資料品質檢查。

將套件註冊及其入口函式集中在單一資料品質儲存格中。 以下範例在一次驗證中執行 兩次檢查 —— customer_id 必須是完全的(無空)且 order_id 必須唯一:

import os
os.environ["SPARK_VERSION"] = "3.5"   # works on both 3.5 and 4.1
import fmlv

# Entry function — returns a PyDeequ VerificationResult DataFrame
def completeness_and_uniqueness(df):
    from pydeequ.checks import Check, CheckLevel
    from pydeequ.verification import VerificationSuite, VerificationResult

    check = Check(spark, CheckLevel.Error, "Completeness & Uniqueness")
    result = (
        VerificationSuite(spark)
        .onData(df)
        .addCheck(
            check.isComplete("customer_id")   # check 1: no nulls
                 .isUnique("order_id")        # check 2: no duplicates
        )
        .run()
    )
    return VerificationResult.checkResultsAsDataFrame(spark, result)
# Data quality cell — separate from the MLV definition
@fmlv.dq_suite(mlv_name="sales_db.daily_orders", replace=True)
@fmlv.validate("completeness_and_uniqueness", "FAIL")
def daily_orders_dq():
    pass

加入指標而不使此次執行失敗。 堆疊一個 @fmlv.analyze 遍來計算欄位指標(大小、完整性、平均值等),以達成可觀察性。 分析結果始終被記錄,且不會阻擋執行——這在驗證規則仍在演進時非常有用。

import os
os.environ["SPARK_VERSION"] = "3.5"   # works on both 3.5 and 4.1
import fmlv

# Entry function — returns a PyDeequ AnalyzerContext metrics DataFrame
def column_profiling(df):
    from pydeequ.analyzers import AnalysisRunner, AnalyzerContext, Size, Completeness, Mean
    result = (
        AnalysisRunner(spark)
        .onData(df)
        .addAnalyzer(Size())
        .addAnalyzer(Completeness("customer_id"))
        .addAnalyzer(Mean("amount"))
        .run()
    )
    return AnalyzerContext.successMetricsAsDataFrame(spark, result)
# Data quality cell — separate from the MLV definition
@fmlv.dq_suite(mlv_name="sales_db.daily_orders", replace=True)
@fmlv.validate("completeness_and_uniqueness", "FAIL")
@fmlv.analyze("column_profiling")
def daily_orders_dq():
    pass
掌控結果:失敗 vs. 警告

行動 @fmlv.validate 決定檢定失敗時的處理:

  • FAIL — 檢查失敗會導致資料品質執行失敗,並 阻擋依賴此項檢查結果的下游 MLV。 用它來處理像主鍵和必填欄位這類硬性約束。
  • WARN — 失敗會被記錄,但執行仍然成功,且下游的 MLV 不會 被阻擋。 用它來做軟性或建議性規則。

步驟 3:在排程中啟用資料品質檢查

選擇欄位層級檢查是否作為刷新排程的一部分執行。 在進階設定中,建立新排程體驗的資料品質檢查下拉選單提供兩個選項:

  • 每次執行後都要檢查 ——資料品質套件會在該排程中每次 MLV 刷新完成後自動執行。
  • 沒有檢查 — 該時程會跳過資料品質;MLV 仍會依其排程頻率重新整理。

建立新排程的進階設定截圖,資料品質檢查下拉選單設為每次運行後檢查。

排程的進階設定中的資料品質檢查設定——選擇每次執行後檢查或不檢查。

檢查失敗如何影響流程

在資料譜系檢視中,對 gold.daily_dq_reportusage 執行的資料品質檢查是以 FAIL 定義,且已失敗。 因此,其下游依賴分支 gold.monthly_dq_report…會自動 略過,而獨立分支(gold.expected_regions、gold.region_mlv_dq_rep…)則正常完成。

血統檢視的截圖顯示一個失敗的資料品質節點阻擋了其下游依賴節點,使其下游依賴節點因此被跳過,而兄弟分支則已完成。

資料 FAIL 品質檢查會中止整個流程鏈——失敗節點的下游依賴節點會被跳過,但獨立分支會繼續。

執行順序。 當一個套件同時擁有這兩種類型時,所有 @fmlv.validate 函式會先執行(依定義順序),然後才是所有 @fmlv.analyze 函式。 記錄失敗的檢查並繼續執行;整體結果在所有檢查完成後決定——只有當 FAIL-action 檢查失敗時,此次執行才會失敗。

步驟四:檢視並分析資料品質報告

執行歷史反映每次執行的資料品質是開啟還是關閉。 你也可以隨時從筆記本隨需執行套件,獨立於任何重新整理。

在血統檢視中選擇任一 MLV 節點,並開啟詳細面板的 資料品質 分頁,即可查看該次執行的結果:

  • 計算指標 — 由 Deequ 分析器計算的欄位層級彙總指標(例如 Completeness 的 region)。
  • 驗證結果 — 總 檢查次數、 通過次數與 失敗次數的摘要,後附每個限制及其通過/失敗 狀態,讓您能精確看到哪條規則通過或失敗。

資料品質細節面板的截圖,顯示計算出的指標與驗證結果,並顯示每個約束的通過/失敗狀態。

資料品質分頁顯示所選 MLV 執行的計算指標與各約束驗證結果。

MLV 執行紀錄也會顯示每次執行的資料品質狀態——成功、失敗,或當沒有套件執行時不顯示任何指示——讓你能一眼發現問題執行,無需打開每個節點。

支援的檢查與分析器

由於欄位層級的 DQ 由開源的 Deequ 函式庫驅動,你可以在入口函式中使用 Deequ 的所有檢查和分析器。 驗證檢查 (與 @fmlv.validate一起使用)是 Check 產生通過/失敗結果的約束; 分析器 (與 @fmlv.analyze一起使用)計算一個無通過/失敗的指標。 最常見的例子列於以下表格中。

驗證檢查—— @fmlv.validate
檢查 Description Example
hasSize 檢視表的資料列數滿足一個條件。 .hasSize(lambda s: s == 5)
isComplete 欄位中沒有空值。 .isComplete("customer_id")
hasCompleteness 非空值的比例達到一個門檻。 .hasCompleteness("email", lambda c: c >= 0.9)
isUnique 該欄位沒有重複的值。 .isUnique("order_id")
hasUniqueness 唯一值的比例符合條件。 .hasUniqueness(["brand"], lambda u: u == 1.0)
hasDistinctness 不同值的占比滿足某個條件。 .hasDistinctness(["title"], lambda d: d > 0.5)
isPrimaryKey 欄位(或欄位集合)唯一地識別每一列。 .isPrimaryKey("order_id")
isContainedIn 所有值都在允許的集合內。 .isContainedIn("priority", ["high", "low"])
isNonNegative / isPositive 欄中沒有負值 / 只有嚴格為正的值。 .isNonNegative("num_views")
isLessThan / isGreaterThan 一欄始終小於/大於另一欄。 .isLessThan("discount", "price")
hasMin / hasMax 欄的最小值/最大值滿足某個條件。 .hasMax("age", lambda v: v <= 120)
hasMean / hasSum 欄位平均值/和符合條件。 .hasSum("total_votes", lambda v: v > 0)
hasStandardDeviation 資料欄標準差符合某個條件。 .hasStandardDeviation("amount", lambda v: v < 5)
hasApproxQuantile 一個近似分位數(例如中位數)滿足一個條件。 .hasApproxQuantile("num_views", 0.5, lambda v: v <= 10)
hasCorrelation 兩欄間的皮爾森相關性符合一個條件。 .hasCorrelation("a", "b", lambda c: c > 0.8)
hasNumberOfDistinctValues 不同數值的數量符合一個條件。 .hasNumberOfDistinctValues("locale", lambda n: n == 5)
hasEntropy 欄位的資訊內容(熵)符合條件。 .hasEntropy("locale", lambda e: e > 2.0)
hasDataType 值符合預期的資料型態。 .hasDataType("id", ConstrainableDataTypes.Integral)
hasPattern / containsURL / containsEmail 符合正規表示式/網址/電子郵件模式的值比例符合條件。 .containsURL("description", lambda c: c >= 0.5)
containsCreditCardNumber / containsSocialSecurityNumber 符合信用卡/社會安全號碼模式的數值比例符合條件。 .containsCreditCardNumber("notes", lambda c: c == 0)
satisfies 滿足自訂 SQL 謂詞的列比例符合條件。 .satisfies("age >= 18", "adults", lambda c: c == 1.0)
分析器/指標 — @fmlv.analyze
Metric Description Example
ApproxCountDistinct 不同數值的大約數量,透過 HyperLogLog++ 草圖計算。 ApproxCountDistinct("product_id")
ApproxQuantile 分布的近似分位數。 ApproxQuantile("locale_encoded", 0.5)
ApproxQuantiles 分布的幾個近似分位數。 ApproxQuantiles("locale_encoded", [0.1, 0.5, 0.9])
Completeness 欄位中非空值的比例。 Completeness("product_id")
Compliance 符合特定欄位限制的列數比例。 Compliance("locale", "locale in ('es','jp','us')")
Correlation 兩欄間的皮爾森相關係數,範圍為 [-1, 1]。 Correlation("title", "brand")
CountDistinct 不同數值的數量。 CountDistinct("locale")
DataType 資料型態的分布(布林、小數、整數、字串)。 DataType("locale")
Distinctness 不同值數量占值總數的比例。 Distinctness("title")
Entropy 欄位值分布的資訊內容,以 nats 為單位。 Entropy("locale_encoded")
Maximum / Minimum 欄位的最大值/最小值。 Maximum("locale_encoded")
Mean 平均值;排除空值。 Mean("locale_encoded")
MutualInformation 可從一欄推斷出多少關於另一欄的資訊;對稱且非負。 MutualInformation(["title", "brand"])
PatternMatch 符合特定正則表達式的列比例。 PatternMatch("locale", r"\w{2}")
Size DataFrame 中的列數。 Size()
Sum 欄位所有值的總和。 Sum("total_votes")
UniqueValueRatio 唯一值數量占所有相異值總數的比例。 UniqueValueRatio(["brand"])
Uniqueness 唯一值除以所有值的比例。 Uniqueness(["brand"])

開源的 Deequ 函式庫提供了這些檢查與分析工具。 完整且權威的名單請參閱 Deequ 專案:github.com/awslabs/deequ。

Summary

  1. 建立你的 MLV,並註明其完整限定名稱。
  2. 在另一個資料品質儲存格中,使用 @fmlv.dq_suite(mlv_name=…) 註冊一個套件。
  3. 新增檢查 — 堆疊 @fmlv.validate("<fn>", "FAIL"|"WARN") 和/或 @fmlv.analyze("<fn>"),並撰寫對應的 entry functions,回傳 PyDeequ 資料框。
  4. 執行它 — 可從筆記本隨需執行,或在建立排程時開啟資料品質開關。
  5. 在血統資料品質標籤和執行歷史記錄中檢視結果。