自動プロファイリングとデータ品質ルールを確立することで、信頼シグナルとビジネス コンテキストでメタデータを強化できます。
Human-in-the-Loop のアプローチ（AI が最初のルールを作成し、ユーザーがレビュー、修正、検証する）を使用すると、プロファイル統計をデータ品質フレームワークにすばやく変換できます。
目標
- マテリアライズド ビューを使用してネストされた BigQuery データをフラット化し、Knowledge Catalog のプロファイリングを有効にします。
- Python クライアント ライブラリを使用して Knowledge Catalog プロファイル スキャンを実行します。
- Antigravity CLI を使用して、プロファイル統計に基づいてデータ品質ルールを生成します。
- 人間参加型レビュー プロセスを使用して、AI が生成したルールを Knowledge Catalog 品質スキャンとして検証してデプロイします。
始める前に
始める前に、課金が有効になっている Google Cloud プロジェクトがあることを確認してください。
環境を準備する
次の手順では、Cloud Shell（クラウドで実行されるコマンドライン環境）を使用します。
コンソールの右上のツールバーで [Cloud Shell をアクティブにする] をクリックします。 Google Cloud 環境のプロビジョニングと接続にはしばらく時間がかかります。
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 クエリの場合、ソースデータと宛先テーブルは同じロケーションに存在する必要があります。必要なサービスを有効にします。
gcloud services enable dataplex.googleapis.com \ bigquery.googleapis.com \ serviceusage.googleapis.com \ aiplatform.googleapis.comサンプルデータと結果を保存する BigQuery データセットを作成します。
bq --location=us mk --dataset $PROJECT_ID:$DATASET_IDGoogle Merchandise Store の一般公開 e コマース データセットから取得したサンプルデータを準備します。
次の
bqコマンドは、kc_dq_codelabデータセットに新しいテーブルga4_transactionsを作成します。スキャンを迅速に実行するため、1 日（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）: イベントごとに 1 行。 - トランザクション ビュー （
mv_ga4_ecommerce_transactions.sql）: トランザクションごとに 1 行。 - アイテムビュー （
mv_ga4_ecommerce_items.sql）: アイテムごとに 1 行。
プロジェクト リポジトリには、これらのビューを定義する 3 つの SQL ファイルが devrel-demos/data-analytics/programmatic-dq ディレクトリに用意されています。
次の 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 コンソールで確認できます。
- ナビゲーション メニューで、[Knowledge Catalog] に移動し、[統制] セクションの [データのプロファイリングと品質] に移動します。
- 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 ファイルをまだ書き込まないように指示します。
./dq_profile_results.jsonインタラクティブな 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 ファイルを生成します。
データ品質スキャンを作成して実行する
これで、エージェントが生成し、人間が検証したデータ品質ルールのセットが用意されました。これをスキャンとして登録してデプロイできます。
/quitと入力するか、Ctrl+Cキーを 2 回押して、Antigravity 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
- ナビゲーション メニューで、[Knowledge Catalog] に移動し、[統制] セクションの [データのプロファイリングと品質] に移動します。
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 の利用のための信頼できるコンテキスト エンジンとして機能します。
次のステップ
- このアーキテクチャの背後にある理念について詳しくは、AI を活用したガバナンス: 人間による監視によるデータ品質の向上をご覧ください。
- CI/CD パイプラインを作成して、データ品質をコードとして管理します。
- カスタム SQL ルールを使用して、ビジネス固有のロジックを適用する方法を確認します。
- フィルタとサンプリングを使用してスキャンを最適化し、コストを削減します。
- Terraform で Knowledge Catalog リソースをプロビジョニングしてインフラストラクチャを自動化し、データ品質仕様とメタデータ エンリッチメントを大規模に管理します。
- 詳細については、Antigravity CLI クイックスタートをご覧ください。
- Knowledge Catalog のその他のユースケース を試す。