本頁面由 Cloud Translation API 翻譯而成。

使用資料品質任務

本文件說明如何建立 Dataplex 通用目錄資料品質工作，讓您為內建和外部 BigQuery 資料表排定及執行資料品質檢查作業。

詳情請參閱「資料品質工作總覽」。

事前準備

本文假設您已建立 Dataplex 通用目錄湖泊，可用於建立資料品質工作。

啟用 Google API 和服務

啟用 Dataproc API。

啟用 API
為網路和子網路啟用私人 Google 存取權。在您打算用於 Dataplex 通用目錄資料品質工作網路上啟用私人 Google 存取權。如果您在建立 Dataplex Universal Catalog 資料品質工作時未指定網路或子網路，Dataplex Universal Catalog 會使用預設子網路。在這種情況下，您必須在預設子網路中啟用私人 Google 存取權。

建立規格檔案

Dataplex Universal Catalog 會使用開放原始碼 CloudDQ 做為驅動程式。Dataplex 通用目錄資料品質檢查要求是在 CloudDQ YAML 規格檔案中定義。

您可以使用單一 YAML 檔案或單一 ZIP 封存檔，做為資料品質工作的輸入內容，其中包含一或多個 YAML 檔案。建議您在個別的 YAML 規格檔案中記錄資料品質檢查要求，每個部分一個檔案。

如要準備規格檔案，請按照下列步驟操作：

建立一或多個 CloudDQ YAML 規格檔案，定義資料品質檢查要求。如要進一步瞭解必要語法，請參閱本文件的「關於規格檔案」一節。

請以 .yml 或 .yaml 格式儲存 YAML 規格檔案。如果您建立多個 YAML 規格檔案，請將所有檔案儲存至單一 ZIP 壓縮檔中。
建立 Cloud Storage 值區。
將規格檔案上傳至 Cloud Storage 值區。

關於規格檔案

CloudDQ YAML 規格檔案必須包含下列部分：

規則 (定義於頂層 rules YAML 節點)：要執行的規則清單。您可以使用預先定義的規則類型 (例如 NOT_NULL 和 REGEX) 建立這些規則，也可以使用自訂 SQL 陳述式 (例如 CUSTOM_SQL_EXPR 和 CUSTOM_SQL_STATEMENT) 擴充規則。CUSTOM_SQL_EXPR 陳述式會將 custom_sql_expr 評估為 False 的任何資料列標示為失敗。CUSTOM_SQL_STATEMENT 陳述式會將整個陳述式傳回的任何值標示為失敗。
列篩選器 (在頂層 row_filters YAML 節點中定義)：傳回布林值的 SQL 運算式，定義篩選器，以便從基礎實體主體擷取部分資料進行驗證。
規則繫結 (在頂層 rule_bindings YAML 節點中定義)：定義要套用至資料表的 rules 和 rule filters。
規則維度 (在 rule_dimensions YAML 節點中定義)：定義規則可在對應的 dimension 欄位中定義的資料品質規則維度允許清單。

例如：
```
rule_dimensions:
  - consistency
  - correctness
  - duplication
  - completeness
  - conformance
```
dimension 欄位是規則的選用欄位。如果任何規則中列出 dimension，則必須提供規則維度。

詳情請參閱 CloudDQ 參考指南和範例規格檔案。

注意：由於 CloudDQ 有限制，因此在單一 YAML 檔案中，每個部分 (例如 rules 或 rule_bindings) 的頂層節點不得超過一個，因為 CloudDQ 只會剖析檔案中每個類型的最後一個節點。

建立資料集來儲存結果

如要儲存結果，請建立 BigQuery 資料集。

資料集必須與執行資料品質工作所在的資料表位於同一個地區。

Dataplex Universal Catalog 會使用這個資料集，並建立或重複使用您選擇的資料表來儲存結果。

建立服務帳戶

建立服務帳戶，並賦予下列身分與存取權管理 (IAM) 角色和權限：

具備包含 YAML 規格的 Cloud Storage 路徑的讀取權限。您可以在 Cloud Storage 儲存桶中使用「Storage 物件檢視者」角色 (roles/storage.objectViewer)。
可讀取 BigQuery 資料集，其中含有待驗證的資料。您可以使用 BigQuery 資料檢視者角色。
具備 BigQuery 資料集的寫入權限，以便視需要建立資料表，並將結果寫入該資料表。您可以在資料集層級使用 BigQuery 資料編輯者角色 (roles/bigquery.dataEditor)。
專案層級的 BigQuery 工作使用者角色 (roles/bigquery.jobUser)，以便在專案中建立 BigQuery 工作。
專案或資料湖層級的 Dataplex 通用目錄中繼資料讀取者角色 (roles/dataplex.metadataReader)。
專案層級的服務使用情形消費者角色 (roles/serviceusage.serviceUsageConsumer)。
Dataproc 工作站角色。
授予提交工作的使用者 iam.serviceAccounts.actAs 權限。
授予 Dataplex 通用目錄湖服務帳戶的服務帳戶使用者角色。您可以在控制台查看 Dataplex Universal Catalog 湖泊服務帳戶。 Google Cloud

