資料品質Spec配置說明 - DataWorks

該Spec是DataWorks資料品質模組中資料品質監控、資料品質規則資源的描述規範，使用YAML格式書寫。目前可以作為OpenAPI的入參，操作DataWorks資料品質產品中的相關資源。

基本定義

YAML樣本

一個簡單的資料品質監控定義如下：

datasets:
  - type: Table
    tables:
      - tb_d_spec_demo
    dataSource:
      name: odps_first
      envType: Dev
rules:
  - assertion: row_count > 0

屬性說明

上述樣本的Spec定義了一個最簡單的資料品質監控：

datasets：資料品質監控對象，包含3個屬性
- type：監控物件類型，目前只支援一種枚舉Table。
- dataSource：監控對象所屬的資料來源，設定name和envType來標識資料來源，您可以通過ListDataSources擷取資料來源名稱。
  說明
  當前僅支援部分資料來源，詳情請參見支援的資料來源類型列表。
- tables：如果監控對象為Table類型，需配置表名。
  說明
  如果資料來源綁定到了資料庫層級，同時需要監控非預設Schema的表，table需要按照schema.table的格式配置。
rules：期望資料滿足的規則，一個資料品質監控可以包含多條規則。
資料品質監控在執行時，會掃描監控對象中的資料，依次計算出每一個規則所指定的指標值，並與期望的閾值做比較，通過校正是否滿足期望閾值來判斷該條規則是否通過。
一般情況下，對資料的期望使用一個包含指標類型（如row_count）、比較符（如>）、閾值（如0）的assertion語句來描述，校正結果通常有3種。
- pass：通過，採集的指標值落在閾值定義的區間內。
- fail：不通過，採集的指標值落在閾值定義的區間外。
- error：校正過程中出現其他異常，比如語法錯誤等。
說明
- 如果顯式指定了warn層級的閾值，校正結果也可能會是warn。詳情請參見添加多級閾值定義。
- 您可以查看assertion語句中支援的支援的系統內建指標類型。
- 建立品質監控時，您也可以使用自訂指標規則。

閾值定義方式

assertion中支援的閾值定義方式如下：

固定閾值

適用於需要將指標值與一個固定值直接比較的情境，固定閾值定義包含如下部分：

a metric
an argument (optional)
a comparison symbol（optional）
a threshold（optional）

配置樣本

rules:
  # 資料行數要大於0
  - assertion: row_count > 0
  # size欄位最大值要小於等於500
  - assertion: max(size) <= 500

對應固定值閾值運算式的四個部分如下表所示：

運算式組成部分	`row_count > 0`	`max(size) <= 500`
a metric	`row_count`	`max`
an argument (optional)	/	`(size)`
a comparison symbol（optional）	`>`	`<=`
a threshold（optional）	`0`	`500`

更多支援的比較符，請參見支援的比較符（comparison symbol）。

波動閾值

適用於將當前的指標值，與相同指標的歷史值做比較的情境，例如：當天的使用者數與前一天使用者數的差值需控制在100個以內、當天的收入與最近7天的收入均值相比波動範圍需控制在10%以內等。

通常在metric前加change for描述波動值閾值，波動值閾值定義包含如下部分：

change（關鍵字）
an aggregate type（optional）
a time window
percent（關鍵字 optional）
for（關鍵字）
a metric
an argument（optional）
a comparison symbol（optional）
a threshold（optional）

組合後的運算式格式：change [aggregate_type] [time_window] [percent] for metric [argument] [comparison_symbol threshold]。

配置樣本

樣本一：與指定時間視窗（time_window）的校正結果做差值比較

您可以在change ... for之間添加時間視窗（time_window）來顯式指定本次指標值與歷史上哪些指標做對比：

rules:
  # 本次資料行數與7天前校正時資料行數差值要控制在10000行以內
  - assertion: change 7 days ago for row_count < 10000

樣本二：將指定時間視窗的校正結果彙總後做差值比較

您可以在change和時間視窗（time_window）之間增加彙總方式（aggregate type），系統會將時間視窗之內的校正記錄使用對應彙總方式計算出中間結果後，再作為本次校正的參考值：

rules:
  # 本次資料行數與最近7天資料行數均值的差值要控制在10000行以內
  - assertion: change average last 7 days for row_count < 10000

目前支援如下兩種彙總方式：

avg：均值。
var：方差。

如果不指定彙總方式，系統會將當前指標值與時間視窗之內的所有校正記錄依次對比，得出與每一個校正記錄的對比結果，然後取嚴重等級最高的狀態作為最終校正狀態。

