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

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

剖析及確保資料品質

建立以程式碼即政策為基礎的資料品質工作流程。本教學課程說明如何透過宣告式版本控管檔案定義資料品質期望，擺脫手動 UI 驅動程序。

採用Human-in-the-Loop方法，由 AI 草擬初始規則，您負責審查、修正及驗證，即可快速將剖析檔統計資料轉換為資料品質架構。

目標

使用具體化檢視區塊將巢狀 BigQuery 資料攤平，以啟用 Knowledge Catalog 剖析功能。
使用 Python 用戶端程式庫執行 Knowledge Catalog 剖析掃描作業。
使用 Gemini CLI 根據設定檔統計資料生成資料品質規則。
透過人機迴圈審查程序，驗證並部署 AI 生成的規則，做為 Knowledge Catalog 品質掃描作業。

事前準備

開始之前，請確認您已啟用計費功能的 Google Cloud 專案。

準備環境

下列步驟會使用 Cloud Shell，這是可在雲端執行的指令列環境。

在 Google Cloud 控制台，按一下右上工具列中的「啟用 Cloud Shell」。請稍候片刻，等待系統完成佈建作業並連線至環境。

在 Cloud Shell 中設定專案 ID 和環境變數：

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export LOCATION="us-central1"
export BQ_LOCATION="us"
export DATASET_ID="dataplex_dq_codelab"
export TABLE_ID="ga4_transactions"

由於公開範例資料也位於 us (多區域)，因此請使用 us (多區域) 做為位置。如果是 BigQuery 查詢，來源資料和目的地資料表必須位於相同位置。

啟用必要服務：

gcloud services enable dataplex.googleapis.com \
                       bigquery.googleapis.com \
                       serviceusage.googleapis.com

建立 BigQuery 資料集，用於儲存範例資料和結果：
```
bq --location=us mk --dataset $PROJECT_ID:$DATASET_ID
```
準備範例資料，這些資料來自 Google 商品網路商店的公開電子商務資料集。