使用進階設定

這些步驟為選用步驟：

根據預設，BigQuery 會在目前專案中執行資料品質檢查。您可以選擇其他專案來執行 BigQuery 工作。請為工作屬性 --execution-args 使用 --gcp_project_id TASK_ARGS 引數。
如果指定用於執行 BigQuery 查詢的專案 ID 與建立服務帳戶 (由 --execution-service-account 指定) 的專案不同，請確認已停用停用跨專案服務帳戶使用權 (iam.disableServiceAccountCreation) 的機構政策。此外，請確認服務帳戶可存取執行 BigQuery 查詢的專案中 BigQuery 工作排程。

限制

為特定資料品質工作指定的所有資料表，都必須屬於同一個 Google Cloud區域。

排定資料品質任務

控制台

在 Google Cloud 控制台中，前往 Dataplex 通用目錄的「Process」頁面。
前往「Process」
按一下「建立工作」。
在「檢查資料品質」資訊卡上，按一下「建立工作」。
在「Dataplex lake」(Dataplex 湖泊) 部分，選擇湖泊。
在「ID」中輸入 ID。
在「資料品質規格」部分執行下列操作：
1. 在「Select GCS file」(選取 GCS 檔案) 欄位中，按一下「Browse」(瀏覽)。
2. 選取 Cloud Storage 值區。
3. 按一下 [選取]。
在「結果表格」部分，執行下列操作：
1. 在「選取 BigQuery 資料集」欄位中，按一下「瀏覽」。
2. 選取要儲存驗證結果的 BigQuery 資料集。
3. 按一下 [選取]。
4. 在「BigQuery table」(BigQuery 資料表) 欄位中，輸入要儲存結果的資料表名稱。如果資料表不存在，Dataplex 通用目錄會為您建立。請勿使用 dq_summary 這個名稱，因為這是保留給內部處理工作使用的名稱。
在「服務帳戶」部分，從「使用者服務帳戶」選單中選取服務帳戶。
按一下「繼續」。
在「Set schedule」(設定時間表) 部分，設定資料品質工作執行的時間表。
按一下 [建立]。

gcloud CLI

以下是使用 Dataplex 通用目錄工作 gcloud CLI 指令執行資料品質工作的範例：

export USER_CLOUDDQ_YAML_CONFIGS_GCS_PATH="USER_CLOUDDQ_YAML_CONFIGS_GCS_PATH"

# Google Cloud project where the Dataplex Universal Catalog task is created.
export GOOGLE_CLOUD_PROJECT="GOOGLE_CLOUD_PROJECT"

# Google Cloud region for the Dataplex Universal Catalog lake.
export DATAPLEX_REGION_ID="DATAPLEX_REGION_ID"

# Public Cloud Storage bucket containing the prebuilt data quality executable artifact. There is one bucket for each Google Cloud region.
export DATAPLEX_PUBLIC_GCS_BUCKET_NAME="dataplex-clouddq-artifacts-${DATAPLEX_REGION_ID}"

# The Dataplex Universal Catalog lake where your task is created.
export DATAPLEX_LAKE_ID="DATAPLEX_LAKE_ID"

# The service account used for running the task. Ensure that this service account
has sufficient IAM permissions on your project, including
BigQuery Data Editor, BigQuery Job User,
Dataplex Universal Catalog Editor, Dataproc Worker, and Service
Usage Consumer.
export DATAPLEX_TASK_SERVICE_ACCOUNT="DATAPLEX_TASK_SERVICE_ACCOUNT"

# If you want to use a different dataset for storing the intermediate data quality summary results
and the BigQuery views associated with each rule binding, use the following:
export CLOUDDQ_BIGQUERY_DATASET="CLOUDDQ_BIGQUERY_DATASET"

# The BigQuery dataset where the final results of the data quality checks are stored.
This could be the same as CLOUDDQ_BIGQUERY_DATASET.
export TARGET_BQ_DATASET="TARGET_BQ_DATASET"

# The BigQuery table where the final results of the data quality checks are stored.
export TARGET_BQ_TABLE="TARGET_BQ_TABLE"

# The unique identifier for the task.
export TASK_ID="TASK_ID"