樣本三：與歷史校正結果做波動範圍百分比比較

您可以在change ... for之間添加percent來指明計算波動百分比之後再與閾值比較：

rules:
  # 本次資料行數與7天前校正時資料行數的相差100%要控制在50%以內
  - assertion: change 7 days ago percent for row_count < 50%

閾值結尾可以添加 %，提升可讀性。
假設本次指標值是c、上一次是cl，percent = (c-cl) / cl：
- 如果cl為0、c也為0，計算出的百分比為0。
- 如果cl為0、c不為0，則無法計算，校正結果為error。
結果可能是一個負數，定義的時候需要注意，可以用下面提到的between...and...來定義波動範圍百分比的區間

區間閾值

可以使用between...and...定義區間類型的閾值。

閉區間閾值定義

直接使用between...and...定義的區間，預設是閉區間。例如：當相較於一天前的資料行數波動範圍不在[-1%, 1%]的範圍內時觸發warn；行數波動範圍不在[-5%, 5%]的範圍內時觸發fail。[10, 15]區間時，校正通過。

datasets:
  - type: Table
    tables:
      - tb_d_spec_demo
    filter: dt='$[yyyymmdd]' AND hh='$[hh24-1/24]'
    dataSource:
      name: odps_first
      envType: Dev
rules:
  - assertion: change 1 day ago percent for row_count
    warn: 
      - when not between -1% and 1%
    fail: 
      - when not between -5% and 5%

添加多級閾值定義

除了在規則的assertion語句中定義期望閾值，還可以省去assertion語句中的期望閾值，同時設定規則的warn或fail屬性，來定義更豐富等級的閾值。例如：

rules:
  - assertion: duplicate_count(phone)
    warn: when between 1 and 10
    fail: when > 10

上述程式碼片段中，定義了warn和fail兩級閾值：

phone欄位的重複行數為0時校正通過。
phone欄位的重複行數大於10時校正不通過。
phone欄位的重複行數在1到10之間時，校正結果為warn。

warn和fail有重疊時的處理策略

warn和fail的閾值區間可以重疊，如果指標值落到了這段重疊的區間，系統會以等級更嚴重的狀態為準，結果為fail。

使用not between...and...定義區間補集

您可以在between...and...前使用not取反，擷取區間補集，例如：

rules:
  - assertion: duplicate_count(phone)
    warn: 
      - when not between -1% and 1%
    fail:
      - when not between -5% and 5%

上述程式碼片段定義的區間如下圖所示：

設定規則唯一標識（identity）

您可以為規則指定一個identity，作為規則在同一個資料品質監控範圍內的唯一標識。

如果建立規則時，沒有指定identity，系統會為該規則自動分配一個id。
您需要確保identity在同一個資料品質監控規則中的唯一性，，否則在更新時可能會失敗，或者誤更新到其他的規則，推薦使用一段有可讀性的字串，方便管理。
對于波動類閾值的規則（change...for...）和異常檢測（anomaly detection for ...）的規則，在查詢校正歷史時，會根據規則的identity查詢。
系統在接收到更新品質監控請求時，處理邏輯如下：
- 先遍曆更新品質監控請求中傳入的每一個規則，使用規則的id匹配品質監控中已經存在的規則並進行更新。
- 將品質監控中已經存在且未匹配到id的規則刪除。
- 在品質監控中將更新要求中剩餘規則建立為新規則。

指定identity的樣本如下：

rules:
  - assertion: row_count > 0
    name: 資料行數大於0
    # 指定資料品質監控範圍內的唯一標識
    identity: table-not-empty

定義規則業務嚴重等級（severity）

您可以設定規則的severity，標記規則對自身業務影響的嚴重程度，方便後續管理。例如：

rules:
  - assertion: row_count > 0
    severity: High

severity支援2個等級：

High
Normal（預設值）

設定規則啟用狀態（enabled）

您可以指定規則的enabled標識，用於管理規則的開啟狀態，對於臨時不使用但又不想刪除的規則，可以將enabled置為false，表示暫時關閉。在監控執行時，將不會真正觸發該規則。

rules:
  - assertion: row_count > 0
    # 規則的開啟狀態，預設為true
    enabled: false

設定前置語句（settingConfig）

部分業務情境下，在執行SQL計算指標之前，需要執行一些SET語句進行參數調整，以確保指標計算的SQL能夠正常執行或者保證效能。您可以在規則中添加settingConfig設定，例如：

