En établissant des règles automatisées de profilage et de qualité des données, vous enrichissez vos métadonnées avec des signaux de confiance et un contexte métier.
Grâce à une approche Human-in-the-Loop (avec intervention humaine), dans laquelle l'IA rédige les règles initiales que vous examinez, affinez et validez, vous pouvez rapidement traduire les statistiques de profil en un framework de qualité des données.
Objectifs
- Aplatissez les données BigQuery imbriquées avec des vues matérialisées pour activer le profilage Knowledge Catalog.
- Exécutez des analyses de profil Knowledge Catalog à l'aide de la bibliothèque cliente Python.
- Utilisez l'interface de ligne de commande Antigravity pour générer des règles de qualité des données basées sur des statistiques de profil.
- Validez et déployez les règles générées par l'IA en tant qu'analyses de qualité Knowledge Catalog à l'aide d'un processus d'examen human-in-the-loop.
Avant de commencer
Avant de commencer, assurez-vous de disposer d'un Google Cloud projet avec la facturation activée.
Préparer votre environnement
Les étapes suivantes utilisent Cloud Shell, un environnement de ligne de commande exécuté dans le cloud.
Dans la Google Cloud console, cliquez sur Activer Cloud Shell dans la barre d'outils située en haut à droite. Le provisionnement et la connexion à l'environnement prennent quelques instants.
Dans Cloud Shell, configurez votre ID de projet et vos variables d'environnement :
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"Utilisez
us(multirégional) comme emplacement, car les exemples de données publiques se trouvent également dansus(multirégional). Pour les requêtes BigQuery, les données sources et la table de destination doivent se trouver au même emplacement.Activez les services requis :
gcloud services enable dataplex.googleapis.com \ bigquery.googleapis.com \ serviceusage.googleapis.com \ aiplatform.googleapis.comCréez un ensemble de données BigQuery pour stocker les exemples de données et les résultats :
bq --location=us mk --dataset $PROJECT_ID:$DATASET_IDPréparez les exemples de données, qui proviennent d'un ensemble de données d'e-commerce public du Google Merchandise Store.
La commande
bqsuivante crée une tablega4_transactionsdans votre ensemble de donnéeskc_dq_codelab. Pour que les analyses s'exécutent rapidement, elle ne copie que les données d'un seul jour (31/01/2021).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`'Clonez le dépôt GitHub contenant la structure de dossiers et les fichiers d'assistance de ce tutoriel :
# 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-dqCe répertoire est votre zone de travail active.
Profiler les données imbriquées
Avec le profilage des données, Knowledge Catalog trouve des statistiques pour les colonnes de premier niveau, telles que les pourcentages de valeurs nulles, l'unicité et les distributions de valeurs dans vos données, afin de vous aider à les comprendre.
Pour obtenir des statistiques sur les champs imbriqués, vous pouvez aplatir les données à l'aide d'un ensemble de vues matérialisées. Chaque champ imbriqué est ainsi transformé en une colonne de premier niveau que Knowledge Catalog peut profiler.
Obtenir le schéma imbriqué
Obtenez le schéma complet de votre table source, y compris toutes les structures imbriquées, et enregistrez la sortie dans un fichier JSON :
bq show --schema --format=json $PROJECT_ID:$DATASET_ID.$TABLE_ID > bq_schema.json
Afficher le schéma :
jq < bq_schema.json
Le fichier bq_schema.json révèle des structures complexes.
Aplatir les données avec une vue matérialisée
Lorsque vous aplatissez des données imbriquées, il est important de ne pas désimbriquer plusieurs tableaux indépendants dans la même vue. Cela effectue une jointure croisée implicite (produit cartésien) entre les tableaux, ce qui multiplie les lignes de manière incorrecte et corrompt vos données.
Il est préférable de créer plusieurs vues, chacune conçue pour un objectif spécifique. Chaque vue doit conserver un seul niveau de détail clair. Au cours de cette étape, vous allez créer les vues matérialisées suivantes :
- Vue plate de la session (
mv_ga4_user_session_flat.sql) : une ligne par événement. - Vue des transactions (
mv_ga4_ecommerce_transactions.sql) : une ligne par transaction. - Vue des articles (
mv_ga4_ecommerce_items.sql) : une ligne par article.
Le dépôt du projet fournit trois fichiers SQL dans le répertoire devrel-demos/data-analytics/programmatic-dq qui définissent ces vues.
Exécutez ces fichiers à partir de Cloud Shell à l'aide des commandes BigQuery suivantes.
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
Exécuter des analyses de profil avec le client Python
Vous pouvez maintenant créer et exécuter des analyses de profil de données Knowledge Catalog pour chaque vue matérialisée. Le script Python suivant utilise la bibliothèque cliente google-cloud-dataplex pour automatiser ce processus.
Avant d'exécuter le script, créez un environnement virtuel Python isolé dans le répertoire de votre projet.
# Create the virtual environment
python3 -m venv dq_venv
# Activate the environment
source dq_venv/bin/activate
Installez la bibliothèque cliente Knowledge Catalog dans l'environnement virtuel.
# Install the Knowledge Catalog client library
pip install google-cloud-dataplex
Maintenant que vous avez configuré l'environnement et installé la bibliothèque, vous pouvez utiliser le script 1_run_scan.py. Ce script profile vos trois vues matérialisées en créant et en exécutant une analyse pour chacune d'elles. Une fois terminé, il génère un résumé statistique enrichi que vous utiliserez à l'étape suivante pour générer des règles de qualité des données basées sur l'IA.
Exécutez le script à partir de votre terminal Cloud Shell.
python3 1_run_scan.py
Vérifier vos analyses de profil
Vous pouvez consulter les nouvelles analyses de profil dans la Google Cloud console.
- Dans le menu de navigation, accédez à Knowledge Catalog , puis à Qualité et profilage des données dans la section Gouverner.
- Recherchez les trois analyses de profil listées, ainsi que l'état de leur dernier job. Cliquez sur une analyse pour explorer ses résultats détaillés.
Exporter les résultats de profil au format JSON
Pour que l'interface de ligne de commande Antigravity puisse lire vos analyses de profil, vous devez extraire leur contenu dans un fichier local.
Utilisez le script 2_dq_profile_save.py pour rechercher la dernière analyse réussie de la vue mv_ga4_user_session_flat, télécharger les données de profil et les enregistrer dans un fichier nommé dq_profile_results.json.
python3 2_dq_profile_save.py
Une fois le script terminé, il crée un fichier dq_profile_results.json dans le répertoire. Ce fichier contient les métadonnées statistiques détaillées dont vous avez besoin pour générer des règles de qualité des données. Consultez son contenu en exécutant la commande suivante :
cat dq_profile_results.json
Générer des règles de qualité des données avec l'interface de ligne de commande Antigravity
Vous pouvez maintenant utiliser l'interface de ligne de commande Antigravity pour lire les résultats de l'analyse de profil locale.
L'écriture manuelle de spécifications de qualité des données pour des ensembles de données complexes prend du temps et est sujette aux erreurs. L'utilisation d'un agent d'IA générative accélère ce workflow en rédigeant une configuration déclarative initiale en quelques secondes. Les équipes chargées des données peuvent ainsi passer de la rédaction manuelle de la syntaxe à une supervision human-in-the-loop (HITL) de haut niveau et alignée sur l'activité.
Pour démarrer l'interface de ligne de commande Antigravity, utilisez la commande suivante :
agy
Vous êtes maintenant prêt à générer des règles de qualité. Comme l'CLI peut lire les fichiers de votre répertoire actuel, elle peut utiliser directement vos nouvelles données d'analyse de profil.
Demander à l'agent de créer un plan
Tout d'abord, demandez à l'agent d'analyser le profil statistique et de proposer un plan d'action. Demandez-lui de ne pas encore écrire le fichier YAML afin qu'il se concentre sur l'analyse et la justification.
Dans votre session interactive de l'interface de ligne de commande Antigravity, saisissez le prompt structuré suivant :
# 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.
L'agent analysera le fichier JSON et renverra un plan structuré comme suit :
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']
... │ ... │ ... │ ...
Générer des règles de qualité des données
Il s'agit de l'étape la plus critique de l'ensemble du workflow : l'examen human-in-the-loop (HITL). Le plan généré par l'agent est basé uniquement sur des modèles statistiques dans les données. L'agent ne comprend pas votre contexte métier, les futures modifications des données ni l'intention spécifique derrière vos données. Votre rôle en tant qu'expert humain consiste à valider, corriger et approuver ce plan avant de le transformer en code.
Éléments à valider lors de l'examen HITL
Vérifiez le plan proposé par l'agent par rapport aux critères métier de base suivants :
- Anomalies statistiques par rapport à la réalité de l'entreprise:
- Pourquoi : un agent d'IA peut supposer qu'une colonne avec 0% de valeurs nulles dans un échantillon d'un jour ne doit jamais contenir de valeurs nulles, ou définir une plage numérique stricte basée sur des distributions historiques limitées.
- Action : vérifiez si les limites suggérées (telles que
rangeExpectationounonNullExpectation) reflètent de véritables contraintes métier ou simplement des artefacts d'ensemble d'échantillons.
- Métriques volatiles (telles que le nombre de lignes):
- Pourquoi : les métriques telles que
rowCountou la croissance des tables varient quotidiennement dans les environnements d'entreprise actifs. Une règle statique générera des alertes de faux positifs. - Action : rejetez ou modifiez les règles qui appliquent des seuils statiques aux tables transactionnelles dynamiques.
- Pourquoi : les métriques telles que
- Exhaustivité catégorielle (
setExpectation) :- Pourquoi : les données de profil ne révèlent que les valeurs présentes dans la fenêtre d'échantillon analysée. Elles ne peuvent pas prédire les catégories valides qui ne se sont pas produites pendant cette période.
- Action : comparez les listes catégorielles à votre glossaire d'entreprise officiel ou à vos données de référence, en ajoutant toutes les valeurs valides qui ont été omises de l'échantillon (par exemple, en ajoutant des codes régionaux ou des catégories de produits manquants).
Affiner le plan avec les commentaires du prompt
Fournissez des commentaires à l'agent et donnez-lui la commande finale pour générer le code. Adaptez le prompt suivant en fonction du plan que vous avez réellement reçu et des corrections que vous souhaitez apporter.
Le prompt n'est qu'un modèle. La première ligne est celle où vous ajoutez vos corrections spécifiques.
Ce prompt nécessite la conformité à la spécification DataQualityRule, car Knowledge Catalog nécessite une structure YAML précise, ce qui évite les erreurs de syntaxe ou les versions de schéma obsolètes.
# 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.
L'agent génère maintenant un fichier YAML nommé dq_rules.yaml dans votre répertoire de travail, en fonction de vos instructions validées.
Créer et exécuter une analyse de la qualité des données
Vous disposez maintenant d'un ensemble de règles de qualité des données générées par un agent et validées par un humain que vous pouvez enregistrer et déployer en tant qu'analyse.
Quittez l'interface de ligne de commande Antigravity en saisissant
/quitou en appuyant deux fois surCtrl+C.Créez ensuite une analyse de données dans 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"Exécutez l'analyse :
gcloud dataplex datascans run $DQ_SCAN --location=$LOCATION --project=$PROJECT_IDCette commande crée une analyse de la qualité des données nommée
dq-scan.Vérifiez la progression de votre analyse dans la section Knowledge Catalog de la Google Cloud console.
- Dans le menu de navigation, accédez à Knowledge Catalog , puis à Qualité et profilage des données dans la section Gouverner.
- Recherchez
dq-scan. Une fois l'analyse terminée, cliquez dessus pour afficher les résultats.
Libérer de l'espace
Pour éviter des frais de facturation récurrents pour les ressources que vous avez créées dans ce tutoriel, supprimez-les.
Supprimer les analyses Knowledge Catalog
Supprimez vos analyses de profil et de qualité à l'aide des noms d'analyse spécifiques de cet atelier de programmation :
# 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
Supprimer l'ensemble de données d'exemple
Supprimez votre ensemble de données BigQuery temporaire et ses tables.
bq rm -r -f --dataset $PROJECT_ID:kc_dq_codelab
Supprimer les fichiers locaux
Désactivez l'environnement virtuel Python et supprimez le dépôt cloné et son contenu :
deactivate
cd ../../..
rm -rf devrel-demos
Conclusion
Félicitations, vous avez créé un workflow de qualité des données et d'enrichissement des métadonnées de bout en bout et programmatique.
En associant un agent d'interface de ligne de commande Antigravity à Knowledge Catalog, vous établissez une base vérifiable pour l'enrichissement des métadonnées assisté par l'IA. Cette approche accélère la création de règles déclaratives afin que les responsables des données puissent se concentrer sur la validation human-in-the-loop (HITL) et l'affinage des règles par rapport à la logique métier, ce qui garantit que votre catalogue de données agit comme un moteur de contexte fiable pour la consommation d'IA d'entreprise.
Étape suivante
- Pour en savoir plus sur la philosophie de cette architecture, consultez Gouvernance assistée par l'IA : accélérer la qualité des données avec une supervision humaine.
- Gérez la qualité des données en tant que code en créant un pipeline CI/CD.
- Découvrez comment utiliser des règles SQL personnalisées pour appliquer une logique spécifique à l'entreprise.
- Optimisez vos analyses avec des filtres et un échantillonnage pour réduire les coûts.
- Automatisez votre infrastructure en provisionnant des ressources Knowledge Catalog avec Terraform pour gérer vos spécifications de qualité des données et l'enrichissement des métadonnées à grande échelle.
- Pour en savoir plus, consultez le guide de démarrage rapide de l'interface de ligne de commande Antigravity.
- Découvrez d'autres cas d'utilisation de Knowledge Catalog