gcloud dataplex tasks create \
    --location="${DATAPLEX_REGION_ID}" \
    --lake="${DATAPLEX_LAKE_ID}" \
    --trigger-type=ON_DEMAND \
    --execution-service-account="$DATAPLEX_TASK_SERVICE_ACCOUNT" \
    --spark-python-script-file="gs://${DATAPLEX_PUBLIC_GCS_BUCKET_NAME}/clouddq_pyspark_driver.py" \
    --spark-file-uris="gs://${DATAPLEX_PUBLIC_GCS_BUCKET_NAME}/clouddq-executable.zip","gs://${DATAPLEX_PUBLIC_GCS_BUCKET_NAME}/clouddq-executable.zip.hashsum","${USER_CLOUDDQ_YAML_CONFIGS_GCS_PATH}" \
    --execution-args=^::^TASK_ARGS="clouddq-executable.zip, ALL, ${USER_CLOUDDQ_YAML_CONFIGS_GCS_PATH}, --gcp_project_id='GOOGLE_CLOUD_PROJECT', --gcp_region_id='${DATAPLEX_REGION_ID}', --gcp_bq_dataset_id='${TARGET_BQ_DATASET}', --target_bigquery_summary_table='${GOOGLE_CLOUD_PROJECT}.${TARGET_BQ_DATASET}.${TARGET_BQ_TABLE}'," \
    "$TASK_ID"

參數	說明
`USER_CLOUDDQ_YAML_CONFIGS_GCS_PATH`	資料品質工作輸入的資料品質 YAML 設定 Cloud Storage 路徑。您可以使用 `.yml` 或 `.yaml` 格式的單一 YAML 檔案，也可以使用包含多個 YAML 檔案的 ZIP 封存檔。
`GOOGLE_CLOUD_PROJECT`	建立 Dataplex 通用目錄工作和 BigQuery 工作的 Google Cloud 專案。
`DATAPLEX_REGION_ID`	建立資料品質工作的 Dataplex 通用目錄湖泊區域。
`SERVICE_ACCOUNT`	用於執行工作服務帳戶。請確認這個服務帳戶具備足夠的 IAM 權限，詳情請參閱「開始前」一節。

對於 --execution-args，下列引數必須以位置引數的形式傳遞，因此必須按照以下順序傳遞：

引數	說明
`clouddq-executable.zip`	從公開 Cloud Storage bucket 傳入 `spark-file-uris` 的預先編譯可執行檔。
`ALL`	執行所有規則繫結。或者，您也可以透過逗號分隔清單的形式提供特定規則繫結。例如 `RULE_1,RULE_2`。
`gcp-project-id`	執行 BigQuery 查詢的專案 ID。
`gcp-region-id`	執行 BigQuery 工作以驗證資料品質的區域。這個區域應與 `gcp-bq-dataset-id` 和 `target_bigquery_summary_table` 的區域相同。
`gcp-bq-dataset-id`	用於儲存 `rule_binding` 檢視畫面和中繼資料品質摘要結果的 BigQuery 資料集。
`target-bigquery-summary-table`	資料品質檢查的最終結果儲存位置 BigQuery 資料表的資料表 ID 參照。請勿使用 ID 值 `dq_summary`，因為該值是保留給內部處理工作使用。
`--summary_to_stdout`	(選用) 傳遞這個標記後，系統會將上次執行時在 `dq_summary` 資料表中建立的所有驗證結果列，以 JSON 記錄的形式記錄到 Cloud Logging 和 `stdout`。

注意：根據預設，Dataplex 通用目錄資料品質工作會在「預設」網路中執行。您可以使用下列任一引數來變更網路：--vpc-network-name 或 --vpc-sub-network-name。請參閱如何設定這些引數。

API

更改下列內容：

PROJECT_ID = "Your Dataplex Universal Catalog Project ID"
REGION = "Your Dataplex Universal Catalog lake region"
LAKE_ID = "Your Dataplex Universal Catalog lake ID"
SERVICE_ACC = "Your service account used for reading the data"
DATAPLEX_TASK_ID = "Unique task ID for the data quality task"
BUCKET_NAME = "Your Cloud Storage bucket name containing the CloudDQ configs or YAML specification"
GCP_BQ_BILLING_PROJECT_ID = "Your BigQuery billing project"
GCP_BQ_REGION_ID = "Your BigQuery dataset region ID" #Optional
GCP_BQ_DATASET_ID = "Your BigQuery dataset to store the data quality summary results"
TARGET_TABLE_NAME = "Your target table name to store the results in BigQuery dataset"

提交 HTTP POST 要求：

POST https://dataplex.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/lakes/${LAKE_ID}/tasks?task_id=${DATAPLEX_TASK_ID}
{
"spark": {
    "python_script_file": f"gs://dataplex-clouddq-artifacts-us-central1/clouddq_pyspark_driver.py",
    "file_uris": [  f"gs://dataplex-clouddq-artifacts-us-central1/clouddq-executable.zip",
                    f"gs://dataplex-clouddq-artifacts-us-central1/clouddq-executable.zip.hashsum",
                    f"gs://dataplex-clouddq-artifacts-us-central1/your-clouddq-configs.zip"
                ]
},
"execution_spec": {
    "args": {
        "TASK_ARGS":f"clouddq-executable.zip, ALL, gs://BUCKET_NAME/your-clouddq-configs.zip, --gcp_project_id=${GCP_BQ_BILLING_PROJECT_ID}, --gcp_region_id=${GCP_BQ_REGION_ID}, --gcp_bq_dataset_id=${GCP_BQ_DATASET_ID}, --target_bigquery_summary_table=${GCP_BQ_BILLING_PROJECT_ID}.${GCP_BQ_DATASET_ID}.${TARGET_TABLE_NAME}"
    },
    "service_account": "SERVICE_ACC"
},
"trigger_spec": {
"type": "ON_DEMAND"
},
"description": "${DATAPLEX_TASK_DESCRIPTION}"
}