rules:
  - assertion: row_count > 0
    # 設定前置執行的set語句
    settingConfig: SET odps.sql.udf.timeout=600s; SET odps.sql.python.version=cp27;

設定保留問題資料開關（collectFailedRows）

您可以在規則層級開啟問題資料保留的開關，當規則校正未通過（warn、fail狀態）時，自動過濾導致規則未通過的資料並儲存在與監控對象表相同資料庫的另外一張表中。開啟問題資料保留開關的方式如下：

rules:
  - assertion: duplicate_count(phone) = 0
    collectFailedRows: true

您可以將collectFailedRows設定成true，開啟問題資料的保留。對於自訂SQL的規則，需要額外指定failedRowsQuery顯式地配置問題資料保留的過濾語句：

rules:
  - assertion: id_null_count = 0
    id_null_count:
      expression: id IS NULL
    collectFailedRows: true
    failedRowsQuery: SELECT * FROM tb_d_spec_demo WHERE dt = '$[yyyymmdd-1]' AND id IS NULL

除了自訂SQL的規則，僅以下指標支援保留問題資料，其他指標暫不支援開啟collectFailedRows：

missing_count
missing_percent
duplicate_count
duplicate_percent
distinct_count
distinct_percent

設定規則名稱和描述

您可以為規則設定名字、描述，方便管理。

例如，您可以為監控整體設定一個名稱、為每一個規則設定各自的名稱，這個名稱在後續校正結果、頁面顯示中都可以被使用，方便管理。

datasets:
  - type: Table
    tables:
      - tb_d_spec_demo
    filter: dt='$[yyyymmdd]' AND hh='$[hh24-1/24]'
    dataSource:
      name: odps_first
      envType: Dev
rules:
  - assertion: row_count > 0
    # 規則名稱和描述
    name: 資料行數大於0
    description: 產出資料不可為空

設定資料過濾（filter）

為規則設定資料過濾

如果在做規則的校正時，只需要使用一部分資料做指標統計，例如只統計id欄位不為NULL的資料，您可以為規則添加filter設定。例如：

rules:
  - assertion: row_count > 0
    filter: id IS NOT NULL

為品質監控設定資料過濾

您也可以在Scan.Dataset中添加filter設定，此時這個filter會在品質監控的所有規則校正過程中生效。

datasets:
  - type: Table
    tables:
      - tb_d_spec_demo
    filter: dt='$[yyyymmdd]' AND hh='$[hh24-1/24]'
    dataSource:
      name: odps_first
rules:
  - assertion: row_count > 0

上述範例程式碼片段中，在dataset中添加filter設定，每個規則在做校正時，都會優先使用filter做資料過濾，然後再執行後續校正。

說明

在樣本filter的定義中，使用了時間運算式$[yyyymmdd-1]，系統會使用觸發監控時的triggerTime參數，做時間位移後替換到filter中。具體系統支援的參數引用方式請參見資料過濾配置。

附錄

支援的比較符（comparison symbol）

>
>=
<
<=
=
!=
between ... and ...

支援的資料來源類型列表

目前支援的資料來源類型包括：

maxcompute
hologres
emr
mysql
analyticdb_for_mysql
analyticdb_for_postgresql
cdh
starrocks

支援的系統內建指標類型

avg
row_count
sum
min
max
distinct_count
distinct_percent
table_size
missing_count
missing_percent
duplicate_percent
duplicate_count
group_by
invalid_count
invalid_distinct_count

時間視窗（time_window）定義方式

DataWorks資料品質支援多種時間視窗的定義方法，基本的格式如下：

n個時間單位前：n (minute[s]|hour[s]|day[s]|week[s]|month[s]) ago，例如n月前、n天前、n小時前。
- 1天前：1 day ago
- 7天前：7 days ago
- 1月前：1 month ago
- 8小時前：8 hours ago
- 15分鐘前：15 minutes ago
最近一段時間：last n (minute[s]|hour[s]|day[s]|week[s]|month[s]) ，例如最近15分鐘、最近7天、最近1個月。
- 最近15分鐘：last 15 minutes
- 最近24小時：last 24 hours
  說明
  從目前時間的24小時之前開始到目前時間截止，每隔一個小時採集一個時間點。
- 最近7天：last 7 days
- 最近1個月：last 1 month
某個月的日期、某個周的周幾的同一時間：1/2/3/.../-3/-2/-1 of (current|last|n) (months|weeks) (ago)
- 當月1日同一時間：1 of current month
- 上月最後一天同一時間：-1 of last month
- 3周前的周二同一時間：2 of 3 weeks ago