Policy-as-Code のデータ品質ワークフローを構築する

Policy-as-Code のデータ品質とメタデータ拡充ワークフローを構築する。このチュートリアルでは、宣言型のバージョン管理されたファイルでデータ品質の期待値を定義することで、手動プロセスから脱却する方法について説明します。

自動プロファイリングとデータ品質ルールを確立することで、信頼シグナルとビジネス コンテキストでメタデータを拡充できます。

Human-in-the-Loopのアプローチを使用すると、AI が初期ルールをドラフトし、ユーザーがそれらを確認、改良、検証することで、プロファイル統計をデータ品質フレームワークに迅速に変換できます。

目標

  • マテリアライズド ビューを使用してネストされた BigQuery データをフラット化し、Knowledge Catalog のプロファイリングを有効にする。
  • Python クライアント ライブラリを使用して、Knowledge Catalog プロファイル スキャンを実行します。
  • Antigravity 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="kc_dq_codelab"
export TABLE_ID="ga4_transactions"

    一般公開のサンプルデータも us（マルチリージョン）にあるため、ロケーションとして us（マルチリージョン）を使用します。BigQuery クエリの場合、ソースデータと宛先テーブルは同じロケーションに存在する必要があります。

  3. 必要なサービスを有効にします。

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

  4. サンプルデータと結果を保存する BigQuery データセットを作成します。

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

  5. Google Merchandise Store の公開 e コマース データセットから取得したサンプルデータを準備します。

    次の bq コマンドは、kc_dq_codelab データセットに新しいテーブル ga4_transactions を作成します。スキャンを迅速に実行するために、1 日分（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）: イベントごとに 1 行。
  • トランザクション ビュー（mv_ga4_ecommerce_transactions.sql）: トランザクションごとに 1 行。
  • アイテムビュー（mv_ga4_ecommerce_items.sql）: アイテムごとに 1 行。

プロジェクト リポジトリの devrel-demos/data-analytics/programmatic-dq ディレクトリには、これらのビューを定義する 3 つの 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 Knowledge Catalog client library
pip install google-cloud-dataplex

環境を設定してライブラリをインストールしたので、1_run_scan.py スクリプトを使用する準備が整いました。このスクリプトは、3 つのマテリアライズド ビューごとにスキャンを作成して実行することで、それらのビューをプロファイリングします。完了すると、詳細な統計サマリーが出力されます。このサマリーは、次のステップで AI を活用したデータ品質ルールを生成するために使用します。

Cloud Shell ターミナルからスクリプトを実行します。

python3 1_run_scan.py

プロファイル スキャンを確認する

新しいプロファイル スキャンは Google Cloud コンソールで確認できます。

  1. ナビゲーション メニューで、[Knowledge Catalog] に移動し、[管理] セクションの [データのプロファイリングと品質] をクリックします。
  2. 3 つのプロファイル スキャンと、それぞれの最新のジョブ ステータスが表示されます。スキャンをクリックして、詳細な結果を確認します。

プロファイル結果を JSON にエクスポートする

Antigravity CLI でプロファイル スキャンを読み取るには、その内容をローカル ファイルに抽出する必要があります。

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

Antigravity CLI を使用してデータ品質ルールを生成する

これで、Antigravity CLI を使用してローカル プロファイルのスキャン結果を読み取ることができます。

複雑なデータセットのデータ品質仕様を手動で作成すると、時間がかかり、エラーが発生しやすくなります。生成 AI エージェントを使用すると、最初の宣言型構成を数秒で作成できるため、このワークフローを高速化できます。これにより、データチームは手動の構文作成から、ビジネスに沿った高レベルの人間参加型（HITL）監視に移行できます。

Antigravity CLI を起動するには、次のコマンドを使用します。

agy

これで、品質ルールを生成する準備が整いました。CLI は現在のディレクトリ内のファイルを読み取ることができるため、新しいプロファイル スキャンデータを直接使用できます。

エージェントにプランを作成するよう指示する

まず、エージェントに統計プロファイルを分析し、行動計画を提案するよう依頼します。YAML ファイルをまだ作成しないように指示して、分析と正当化に集中させます。

インタラクティブな Antigravity CLI セッションで、次の構造化プロンプトを入力します。

# Context
You are preparing a data quality rule configuration plan for Google Cloud Knowledge Catalog based on data profile statistics.

# Input
- File Path: `./dq_profile_results.json` (contains metrics like null percentage, distinct counts, and distributions)

# Task
Analyze the input statistics and propose a step-by-step plan for establishing automated data quality rules. 
*Do not write any YAML code in this step.* Focus only on analytical planning.

# Rule Mapping Strategy
For candidate columns, match the statistical metrics to the most appropriate expectations:
- `nonNullExpectation`: Propose for columns with 0% null values in the profile.
- `setExpectation`: Propose for columns with a highly limited, stable set of categorical values.
- `rangeExpectation`: Propose for numeric columns with consistent and predictable value boundaries.