另請參閱 Dataplex 通用目錄資料品質工作範例 Airflow DAG。

監控已排程的資料品質任務

瞭解如何監控工作。

查看結果

資料品質驗證結果會儲存在您指定的 BigQuery 資料集和摘要資料表中，如建立資料集來儲存結果所述。摘要表格包含每個規則繫結和規則組合 (針對每次驗證執行作業) 的輸出摘要。摘要表格中的輸出內容包含下列資訊：

資料欄名稱	說明
`dataplex_lake`	(字串) 包含要驗證的資料表的 Dataplex Universal Catalog lake ID。
`dataplex_zone`	(字串) 包含要驗證的資料表的 Dataplex 通用目錄區 ID。
`dataplex_asset_id`	(字串) 包含要驗證的資料表的 Dataplex 通用目錄資產 ID。
`execution_ts`	(時間戳記) 驗證查詢執行時的時間戳記。
`rule_binding_id`	(字串) 要回報驗證結果的規則繫結 ID。
`rule_id`	(字串) 規則繫結下的規則 ID，系統會回報該規則的驗證結果。
`dimension`	(字串) `rule_id` 的資料品質維度。這個值只能是 `rule_dimensions` YAML 節點中指定的其中一個值。
`table_id`	(字串) 回報驗證結果的實體 ID。這個 ID 會在相應規則繫結的 `entity` 參數下指定。
`column_id`	(字串) 要回報驗證結果的資料欄 ID。這個 ID 會在相應規則繫結的 `column` 參數下指定。
`last_modified`	(時間戳記) 正在驗證的 `table_id` 上次修改時間戳記。
`metadata_json_string`	(字串) 在規則繫結或資料品質執行期間，指定的中繼資料參數內容鍵/值組合。
`configs_hashsum`	(字串) JSON 文件的雜湊總和，其中包含規則繫結以及所有相關聯的規則、規則繫結、列篩選器和實體設定。`configs_hashsum` 可追蹤 `rule_binding` ID 的內容或其參照的其中一個設定變更時的情況。
`dq_run_id`	(字串) 記錄的專屬 ID。
`invocation_id`	(字串) 資料品質執行作業的 ID。在同一個資料品質執行例項中產生的所有資料品質摘要記錄，都會共用相同的 `invocation_id`。
`progress_watermark`	(布林值) 決定資料品質檢查是否會考量此特定記錄，以便判斷遞增驗證的高水位標記。如果為 `FALSE`，則在建立高水位值時會忽略相應的記錄。執行測試資料品質驗證時，如果不應提前高水印，這項資訊就很實用。根據預設，Dataplex 通用目錄會在這個欄位填入 `TRUE`，但如果 `--progress_watermark` 引數的值為 `FALSE`，則可以覆寫這個值。
`rows_validated`	(整數) 在 `row_filters` 和 `incremental_time_filter_column_id` 欄的任何高水位標記篩選器套用後，驗證的記錄總數 (如有指定)。
`complex_rule_validation_errors_count`	(浮點值) `CUSTOM_SQL_STATEMENT` 規則傳回的資料列數。
`complex_rule_validation_success_flag`	(布林值) `CUSTOM_SQL_STATEMENT` 規則的成功狀態。
`success_count`	(整數) 通過驗證的記錄總數。此欄位會設為 `CUSTOM_SQL_STATEMENT` 規則的 `NULL`。
`success_percentage`	(浮點值) 在經過驗證的記錄總數中，通過驗證的記錄數量所占的百分比。對於 `CUSTOM_SQL_STATEMENT` 規則，這個欄位會設為 `NULL`。
`failed_count`	(整數) 驗證失敗的記錄總數。此欄位會設為 `CUSTOM_SQL_STATEMENT` 規則的 `NULL`。
`failed_percentage`	(浮點) 在驗證的記錄總數中，驗證失敗的記錄數量百分比。對於 `CUSTOM_SQL_STATEMENT` 規則，這個欄位會設為 `NULL`。
`null_count`	(整數) 驗證期間傳回空值的記錄總數。此欄位會設為 `NOT_NULL` 和 `CUSTOM_SQL_STATEMENT` 規則的 `NULL`。
`null_percentage`	(浮點) 在驗證的記錄總數中，驗證期間傳回空值的記錄數量百分比。此欄位會設為 `NOT_NULL` 和 `CUSTOM_SQL_STATEMENT` 規則的 `NULL`。
`failed_records_query`	對於每個失敗的規則，這個欄會儲存可用於取得失敗記錄的查詢。請參閱本文件的「使用 `failed_records_query` 排解失敗的規則」一節。

