Créer un workflow de qualité des données basé sur le principe "policy-as-code"

Créer un workflow de qualité des données et d'enrichissement des métadonnées basé sur des règles en tant que code. Ce tutoriel explique comment aller au-delà des processus manuels en définissant les attentes en matière de qualité des données dans des fichiers déclaratifs avec contrôle des versions.

En établissant des règles de profilage et de qualité des données automatisées, vous enrichissez vos métadonnées avec des signaux de confiance et un contexte métier.

En utilisant une approche Human-in-the-Loop (avec intervention humaine), où l'IA rédige les règles initiales et où vous les examinez, les affinez et les 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 profilage Knowledge Catalog à l'aide de la bibliothèque cliente Python.
  • Utilisez la CLI Antigravity pour générer des règles de qualité des données en fonction des statistiques de profil.
  • Validez et déployez des règles générées par l'IA en tant qu'analyses de qualité Knowledge Catalog à l'aide d'un processus de révision Human-in-the-Loop.

Avant de commencer

Avant de commencer, assurez-vous de disposer d'un projet Google Cloud pour lequel la facturation est activée.

Préparer votre environnement

Les étapes suivantes utilisent Cloud Shell, un environnement de ligne de commande exécuté dans le cloud.

  1. Dans la console Google Cloud , cliquez sur Activer Cloud Shell dans la barre d'outils en haut à droite. Le provisionnement et la connexion à l'environnement prennent quelques instants.

  2. 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 publics se trouvent également dans us (multirégional). Pour les requêtes BigQuery, les données sources et la table de destination doivent se trouver au même emplacement.

  3. Activez les services requis :

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

  4. Créez un ensemble de données BigQuery pour stocker les données échantillonnées et les résultats :

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

  5. Préparez les exemples de données, qui proviennent d'un ensemble de données d'e-commerce public du Google Merchandise Store.

    La commande bq suivante crée une table, ga4_transactions, dans votre ensemble de données kc_dq_codelab. Pour que les analyses s'exécutent rapidement, il 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`'

  6. Clonez le dépôt GitHub contenant la structure de dossiers et les fichiers associés pour 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-dq

    Ce 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, comme les pourcentages de valeurs nulles, l'unicité et les distributions de valeurs dans vos données, pour 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 le résultat 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 des données avec une vue matérialisée

Lorsque vous aplatissez des données imbriquées, il est important de ne pas annuler l'imbrication de 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 niveau de détail unique et clair. Dans cette étape, vous allez créer les vues matérialisées suivantes :

  • Vue de session à plat (mv_ga4_user_session_flat.sql) : une ligne par événement.
  • Vue des transactions (mv_ga4_ecommerce_transactions.sql) : une ligne par transaction.
  • Vue "Éléments" (mv_ga4_ecommerce_items.sql) : une ligne par élément.

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 depuis 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 désormais créer et exécuter des analyses de profilage des 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 êtes prêt à 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 l'analyse terminée, elle 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 optimisées par l'IA.

Exécutez le script depuis 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 console Google Cloud .

  1. Dans le menu de navigation, accédez à Knowledge Catalog et à Qualité et profilage des données dans la section Gérer.
  2. Vous trouverez 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 du profil au format JSON

Pour que la CLI 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 trouver la dernière analyse réussie de la vue mv_ga4_user_session_flat, téléchargez les données de profil et enregistrez-les 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. Examinez 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 la CLI Antigravity

Vous pouvez maintenant utiliser la CLI Antigravity pour lire les résultats de l'analyse du profil local.

La rédaction 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. Cela permet aux équipes de données de passer de la rédaction manuelle de la syntaxe à une supervision de haut niveau, alignée sur l'activité, avec intervention humaine (HITL).

Pour démarrer la CLI Antigravity, utilisez la commande suivante :

agy

Vous êtes maintenant prêt à générer des règles de qualité. Comme la CLI peut lire les fichiers de votre répertoire actuel, elle peut utiliser directement les données de votre nouvelle 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 Antigravity CLI, 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

C'est l'étape la plus critique de tout le workflow : l'examen Human-in-the-Loop (avec intervention humaine) (HITL). Le plan généré par l'agent est basé uniquement sur des schémas statistiques dans les données. L'agent ne comprend pas le contexte de votre entreprise, les modifications futures des données ni l'intention spécifique derrière vos données. En tant qu'expert humain, votre rôle est de 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 d'activité principaux suivants :

  • Anomalies statistiques et réalité commerciale :
    • Pourquoi : un agent IA peut supposer qu'une colonne contenant 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 en fonction de distributions historiques limitées.
    • Action : vérifiez si les limites suggérées (comme rangeExpectation ou nonNullExpectation) reflètent de véritables contraintes commerciales ou simplement des artefacts d'ensemble d'échantillons.
  • Métriques volatiles (telles que le nombre de lignes) :
    • Pourquoi : Les métriques telles que rowCount ou la croissance des tables varient quotidiennement dans les environnements d'entreprise actifs. Une règle statique génère des alertes de faux positifs.
    • Action : rejetez ou modifiez les règles qui appliquent des seuils statiques aux tables transactionnelles dynamiques.
  • 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. Il ne peut 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 les valeurs valides qui ont été omises de l'échantillon (par exemple, en ajoutant des codes de région ou des catégories de produits manquants).

Affiner le plan avec des commentaires sur les prompts

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 reçu et des corrections que vous souhaitez apporter.

La requête n'est qu'un modèle. La première ligne vous permet d'ajouter vos corrections spécifiques.

Cette requête doit être conforme à 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 désormais 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.

  1. Quittez la CLI Antigravity en saisissant /quit ou en appuyant deux fois sur Ctrl+C.

  2. Ensuite, créez 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"

  3. Exécutez l'analyse :

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

    Cette commande crée une analyse de la qualité des données nommée dq-scan.

  4. Vérifiez la progression de l'analyse dans la section Knowledge Catalog de la console Google Cloud .

    1. Dans le menu de navigation, accédez à Knowledge Catalog et à Qualité et profilage des données dans la section Gérer.
    2. Recherchez l'élément dq-scan. Une fois l'analyse terminée, cliquez dessus pour afficher les résultats.

Effectuer un nettoyage

Pour éviter que des frais récurrents ne vous soient facturés 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'exemple d'ensemble de données

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, puis supprimez le dépôt cloné et son contenu :

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

Conclusion

Félicitations ! Vous avez créé un workflow programmatique de bout en bout pour la qualité des données et l'enrichissement des métadonnées.

En associant un agent CLI 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, ce qui permet aux gestionnaires de données de se concentrer sur la validation avec intervention humaine (HITL) et d'affiner les règles en fonction de la logique métier. Votre catalogue de données sert ainsi de moteur de contexte fiable pour l'utilisation de l'IA en entreprise.

Étapes suivantes