自 2026 年 4 月 10 日起，Dataplex Universal Catalog 將更名為 Knowledge Catalog。API、用戶端程式庫、CLI 和 IAM 名稱維持不變。詳情請參閱「隆重推出 Google Cloud Knowledge Catalog」。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用資料品質任務

Knowledge Catalog 資料品質工作可讓您排定及執行內建和外部 BigQuery 資料表的驗證檢查，確認記錄符合預期。您可以在 CloudDQ YAML 規格中設定預先定義或自訂 SQL 規則、將摘要結果儲存在 BigQuery，以及排解失敗資料列的問題。詳情請參閱「資料品質工作總覽」。

事前準備

本文假設您已有 Knowledge Catalog 湖泊，可在其中建立資料品質工作。

啟用 Google API 和服務

啟用 Dataproc API。

啟用 API
為網路和子網路啟用 Private Google Access。在要用於 Knowledge Catalog 資料品質工作的網路上，啟用 Private Google Access。建立 Knowledge Catalog 資料品質工作時，如未指定網路或子網路，Knowledge Catalog 會使用預設子網路。在這種情況下，您必須在預設子網路上啟用 Private Google Access。

建立規格檔案

Knowledge Catalog 使用開放原始碼 CloudDQ 做為驅動程式。Knowledge Catalog 資料品質檢查要求是以 CloudDQ YAML 規格檔案定義。

資料品質工作的輸入內容可以是單一 YAML 檔案，也可以是包含一或多個 YAML 檔案的單一 ZIP 封存檔。建議您在不同的 YAML 規格檔案中擷取資料品質檢查需求，每個部分各一個檔案。

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

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

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

規格檔案簡介

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 資料集。

資料集必須與執行資料品質工作的資料表位於相同區域。

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

建立服務帳戶

建立服務帳戶，並授予下列 Identity and Access Management (IAM) 角色和權限：

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

使用進階設定

以下為選用步驟：

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

限制

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

排定資料品質任務

控制台

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

gcloud CLI

以下是使用 Knowledge Catalog tasks gcloud CLI 指令執行資料品質工作的範例：

export USER_CLOUDDQ_YAML_CONFIGS_GCS_PATH="USER_CLOUDDQ_YAML_CONFIGS_GCS_PATH"

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

# Google Cloud region for the Knowledge 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 Knowledge 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 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`	建立 Knowledge Catalog 工作和 BigQuery 工作的 Google Cloud 專案。
`DATAPLEX_REGION_ID`	建立資料品質工作的 Knowledge Catalog 湖泊所在區域。
`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`。

注意：根據預設，Knowledge Catalog 資料品質工作會在預設網路中執行。您可以使用下列其中一個引數來變更網路：--vpc-network-name 或 --vpc-sub-network-name。瞭解如何設定這些引數。

API

更改下列內容：

PROJECT_ID = "Your Knowledge Catalog Project ID"
REGION = "Your Knowledge Catalog lake region"
LAKE_ID = "Your Knowledge 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}"
}

另請參閱「Knowledge Catalog 資料品質工作的 Airflow DAG 範例」。

監控排定的資料品質任務

瞭解如何監控工作。

查看結果

資料品質驗證結果會儲存在您指定的 BigQuery 資料集和摘要資料表中，詳情請參閱「建立資料集來儲存結果」。摘要表格包含每次驗證執行作業中，各規則繫結和規則組合的輸出摘要。摘要表格中的輸出內容包含下列資訊：

資料欄名稱	說明
`dataplex_lake`	(字串) 包含待驗證資料表的 Knowledge Catalog 湖泊 ID。
`dataplex_zone`	(字串) 包含待驗證資料表的 Knowledge Catalog 可用區 ID。
`dataplex_asset_id`	(字串) 含有待驗證資料表的 Knowledge Catalog 資產 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`，系統在建立高水位值時會忽略對應的記錄。執行不應推進高水位標記的測試資料品質驗證時，這項資訊非常實用。Knowledge Catalog 預設會在這個欄位填入 `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

如果待檢查的資料表屬於 Knowledge Catalog 湖泊，您可以使用湖泊或可用區標記法指定資料表。這可讓您依湖泊或可用區匯總結果。舉例來說，您可以產生區域層級分數。

如要使用這個範例，請建立 Knowledge Catalog 湖泊，並將湖泊 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：資料表所在 Knowledge Catalog 湖泊的區域 ID，例如 us-central1。

樣本 3

這個範例在範例 2 的基礎上，新增自訂 SQL 檢查，確認 ID 值是否不重複。

# 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 規格參考資料。
如需資料品質規則範例，請參閱「簡易規則」和「進階規則」。
請參閱「Knowledge Catalog 資料品質工作的 Airflow DAG 範例」。

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

事前準備

啟用 Google API 和服務

建立規格檔案

規格檔案簡介

建立資料集來儲存結果

建立服務帳戶

使用進階設定

限制

排定資料品質任務

控制台

gcloud CLI

API

監控排定的資料品質任務

查看結果

成本最佳化

增量驗證

規格檔案範例

樣本 1

樣本 2

樣本 3

範例 4

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

指定參照資料欄

使用失敗記錄查詢

使用 CUSTOM_SQL_STATEMENT 規則的失敗記錄查詢

後續步驟

使用資料品質任務

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