針對 BigQuery 實體，系統會為每個 rule_binding 建立檢視畫面，其中包含最新執行作業的 SQL 驗證邏輯。您可以在 --gcp-bq-dataset-id 引數中指定的 BigQuery 資料集中找到這些檢視畫面。

成本最佳化

資料品質工作會以 BigQuery 工作形式在專案中執行。如要控管執行資料品質工作的費用，請在執行 BigQuery 工作的專案中使用 BigQuery 定價。詳情請參閱 BigQuery 工作負載管理。

漸進式驗證

您經常會使用新區隔 (新資料列) 定期更新資料表。如果您不想在每次執行時重新驗證舊版區隔，可以使用增量驗證功能。

如要進行遞增驗證，資料表中必須有 TIMESTAMP 或 DATETIME 類型欄，且欄值必須單調遞增。您可以使用 BigQuery 資料表的分區資料欄。

如要指定遞增驗證，請在規則繫結中指定 incremental_time_filter_column_id=TIMESTAMP/DATETIME type column 的值。

指定欄時，資料品質工作只會考量 TIMESTAMP 值大於上次執行資料品質工作的時間戳記的資料列。

規格檔案範例

如要使用這些範例，請建立名為 sales 的 BigQuery 資料集。接著，請建立名為 sales_orders 的事實資料表，然後使用下列 GoogleSQL 陳述式執行查詢，新增範例資料：

CREATE OR REPLACE TABLE sales.sales_orders
(
 id STRING NOT NULL,
 last_modified_timestamp TIMESTAMP,
 customer_id STRING,
 item_id STRING,
 amount NUMERIC,
 transaction_currency STRING
);

INSERT INTO sales.sales_orders
(id, last_modified_timestamp, customer_id, item_id, amount, transaction_currency)
VALUES
("order1",CURRENT_TIMESTAMP(),"customer1","ASDWQ123456789012345",100,"USD"),
("order1",CURRENT_TIMESTAMP(),"customer2","bad_item_id",-10,"XXX"),
("order2",CURRENT_TIMESTAMP(),"customer3","INTNL987654321098765",50,"GBP"),
("order3",CURRENT_TIMESTAMP(),"customer4","INTNL932716428593847",50,"GBP")

範例 1

下列程式碼範例會建立資料品質檢查，用於驗證這些值：

amount：值為零或正數。
item_id：英數字串，由 5 個英文字母和 15 個數字組成。
transaction_currency：允許的貨幣類型，由靜態清單定義。這個範例的靜態清單允許使用英鎊和日圓做為貨幣類型。這項驗證僅適用於標示為國際的資料列。

# The following `NONE` row filter is required.
row_filters:
 NONE:
   filter_sql_expr: |-
      True
 # This filters for rows marked as international (INTNL).
 INTERNATIONAL_ITEMS:
   filter_sql_expr: |-
      REGEXP_CONTAINS(item_id, 'INTNL')

# Rule dimensions are optional but let you aggregate reporting.
rule_dimensions:
  - consistency
  - correctness
  - duplication
  - completeness
  - conformance
  - integrity

# Rules can apply to multiple tables or columns.
rules:
 VALUE_ZERO_OR_POSITIVE:
   rule_type: CUSTOM_SQL_EXPR
   dimension: correctness
   params:
     custom_sql_expr: |-
       $column >= 0

 VALID_ITEM_ID:
   rule_type: REGEX
   dimension: conformance
   params:
     pattern: |-
       [A-Z]{5}[0-9]{15}

 VALID_CURRENCY_ID:
   rule_type: CUSTOM_SQL_EXPR
   dimension: integrity
   params:
     custom_sql_expr: |-
      $column in ('GBP', 'JPY')

# Rule bindings associate rules to columns within tables.
rule_bindings:
  TRANSACTION_AMOUNT_VALID:
   entity_uri: bigquery://projects/PROJECT_ID/datasets/DATASET_ID/tables/sales_orders
   column_id: amount
   row_filter_id: NONE
   rule_ids:
     - VALUE_ZERO_OR_POSITIVE

  TRANSACTION_VALID_ITEM_ID:
   entity_uri: bigquery://projects/PROJECT_ID/datasets/DATASET_ID/tables/sales_orders
   column_id: item_id
   row_filter_id: NONE
   rule_ids:
     - VALID_ITEM_ID

  TRANSACTION_CURRENCY_VALID:
   entity_uri: bigquery://projects/PROJECT_ID/datasets/DATASET_ID/tables/sales_orders
   column_id: transaction_currency
   row_filter_id: INTERNATIONAL_ITEMS
   rule_ids:
     - VALID_CURRENCY_ID

更改下列內容：

PROJECT_ID：您的專案 ID。
DATASET_ID：資料集 ID。

示例 2

如果要檢查的資料表是 Dataplex 通用目錄湖泊的一部分，您可以使用湖泊或區域符號指定資料表。這樣一來，您就能依湖泊或區域匯總結果。舉例來說，您可以產生區域層級分數。