下列 bq 指令會在 dataplex_dq_codelab 資料集中建立新資料表 ga4_transactions。為確保掃描作業快速執行，系統只會複製一天 (2021 年 1 月 31 日) 的資料。
```
bq query \
--use_legacy_sql=false \
--destination_table=$PROJECT_ID:$DATASET_ID.$TABLE_ID \
--replace=true \
'SELECT * FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131`'
```

複製包含本教學課程資料夾結構和支援檔案的 GitHub 存放區：

# Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos

# Specify and download only the folder we need for this lab
git sparse-checkout set data-analytics/programmatic-dq
cd data-analytics/programmatic-dq

這個目錄是您目前的工作區。

設定檔巢狀資料

透過資料剖析，Knowledge Catalog 會找出頂層資料欄的統計資料，例如空值百分比、唯一性和資料中的值分布情形，協助您瞭解資料。

如要取得巢狀欄位的統計資料，可以使用一組具體化檢視表整併資料。這會將每個巢狀欄位轉換為頂層資料欄，供 Knowledge Catalog 剖析。

取得巢狀結構定義

取得來源資料表的完整結構定義 (包括所有巢狀結構)，並將輸出內容儲存為 JSON 檔案：

bq show --schema --format=json $PROJECT_ID:$DATASET_ID.$TABLE_ID > bq_schema.json

查看結構定義：

jq < bq_schema.json

bq_schema.json 檔案會顯示複雜的結構。

使用具體化檢視表將資料扁平化

攤平巢狀資料時，請勿在同一個檢視區塊中取消巢狀結構的多個獨立陣列。這麼做會在陣列之間執行隱含的 cross join (笛卡爾乘積)，導致資料列相乘錯誤，進而損毀資料。

建議您改為建立多個資料檢視，每個資料檢視都用於特定用途。每個檢視畫面都應維持單一且清楚的詳細程度。在這個步驟中，您會建立下列具體化檢視區塊：

工作階段平坦檢視畫面 (mv_ga4_user_session_flat.sql)：每個事件各佔一行。
交易檢視畫面 (mv_ga4_ecommerce_transactions.sql)：每筆交易各占一行。
項目檢視畫面 (mv_ga4_ecommerce_items.sql)：每個項目各佔一行。

專案存放區會在 devrel-demos/data-analytics/programmatic-dq 目錄中提供三個 SQL 檔案，用於定義這些檢視區塊。

使用下列 BigQuery 指令，從 Cloud Shell 執行這些檔案。

envsubst < mv_ga4_user_session_flat.sql | bq query --use_legacy_sql=false
envsubst < mv_ga4_ecommerce_transactions.sql | bq query --use_legacy_sql=false
envsubst < mv_ga4_ecommerce_items.sql | bq query --use_legacy_sql=false

使用 Python 用戶端執行設定檔掃描

您現在可以為每個 materialized view 建立及執行 Knowledge Catalog 資料剖析掃描作業。下列 Python 指令碼使用 google-cloud-dataplex 用戶端程式庫自動執行這個程序。

執行指令碼前，請在專案目錄中建立獨立的 Python 虛擬環境。

# Create the virtual environment
python3 -m venv dq_venv

# Activate the environment
source dq_venv/bin/activate

在虛擬環境中安裝 Knowledge Catalog 用戶端程式庫。

# Install the Dataplex client library
pip install google-cloud-dataplex

環境設定完成並安裝程式庫後，即可使用 1_run_dataplex_scans.py 指令碼。這項指令碼會為三個具體化檢視區建立並執行掃描，藉此剖析這些檢視區。完成後，系統會輸出豐富的統計摘要，您可以在下一個步驟中使用這些摘要，生成 AI 輔助的資料品質規則。

從 Cloud Shell 終端機執行指令碼。

python3 1_run_dataplex_scans.py

查看剖析掃描作業

您可以在 Google Cloud 控制台查看新的設定檔掃描結果。

在導覽選單中，前往「Knowledge Catalog」，然後在「Govern」部分選取「Data profiling & quality」。
畫面上會列出三項個人資料掃描結果，以及最新的工作狀態。按一下掃描結果即可查看詳細資料。

將設定檔結果匯出為 JSON 格式

如要讓 Gemini 讀取設定檔掃描結果，請將內容擷取到本機檔案。

使用 2_dq_profile_save.py 指令碼找出 mv_ga4_user_session_flat 檢視畫面的最新掃描結果，下載剖析檔資料，然後儲存到名為 dq_profile_results.json 的檔案。

python3 2_dq_profile_save.py

指令碼完成後，會在目錄中建立 dq_profile_results.json 檔案。這個檔案包含產生資料品質規則所需的詳細統計中繼資料。執行下列指令，查看檔案內容：

cat dq_profile_results.json

使用 Gemini CLI 生成資料品質規則

現在您可以使用 Gemini CLI 讀取本機剖析掃描結果。

為複雜資料集手動編寫資料品質規則既耗時又容易出錯。生成式 AI 可以在幾秒內生成完整的初始資料品質設定，加快這個工作流程。這有助於您從手動執行工作轉為高層級監督。

如要啟動 Gemini CLI，請使用下列指令：

gemini

現在可以開始產生品質規則。由於 CLI 可以讀取目前目錄中的檔案，因此可以直接使用新的剖析掃描資料。

提示 Gemini 建立行程

問問 Gemini 扮演專業分析師，並提出建立資料品質規則的計畫。請 Gemini 暫時不要編寫 YAML 檔案，先著重於分析。Gemini 會分析 JSON 檔案，並傳回結構化計畫

You are an expert Google Cloud Dataplex engineer.
Your first task is to create a plan. I have a file in the current directory named ./dq_profile_results.json.
Based on the statistical data within that file, propose a step-by-step plan to create a Dataplex data quality rules file.
Your plan should identify which specific columns are good candidates for rules like nonNullExpectation, setExpectation, or rangeExpectation, and explain why based on the metrics (for example, "Plan to create a nonNullExpectation for column X because its null percentage is 0%").
Do not write the YAML file yet. Just provide the plan.

產生資料品質規則

Gemini 的計畫完全依據統計模式，缺乏您的特定業務知識。

請查看計畫並思考以下問題：

是否符合您的業務目標和脈絡？
是否有任何統計上合理的規則實際上不可行 (例如針對不斷成長的資料表設定嚴格的 rowCount)？

使用下列範例提示詞，透過 Gemini 調整計畫，或直接核准計畫。提示開頭會先提供一些意見回饋，然後指示 Gemini 在工作目錄中產生 dq_rules.yaml 檔案，並遵守 DataQualityRule 規格，因為 Knowledge Catalog 需要精確的 YAML 結構。這有助於避免語法錯誤或使用過時的結構化資料版本。


- "The plan looks good. Please proceed."
- "The rowCount rule is not necessary, as the table size changes daily. The rest of the plan is approved. Please proceed."
- "For the setExpectation on the geo_continent column, please also include 'Antarctica'."

Once you have incorporated my feedback, please generate the `dq_rules.yaml` file.

You must adhere to the following strict requirements:

- Schema Compliance: The YAML structure must strictly conform to the DataQualityRule specification. For a definitive source of truth, you must refer to the sample_rule.yaml file in the current directory and the DataQualityRule class definition. Search for the `data_quality.py` file inside the `./dq_venv/lib/` directory to read this class definition.

- Data-Driven Values: All rule parameters, such as thresholds or expected values, must be derived directly from the statistical metrics in dq_profile_results.json.

- Rule Justification: For each rule, add a comment (#) on the line above explaining the justification, as you outlined in your plan.

- Output Purity: The final output must only be the raw YAML code block, perfectly formatted and ready for immediate deployment.

建立及執行資料品質掃描作業

您現在有一組由代理程式產生的資料品質規則，可以註冊並部署為掃描作業。

輸入 /quit 或按兩次 Ctrl+C，即可退出 Gemini CLI。

接著，在 Knowledge Catalog 中建立資料掃描作業：

export DQ_SCAN="dq-scan"
gcloud dataplex datascans create data-quality $DQ_SCAN \
    --project=$PROJECT_ID \
    --location=$LOCATION \
    --data-quality-spec-file=dq_rules.yaml \
    --data-source-resource="//bigquery.googleapis.com/projects/$PROJECT_ID/datasets/$DATASET_ID/tables/mv_ga4_user_session_flat"

最後，執行掃描：

gcloud dataplex datascans run $DQ_SCAN --location=$LOCATION --project=$PROJECT_ID

這個指令會建立名為 dq-scan 的資料品質掃描作業。

在 Google Cloud 控制台的 Knowledge Catalog 部分，查看掃描進度。
1. 在導覽選單中，前往「Knowledge Catalog」，然後在「Govern」部分選取「Data profiling & quality」。
2. 找出 dq-scan。掃描完成後，按一下掃描結果即可查看。
注意： 由於大型語言模型 (LLM) 具有不確定性，Gemini 建立的初始規則不會完美。建議您與 Gemini 互動，修正規則並排除誤報。在這個階段看到失敗結果完全正常，這也說明人機迴圈 (HITL) 審查是有效資料品質管理不可或缺的持續性環節。

清除所用資源

如要避免系統針對您在本教學課程中建立的資源，向您收取週期性付款，請將資源全數刪除。

刪除 Knowledge Catalog 掃描作業

使用本程式碼研究室中的特定掃描名稱，刪除設定檔和品質掃描作業：

# Delete the Data Quality Scan
gcloud dataplex datascans delete dq-scan \
    --location=us-central1 \
    --project=$PROJECT_ID --quiet

# Delete the Data Profile Scans
gcloud dataplex datascans delete profile-scan-mv-ga4-user-session-flat \
    --location=us-central1 \
    --project=$PROJECT_ID --quiet

gcloud dataplex datascans delete profile-scan-mv-ga4-ecommerce-transactions \
    --location=us-central1 \
    --project=$PROJECT_ID --quiet

gcloud dataplex datascans delete profile-scan-mv-ga4-ecommerce-items \
    --location=us-central1 \
    --project=$PROJECT_ID --quiet

刪除範例資料集

刪除臨時 BigQuery 資料集和其中的資料表。

bq rm -r -f --dataset $PROJECT_ID:dataplex_dq_codelab

刪除本機檔案

停用 Python 虛擬環境，並移除複製的存放區及其內容：

deactivate
cd ../../..
rm -rf devrel-demos

結論

恭喜，您剛才建構了端對端程式輔助資料治理工作流程。

將 Gemini 與 Knowledge Catalog 配對後，您已為 AI 輔助治理奠定基礎。這種做法不會取代控管迴圈，但可加快規則建立程序，讓您專注於根據商業邏輯驗證及修正規則。

後續步驟

如要進一步瞭解這項架構背後的理念，請參閱「AI 輔助管理：透過人工監督提升資料品質」。
建立 CI/CD 管道，以程式碼形式管理資料品質。
探索如何使用自訂 SQL 規則，強制執行特定商業邏輯。
使用篩選器和取樣功能，盡可能降低掃描費用。
使用 Terraform 佈建 Knowledge Catalog 資源，自動管理基礎架構，大規模控管資料治理。
進一步瞭解 Gemini CLI 開放原始碼 AI 代理。
嘗試其他 Knowledge Catalog 應用實例