# Guidelines
- Provide a metric-based justification for each proposed rule (for example, "Recommend nonNullExpectation for column 'user_pseudo_id' because its null percentage is 0%").
- Flag volatile metrics such as hardcoded row counts that could cause false-positive alerts in production.

# Output Format
Provide your analysis and proposed rules as a structured, step-by-step markdown plan with clear headings.

エージェントは JSON ファイルを分析し、次のような構造化されたプランを返します。

Automated Data Quality Rule Configuration Plan

  Google Cloud Knowledge Catalog (Dataplex Data Quality)
  ──────
  ## Executive Summary
  This analytical planning document outlines a step-by-step strategy for
  configuring automated data quality (DQ) rules in Google Cloud
  Knowledge Catalog (formerly Dataplex Data Quality) based on profiling
  statistics.
  The dataset contains 26,489 rows representing GA4 event logs. Based on
  statistical metrics (null ratios, distinct value distributions, and data
  types), candidate columns are mapped to appropriate expectation rules.
  ──────
  ## 1. Data Profile Overview & Statistical Highlights

   Column Name     │ Data Type │ Null Ratio     │ Distinct Count │ Key Value Range / Categories
  ─────────────────┼───────────┼────────────────┼────────────────┼──────────────────────────────────────────────────
   event_date      │ STRING    │ 0.0% (0)       │ 1 (3.78e-05)   │ "20210131" (100%)
   event_timestamp │ INTEGER   │ 0.0% (0)       │ ~16,539 (0.62) │ Min: 1612051200657906, Max: 1612137595412363
   event_name      │ STRING    │ 0.0% (0)       │ 16 (0.0006)    │ page_view (35.8%), user_engagement (18.9%), etc.
   user_pseudo_id  │ STRING    │ 0.0% (0)       │ ~2,545 (0.09)  │ 18-21 characters string identifiers
   user_id         │ STRING    │ 100.0% (1.0)   │ 0 (0.0)        │ Entirely NULL
   device_category │ STRING    │ 0.0% (0)       │ 3 (0.0001)     │ desktop (57.5%), mobile (40.1%), tablet (2.4%)
   ...             │ ...       │ ...            │ ...            │ ...
  ──────
  ## 2. Rule Mapping Strategy & Analytical Justifications

  ### Step 1: Nullability Rules (nonNullExpectation)
  Propose nonNullExpectation for mandatory columns where the data profile
  demonstrates 0% null values.
  • user_pseudo_id, event_timestamp, event_name, event_date, stream_id,
    platform, device_category (Metric Justification: nullRatio is 0.0%)

  │ [!NOTE] Exclusions:
  │ • user_id: Has a nullRatio of 100.0% (unauthenticated traffic).
  │ • device_language: Has a nullRatio of 37.53%.
  ──────
  ### Step 2: Categorical Value Set Validation (setExpectation)
  Propose setExpectation for columns with a highly limited, stable set of
  categorical domain values.
  • device_category: Distinct count is exactly 3. Allowed set:
    ['desktop', 'mobile', 'tablet']
  • platform: Distinct count is 1. Allowed set expanded to:
    ['WEB', 'ANDROID', 'IOS'] to avoid over-fitting.
  • geo_continent: Distinct count is 6. Allowed set:
    ['Americas', 'Asia', 'Europe', 'Africa', 'Oceania', 'Antarctica', '(not set)']

  ──────
  ### Step 3: Numeric & Timestamp Boundary Validation (rangeExpectation)
  Propose rangeExpectation for numeric columns with consistent and predictable
  value boundaries.
  • event_timestamp: rangeExpectation requiring event_timestamp > 0 (avoid
    dynamic microsecond range hardcoding)
  • stream_id: rangeExpectation requiring positive integer stream IDs
    (stream_id > 0)

  ──────
  ## 3. Risk Warning: Volatile Metrics & Production False Positives
  │ [!WARNING] Volatile Metrics Flagged for Risk Mitigation:
  1. Hardcoded Total Row Count (rowCount = 26,489) -> Daily event volume
     fluctuates. Use dynamic volume thresholds.
  2. Hardcoded Partition Date (event_date = '20210131') -> Breaks on future
     runs. Validate against YYYYMMDD regex patterns.
  3. Exact Timestamp Range Bounds -> Enforcing these microsecond limits on
     incoming live pipelines will reject all future data.
  4. Single-Value Domain Restrictions -> Single profile sample might lack
     active streams. Set sets according to enterprise schema.

  ──────
  ## Summary Table of Proposed Rules
  
   Target Column   │ Rule Type          │ Metric-Based Justification │ Operational Considerations
  ─────────────────┼────────────────────┼────────────────────────────┼──────────────────────────────────────────────────
   user_pseudo_id  │ nonNullExpectation │ Null Ratio: 0.0%           │ Core identifier, strictly required
   event_timestamp │ nonNullExpectation │ Null Ratio: 0.0%           │ Temporal key, strictly required
   event_timestamp │ rangeExpectation   │ Min: > 0 (Microseconds)    │ Avoid hardcoding epoch min/max
   event_name      │ nonNullExpectation │ Null Ratio: 0.0%           │ Required event taxonomy key
   event_name      │ setExpectation     │ Categorical distribution   │ Map to standard GA4 event taxonomy
   device_category │ nonNullExpectation │ Null Ratio: 0.0%           │ Required form-factor dimension
   device_category │ setExpectation     │ Distinct Count: 3 values   │ ['desktop', 'mobile', 'tablet']
   ...             │ ...                │ ...                        │ ...