如要使用這個範例，請建立 Dataplex 通用目錄湖泊，並使用湖泊 ID operations 和可用區 ID procurement。接著，將表格 sales_orders 新增為可用區的資產。

# This is a convenience section that allows you to shorten the entity_uri
metadata_registry_defaults:
 dataplex:
   projects: PROJECT_ID
   locations: REGION_ID
   lakes: operations
   zones: procurement

# You have to define a NONE row filter
row_filters:
 NONE:
   filter_sql_expr: |-
      True
 INTERNATIONAL_ITEMS:
   filter_sql_expr: |-
      REGEXP_CONTAINS(item_id, 'INTNL')

# rule dimensions are optional but allow you to aggregate reporting.
rule_dimensions:
  - consistency
  - correctness
  - duplication
  - completeness
  - conformance
  - integrity

# Rules can be shared across tables or columns.
rules:
 VALUE_ZERO_OR_POSITIVE:
   rule_type: CUSTOM_SQL_EXPR
   dimension: correctness
   params:
     custom_sql_expr: |-
       $column >= 0

 VALID_ITEM_ID:
   rule_type: REGEX
   dimension: conformance
   params:
     pattern: |-
       [A-Z]{5}[0-9]{15}

 VALID_CURRENCY_ID:
   rule_type: CUSTOM_SQL_EXPR
   dimension: integrity
   params:
     custom_sql_expr: |-
      $column in ('GBP', 'JPY')

#rule bindings associate rules to {table, column}
rule_bindings:
 TRANSACTION_AMOUNT_VALID:
   entity_uri: dataplex://projects/PROJECT_ID/locations/REGION_ID/lakes/operations/zones/procurement/entities/sales_orders
   column_id: amount
   row_filter_id: NONE
   rule_ids:
     - VALUE_ZERO_OR_POSITIVE

 TRANSACTION_VALID_ITEM_ID:
   entity_uri: dataplex://zones/procurement/entities/sales_orders # omitting projects/locations/lakes from uri path to use the default values specified in metadata_registry_defaults
   column_id: item_id
   row_filter_id: NONE
   rule_ids:
     - VALID_ITEM_ID

 TRANSACTION_CURRENCY_VALID:
   entity_uri: dataplex://zones/procurement/entities/sales_orders
   column_id: transaction_currency
   row_filter_id: INTERNATIONAL_ITEMS
   rule_ids:
     - VALID_CURRENCY_ID

更改下列內容：

PROJECT_ID：您的專案 ID。
REGION_ID：資料表所在的 Dataplex 通用目錄湖泊的區域 ID，例如 us-central1。

示例 3

這個範例會新增自訂 SQL 檢查，藉此確認 ID 值是否唯一，進而強化範例 2。

# This is a convenience section that allows you to shorten the entity_uri
metadata_registry_defaults:
 dataplex:
   projects: PROJECT_ID
   locations: REGION_ID
   lakes: operations
   zones: procurement

# You have to define a NONE row filter
row_filters:
 NONE:
   filter_sql_expr: |-
      True
 INTERNATIONAL_ITEMS:
   filter_sql_expr: |-
      REGEXP_CONTAINS(item_id, 'INTNL')

# rule dimensions are optional but allow you to aggregate reporting.
rule_dimensions:
  - consistency
  - correctness
  - duplication
  - completeness
  - conformance
  - integrity

# Rules can be shared across tables or columns.
rules:
# This rule is parameterized with column_names as parameter
 NO_DUPLICATES_IN_COLUMN_GROUPS:
   rule_type: CUSTOM_SQL_STATEMENT
   dimension: duplication
   params:
     custom_sql_arguments:
       - column_names
     custom_sql_statement: |-
       select a.*
       from data a
       inner join (
         select
           $column_names
         from data
         group by $column_names
         having count(*) > 1
       ) duplicates
       using ($column_names)

 VALUE_ZERO_OR_POSITIVE:
   rule_type: CUSTOM_SQL_EXPR
   dimension: correctness
   params:
     custom_sql_expr: |-
       $column >= 0

 VALID_ITEM_ID:
   rule_type: REGEX
   dimension: conformance
   params:
     pattern: |-
       [A-Z]{5}[0-9]{15}

 VALID_CURRENCY_ID:
   rule_type: CUSTOM_SQL_EXPR
   dimension: integrity
   params:
     custom_sql_expr: |-
      $column in ('GBP', 'JPY')

#rule bindings associate rules to {table, column}

