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

分析数据并确保数据质量

构建政策即代码数据质量工作流。本教程介绍如何通过在声明式、版本受控的文件中定义数据质量预期，摆脱手动、界面驱动的流程。

借助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 Merchandise Store 的公共电子商务数据集。

以下 bq 命令会在 dataplex_dq_codelab 数据集中创建一个新表 ga4_transactions。为确保扫描快速运行，它只会复制一天（2021-01-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 可以查找顶级列的统计信息，例如 null 百分比、唯一性和数据中的值分布，以帮助您了解数据。

如需获取嵌套字段的统计信息，您可以使用一组物化视图展平数据。这会将每个嵌套字段转换为 Knowledge Catalog 可以分析的顶级列。

获取嵌套架构

获取源表的完整架构（包括所有嵌套结构），并将输出保存为 JSON 文件：

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

查看架构：

jq < bq_schema.json

bq_schema.json 文件会显示复杂的结构。

使用具体化视图展平数据

展平嵌套数据时，请务必不要在同一视图中取消嵌套多个独立数组。这样做会在数组之间执行隐式交叉联接（笛卡尔积），从而错误地将行数相乘并损坏数据。

最好创建多个视图，每个视图都针对特定用途而构建。每个视图都应保持单一、清晰的详细程度。在此步骤中，您将创建以下物化视图：

会话展平视图 (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 客户端运行分析扫描

现在，您可以为每个具体化视图创建并运行 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 ，然后在治理部分中选择数据分析和质量评估 。
找到列出的三个分析扫描及其最新的作业状态。点击扫描即可探索其详细结果。

将分析结果导出为 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 的数据质量扫描。

在控制台的 Knowledge Catalog 部分中查看扫描的进度。 Google Cloud
1. 在导航菜单中，前往 Knowledge Catalog ，然后在治理部分中选择数据分析和质量评估 。
2. 找到 dq-scan。扫描完成后，点击该扫描即可查看结果。
注意：由于大语言模型 (LLM) 是非确定性的，因此 Gemini 创建的初始规则并不完美。您应与 Gemini 迭代，以完善规则并消除误报。在此阶段看到失败的结果是完全正常的，这说明了人为回环 (HITL) 审核为何是有效数据质量治理不可或缺的持续组成部分。

清理

如需避免重复收取在本教程中创建的资源的定期结算费用，请将其删除。

删除 Knowledge Catalog 扫描

使用此 Codelab 中的特定扫描名称删除分析扫描和质量扫描：

# 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 应用场景