データ品質ルールを生成する

これは、ワークフロー全体で最も重要なステップである人間参加型（HITL）レビューです。エージェントが生成したプランは、純粋にデータの統計パターンに基づいています。エージェントは、ビジネス コンテキスト、将来のデータ変更、データの背後にある特定の意図を理解していません。人間のエキスパートとしてのあなたの役割は、この計画を検証、修正、承認してからコードに変換することです。

HITL レビュー中に検証する内容

エージェントが提案したプランを、次の主要なビジネス基準に照らして確認します。

  • 統計上の異常とビジネスの現実:
    • 理由: AI エージェントは、1 日のサンプルで null が 0% の列には null が含まれないと想定したり、限られた過去の分布に基づいて厳格な数値範囲を設定したりすることがあります。
    • アクション: 提案された境界（rangeExpectation や nonNullExpectation など）が、実際のビジネス上の制約を反映しているのか、それとも単にサンプルセットのアーティファクトなのかを確認します。
  • 揮発性指標（行数など）:
    • 理由: rowCount やテーブルの増加などの指標は、アクティブなエンタープライズ環境で毎日変化します。静的ルールは誤検出アラートの原因になります。
    • アクション: 動的トランザクション テーブルに静的しきい値を適用するルールを拒否または変更します。
  • カテゴリの完全性（setExpectation）:
    • 理由: プロファイル データには、スキャンされたサンプル ウィンドウに存在する値のみが表示されます。その期間に発生しなかった有効なカテゴリを予測することはできません。
    • アクション: カテゴリリストを公式のビジネス用語集または参照データと照合し、サンプルから除外された有効な値を追加します（たとえば、欠落している地域コードや商品カテゴリを追加します）。

プロンプト フィードバックを使用してプランを調整する

エージェントにフィードバックを提供し、コードを生成する最終コマンドを送信します。実際に受け取ったプランと、行いたい修正に基づいて、次のプロンプトを調整します。

プロンプトは単なるテンプレートです。最初の行に、お題に参加します。

このプロンプトでは、DataQualityRule 仕様に準拠する必要があります。これは、Knowledge Catalog で正確な YAML 構造が必要であり、構文エラーや古いスキーマ バージョンを防止するためです。

# Feedback & Approvals
[YOUR CORRECTIONS AND APPROVAL GO HERE. Examples:
- "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'."]

# Objective
Based on the approved analysis plan and the provided feedback, generate the final `dq_rules.yaml` file conforming to the standard `DataQualityRule` schema.

# Instructions
1. **Rule Justifications**: For every generated rule, add a YAML comment (`#`) on the line directly above it, briefly explaining the justification established in the plan.
2. **Schema Alignment**: Ensure the structure strictly adheres to the required Knowledge Catalog data quality scan specification. Refer to the `sample_rule.yaml` file in the current directory and the `DataQualityRule` class definition as the schema authority. Search for the `data_quality.py` file inside the `./dq_venv/lib/` directory to read this class definition.
3. **Data-Driven Values**: Derive all rule parameters, such as thresholds or expected values, directly from the statistical metrics in `dq_profile_results.json`.

# Constraints
- **Output Purity**: Return ONLY the raw, valid, and properly formatted YAML code block.
- Do not include conversational preambles, introductory sentences, explanations, or markdown blocks around the YAML.

エージェントは、検証済みの指示に基づいて、作業ディレクトリに dq_rules.yaml という YAML ファイルを生成します。

データ品質スキャンを作成して実行する

これで、エージェントが生成し、人間が検証したデータ品質ルールのセットが作成されました。これをスキャンとして登録してデプロイできます。

  1. /quit を入力するか、Ctrl+C を 2 回押して、Antigravity 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:kc_dq_codelab

ローカル ファイルを削除する

Python 仮想環境を無効にし、クローンを作成したリポジトリとその内容を削除します。

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

まとめ

これで、エンドツーエンドのプログラムによるデータ品質とメタデータの拡充ワークフローが構築されました。

Antigravity CLI エージェントと Knowledge Catalog を組み合わせることで、AI を活用したメタデータ拡充のための検証可能な基盤を構築できます。このアプローチにより、宣言型ルールの作成が加速されるため、データ スチュワードは人間参加型（HITL）の検証とビジネス ロジックに対するルールの改良に集中できます。これにより、データカタログがエンタープライズ AI の利用において信頼できるコンテキスト エンジンとして機能するようになります。

次のステップ