rule_bindings:
 TRANSACTIONS_UNIQUE:
   entity_uri: dataplex://projects/PROJECT_ID/locations/REGION_ID/lakes/operations/zones/procurement/entities/sales_orders
   column_id: id
   row_filter_id: NONE
   rule_ids:
     - NO_DUPLICATES_IN_COLUMN_GROUPS:
         column_names: "id"

 TRANSACTION_AMOUNT_VALID:
   entity_uri: dataplex://zones/procurement/entities/sales_orders # omitting projects/locations/lakes from uri path to use the default values specified in metadata_registry_defaults
   column_id: amount
   row_filter_id: NONE
   rule_ids:
     - VALUE_ZERO_OR_POSITIVE

 TRANSACTION_VALID_ITEM_ID:
   entity_uri: dataplex://zones/procurement/entities/sales_orders
   column_id: item_id
   row_filter_id: NONE
   rule_ids:
     - VALID_ITEM_ID

 TRANSACTION_CURRENCY_VALID:
   entity_uri: dataplex://zones/procurement/entities/sales_orders
   column_id: transaction_currency
   row_filter_id: INTERNATIONAL_ITEMS
   rule_ids:
     - VALID_CURRENCY_ID

示例 4

這個範例會使用 last_modified_timestamp 欄新增遞增驗證功能，以強化範例 3。您可以為一或多個規則繫結新增漸進式驗證。

# This is a convenience section that allows you to shorten the entity_uri
metadata_registry_defaults:
 dataplex:
   projects: PROJECT_ID
   locations: REGION_ID
   lakes: operations
   zones: procurement

# You have to define a NONE row filter
row_filters:
 NONE:
   filter_sql_expr: |-
      True
 INTERNATIONAL_ITEMS:
   filter_sql_expr: |-
      REGEXP_CONTAINS(item_id, 'INTNL')

# rule dimensions are optional but allow you to aggregate reporting.
rule_dimensions:
  - consistency
  - correctness
  - duplication
  - completeness
  - conformance
  - integrity

# Rules can be shared across tables or columns.
rules:
# This rule is parameterized with column_names as parameter
 NO_DUPLICATES_IN_COLUMN_GROUPS:
   rule_type: CUSTOM_SQL_STATEMENT
   dimension: duplication
   params:
     custom_sql_arguments:
       - column_names
     custom_sql_statement: |-
       select a.*
       from data a
       inner join (
         select
           $column_names
         from data
         group by $column_names
         having count(*) > 1
       ) duplicates
       using ($column_names)

 VALUE_ZERO_OR_POSITIVE:
   rule_type: CUSTOM_SQL_EXPR
   dimension: correctness
   params:
     custom_sql_expr: |-
       $column >= 0

 VALID_ITEM_ID:
   rule_type: REGEX
   dimension: conformance
   params:
     pattern: |-
       [A-Z]{5}[0-9]{15}

 VALID_CURRENCY_ID:
   rule_type: CUSTOM_SQL_EXPR
   dimension: integrity
   params:
     custom_sql_expr: |-
      $column in ('GBP', 'JPY')

#rule bindings associate rules to {table, column}

rule_bindings:
 TRANSACTIONS_UNIQUE:
   entity_uri: dataplex://projects/PROJECT_ID/locations/REGION_ID/lakes/operations/zones/procurement/entities/sales_orders
   column_id: id
   row_filter_id: NONE
   incremental_time_filter_column_id: last_modified_timestamp
   rule_ids:
     - NO_DUPLICATES_IN_COLUMN_GROUPS:
         column_names: "id"

 TRANSACTION_AMOUNT_VALID:
   entity_uri: dataplex://zones/procurement/entities/sales_orders # omitting projects/locations/lakes from uri path to use the default values specified in metadata_registry_defaults
   column_id: amount
   row_filter_id: NONE
   incremental_time_filter_column_id: last_modified_timestamp
   rule_ids:
     - VALUE_ZERO_OR_POSITIVE

 TRANSACTION_VALID_ITEM_ID:
   entity_uri: dataplex://zones/procurement/entities/sales_orders
   column_id: item_id
   row_filter_id: NONE
   incremental_time_filter_column_id: last_modified_timestamp
   rule_ids:
     - VALID_ITEM_ID

 TRANSACTION_CURRENCY_VALID:
   entity_uri: dataplex://zones/procurement/entities/sales_orders
   column_id: transaction_currency
   row_filter_id: INTERNATIONAL_ITEMS
   incremental_time_filter_column_id: last_modified_timestamp
   rule_ids:
     - VALID_CURRENCY_ID

使用 `failed_records_query` 排解規則失敗問題

對於每個失敗的規則，摘要資料表會在 failed_records_query 欄中儲存查詢，您可以使用這項查詢取得失敗的記錄。

如要進行偵錯，您也可以在 YAML 檔案中使用 reference columns，這樣就能將 failed_records_query 的輸出內容與原始資料彙整，取得完整的記錄。舉例來說，您可以指定 primary_key 資料欄或複合 primary_key 資料欄做為參照資料欄。

注意：失敗的記錄查詢不會在 CUSTOM_SQL_STATEMENT 規則中使用 reference_columns。失敗記錄查詢的輸出內容取決於 CUSTOM_SQL_STATEMENT 本身的查詢。舉例來說，如果您需要在 CUSTOM_SQL_STATEMENT 規則的失敗記錄查詢中加入參照欄，就必須在 SQL 陳述式中加入該欄。詳情請參閱「使用失敗記錄查詢 CUSTOM_SQL_STATEMENT 規則」。

