分析数据并确保数据质量

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

借助Human-in-the-Loop方法，让 AI 起草初始规则，然后由您审核、完善和验证这些规则，您可以快速将剖析统计信息转化为数据质量框架。

目标

  • 使用具体化视图展平嵌套的 BigQuery 数据，以启用 Knowledge Catalog 分析。
  • 使用 Python 客户端库运行 Knowledge Catalog 配置文件扫描。
  • 使用 Gemini CLI 根据分析统计信息生成数据质量规则。
  • 通过人机协同审核流程，验证并部署 AI 生成的规则，将其作为 Knowledge Catalog 质量扫描。

准备工作

在开始之前，请确保您有一个启用了结算功能的 Google Cloud 项目。

准备环境

以下步骤使用 Cloud Shell，它是在云端运行的命令行环境。

  1. 在 Google Cloud 控制台中，点击右上角工具栏中的激活 Cloud Shell。预配和连接到环境需要一些时间。

  2. 在 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 查询，源数据和目标表必须位于同一位置。

  3. 启用必需的服务：

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

  4. 创建 BigQuery 数据集来存储示例数据和结果：

    bq --location=us mk --dataset $PROJECT_ID:$DATASET_ID

  5. 准备示例数据，这些数据来自 Google Merchandise Store 的公开电子商务数据集。

    以下 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`'

  6. 克隆包含本教程的文件夹结构和支持文件的 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 控制台中查看新的分析扫描。

  1. 在导航菜单中，前往 Knowledge Catalog，然后在治理部分中选择数据分析和质量评估。
  2. 您会看到列出的三项个人资料扫描作业及其最新作业状态。点击某次扫描即可查看其详细结果。

将分析结果导出为 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.

创建并运行数据质量扫描

现在，您已获得一组由代理生成的可以注册并部署为扫描的数据质量规则。

  1. 输入 /quit 或按两次 Ctrl+C 退出 Gemini CLI。

  2. 然后，在 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"

  3. 最后，运行扫描：

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

    此命令会创建一个名为 dq-scan 的数据质量扫描。

  4. 在 Google Cloud 控制台的 Knowledge Catalog 部分中查看扫描进度。

    1. 在导航菜单中，前往 Knowledge Catalog，然后在治理部分中选择数据分析和质量评估。
    2. 查找 dq-scan。扫描完成后，点击相应扫描即可查看结果。

清理

为避免因本教程中创建的资源而产生定期结算费用，请删除这些资源。

删除 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 辅助治理奠定基础。这种方法不会取代治理循环，但会加快规则创建流程，以便您可以专注于根据业务逻辑验证和完善规则。

后续步骤