指定參照欄

如要產生參照欄，您可以在 YAML 規格中加入以下內容：

reference_columns 段。在本節中，您可以建立一或多個參照欄組，每個組合都會指定一或多個欄。
rule_bindings 段。在本節中，您可以為規則繫結新增一行，指定要用於該規則繫結的規則參照欄 ID (reference_columns_id)。應為 reference_columns 部分指定的參照欄組合。

舉例來說，下列 YAML 檔案會指定 reference_columns 區段，並定義三個資料欄：id、last_modified_timestamp 和 item_id，做為 ORDER_DETAILS_REFERENCE_COLUMNS 集的一部分。以下範例使用範例資料表 sales_orders。

reference_columns:
  ORDER_DETAILS_REFERENCE_COLUMNS:
    include_reference_columns:
      - id
      - last_modified_timestamp
      - item_id
rules:
  VALUE_ZERO_OR_POSITIVE:
  rule_type: CUSTOM_SQL_EXPR
  params:
    custom_sql_expr: |-

row_filters:
NONE:
  filter_sql_expr: |-
      True

rule_bindings:
TRANSACTION_AMOUNT_VALID:
  entity_uri: bigquery://projects/PROJECT_ID/datasets/DATASET_ID/tables/sales_orders
  column_id: amount
  row_filter_id: NONE
  reference_columns_id: ORDER_DETAILS_REFERENCE_COLUMNS
  rule_ids:
    - VALUE_ZERO_OR_POSITIVE

使用失敗記錄查詢

失敗的記錄查詢會為每個規則失敗的記錄產生一列資料。其中包含觸發失敗的資料欄名稱、觸發失敗的值，以及參照欄的值。並包含可用於連結資料品質工作執行作業的中繼資料。

以下是「指定參照欄」一節所述 YAML 檔案記錄查詢失敗的輸出內容範例。這會顯示 amount 欄的失敗情況，以及 -10 的失敗值。並記錄參照資料欄的對應值。

_dq_validation_invocation_id	_dq_validation_rule_binding_id	_dq_validation_rule_id	_dq_validation_column_id	_dq_validation_column_value	_dq_validation_dimension	_dq_validation_simple_rule_row_is_valid	_dq_validation_complex_rule_validation_errors_count	_dq_validation_complex_rule_validation_success_flag	id	last_modified_timestamp	item_id
10a25be9-8dfa-446c-a42c-75f6bb4a49d9	TRANSACTION_AMOUNT_VALID	VALUE_ZERO_OR_POSITIVE	amount	-10		FALSE			order1	2022-01-22T02:30:06.321Z	bad_item_id

使用失敗記錄查詢來套用 CUSTOM_SQL_STATEMENT 規則

對於 CUSTOM_SQL_STATEMENT 規則，失敗的記錄查詢會包含 custom_sql_statement_validation_errors 欄。custom_sql_statement_validation_errors 欄位是巢狀欄位，其中的欄位會與 SQL 陳述式的輸出內容相符。系統不會在 CUSTOM_SQL_STATEMENT 規則的失敗記錄查詢中納入參考資料欄。

舉例來說，您的 CUSTOM_SQL_STATEMENT 規則可能如下所示：

rules:
  TEST_RULE:
    rule_type: CUSTOM_SQL_STATEMENT
    custom_sql_arguments:
      - existing_id
      - replacement_id
    params:
     CUSTOM_SQL_STATEMENT: |-
       (SELECT product_name, product_key FROM data
       where $existing_id != $replacement_id)

這個範例的結果將包含 custom_sql_statement_validation_errors 資料欄的一或多個資料列，每個 existing_id!=replacement_id 出現的情況都會對應到一個資料列。

以 JSON 格式轉譯時，這個資料欄中儲存格的內容可能會如下所示：

{
  "custom_sql_statement_valdation_errors" :{
    "product_name"="abc"
    "product_key"="12345678"
    "_rule_binding_id"="your_rule_binding"
  }
}

您可以使用 join on custom_sql_statement_valdation_errors.product_key 等巢狀參照，將這些結果與原始資料表合併。

後續步驟

請參閱 CloudDQ YAML 規格參考資料。
如需範例資料品質規則，請參閱「簡單規則」和「進階規則」。
請參閱 Dataplex 通用目錄資料品質工作範例 Airflow DAG。

使用資料品質任務 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

啟用 Google API 和服務

建立規格檔案

關於規格檔案

建立資料集來儲存結果

建立服務帳戶

使用進階設定

限制

排定資料品質任務

控制台

gcloud CLI

API

監控已排程的資料品質任務

查看結果

成本最佳化

漸進式驗證

規格檔案範例

範例 1

示例 2

示例 3

示例 4

使用 failed_records_query 排解規則失敗問題

指定參照欄

使用失敗記錄查詢

使用失敗記錄查詢來套用 CUSTOM_SQL_STATEMENT 規則

後續步驟

使用資料品質任務

使用 `failed_records_query` 排解規則失敗問題