Crea un flusso di lavoro di qualità dei dati policy-as-code

Crea un workflow di arricchimento dei metadati e di qualità dei dati basato su policy-as-code. Questo tutorial spiega come andare oltre i processi manuali definendo le aspettative di qualità dei dati in file dichiarativi con controllo della versione.

Stabilendo regole di profilazione e qualità dei dati automatizzate, arricchisci i metadati con indicatori di attendibilità e contesto aziendale.

Utilizzando un approccio Human-in-the-Loop, in cui l'AI elabora le regole iniziali e tu le rivedi, le perfezioni e le convalidi, puoi tradurre rapidamente le statistiche del profilo in un framework per la qualità dei dati.

Obiettivi

  • Appiattisci i dati BigQuery nidificati con viste materializzate per abilitare la profilazione di Knowledge Catalog.
  • Esegui scansioni di profilazione di Knowledge Catalog utilizzando la libreria client Python.
  • Utilizza l'interfaccia a riga di comando Antigravity per generare regole di qualità dei dati in base alle statistiche del profilo.
  • Convalida ed esegui il deployment delle regole generate dall'AI come scansioni della qualità di Knowledge Catalog utilizzando un processo di revisione Human-in-the-Loop.

Prima di iniziare

Prima di iniziare, assicurati di avere un progetto Google Cloud con la fatturazione abilitata.

prepara l'ambiente

I passaggi seguenti utilizzano Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.

  1. Nella console Google Cloud , fai clic su Attiva Cloud Shell nella barra degli strumenti in alto a destra. Bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente.

  2. In Cloud Shell, configura l'ID progetto e le variabili di ambiente:

    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"

    Utilizza us (multiregionale) come località, poiché anche i dati di esempio pubblici si trovano in us (multiregionale). Per le query BigQuery, i dati di origine e la tabella di destinazione devono trovarsi nella stessa località.

  3. Abilita i servizi richiesti:

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

  4. Crea un set di dati BigQuery per archiviare i dati campionati e i risultati:

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

  5. Preparare i dati campionati, che provengono da un set di dati di e-commerce pubblico del Google Merchandise Store.

    Il seguente comando bq crea una nuova tabella, ga4_transactions, nel set di dati kc_dq_codelab. Per garantire che le scansioni vengano eseguite rapidamente, copia solo i dati di un giorno (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`'

  6. Clona il repository GitHub che contiene la struttura delle cartelle e i file di supporto per questo tutorial:

    # 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

    Questa directory è la tua area di lavoro attiva.

Profila dati nidificati

Con la profilazione dei dati, Knowledge Catalog trova le statistiche per le colonne di primo livello, come le percentuali di valori nulli, l'unicità e le distribuzioni dei valori nei dati per aiutarti a comprenderli.

Per ottenere statistiche per i campi nidificati, puoi appiattire i dati utilizzando un insieme di viste materializzate. In questo modo, ogni campo nidificato viene trasformato in una colonna di primo livello che Knowledge Catalog può profilare.

Ottieni lo schema nidificato

Recupera lo schema completo della tabella di origine, incluse tutte le strutture nidificate, e salva l'output come file JSON:

bq show --schema --format=json $PROJECT_ID:$DATASET_ID.$TABLE_ID > bq_schema.json

Visualizza lo schema:

jq < bq_schema.json

Il file bq_schema.json rivela strutture complesse.

Appiattisci i dati con una vista materializzata

Quando appiattisci i dati nidificati, è importante non annullare la nidificazione di più array indipendenti nella stessa visualizzazione. In questo modo viene eseguita una cross join implicita (prodotto cartesiano) tra gli array, che moltiplica le righe in modo errato e danneggia i dati.

È meglio creare più visualizzazioni, ognuna creata per uno scopo specifico. Ogni visualizzazione deve mantenere un unico livello di dettaglio chiaro. In questo passaggio, creerai le seguenti viste materializzate:

  • Visualizzazione piatta della sessione (mv_ga4_user_session_flat.sql): una riga per evento.
  • Visualizzazione Transazioni (mv_ga4_ecommerce_transactions.sql): una riga per transazione.
  • Visualizzazione Elementi (mv_ga4_ecommerce_items.sql): una riga per elemento.

Il repository del progetto fornisce tre file SQL nella directory devrel-demos/data-analytics/programmatic-dq che definiscono queste visualizzazioni.

Esegui questi file da Cloud Shell utilizzando i seguenti comandi BigQuery.

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

Esegui scansioni del profilo con il client Python

Ora puoi creare ed eseguire scansioni di profilazione dei dati di Knowledge Catalog per ogni vista materializzata. Il seguente script Python utilizza la libreria client google-cloud-dataplex per automatizzare questo processo.

Prima di eseguire lo script, crea un ambiente virtuale Python isolato nella directory del progetto.

# Create the virtual environment
python3 -m venv dq_venv

# Activate the environment
source dq_venv/bin/activate

Installa la libreria client di Knowledge Catalog all'interno dell'ambiente virtuale.

# Install the Knowledge Catalog client library
pip install google-cloud-dataplex

Ora che hai configurato l'ambiente e installato la libreria, puoi utilizzare lo script 1_run_scan.py. Questo script profila le tre viste materializzate creando ed eseguendo una scansione per ciascuna. Al termine, genera un riepilogo statistico dettagliato che utilizzerai nel passaggio successivo per generare regole sulla qualità dei dati basate sull'AI.

Esegui lo script dal terminale Cloud Shell.

python3 1_run_scan.py

Controlla le analisi del profilo

Puoi controllare le nuove scansioni del profilo nella console Google Cloud .

  1. Nel menu di navigazione, vai a Knowledge Catalog e Profilazione e qualità dei dati nella sezione Governa.
  2. Trova le tre scansioni del profilo elencate, insieme allo stato del job più recente. Fai clic su una scansione per esplorarne i risultati dettagliati.

Esporta i risultati del profilo in JSON

Affinché Antigravity CLI possa leggere le scansioni del tuo profilo, devi estrarre i contenuti in un file locale.

Utilizza lo script 2_dq_profile_save.py per trovare l'ultima scansione riuscita per la vista mv_ga4_user_session_flat, scarica i dati del profilo e salvali in un file denominato dq_profile_results.json.

python3 2_dq_profile_save.py

Al termine dello script, viene creato un file dq_profile_results.json nella directory. Questo file contiene i metadati statistici dettagliati necessari per generare le regole di qualità dei dati. Dai un'occhiata ai suoi contenuti eseguendo questo comando:

cat dq_profile_results.json

Genera regole sulla qualità dei dati con Antigravity CLI

Ora puoi utilizzare l'Antigravity CLI per leggere i risultati della scansione del profilo locale.

La scrittura manuale delle specifiche di qualità dei dati per set di dati complessi richiede molto tempo ed è soggetta a errori. L'utilizzo di un agente AI generativa accelera questo flusso di lavoro, creando una bozza di configurazione dichiarativa iniziale in pochi secondi. In questo modo, i team di dati possono passare dalla stesura manuale della sintassi a una supervisione human-in-the-loop (HITL) di alto livello e allineata al business.

Per avviare l'interfaccia a riga di comando di Antigravity, utilizza il seguente comando:

agy

Ora puoi generare regole di qualità. Poiché l'interfaccia a riga di comando può leggere i file nella directory corrente, può utilizzare direttamente i dati di scansione del nuovo profilo.

Chiedi all'agente di creare un piano

Innanzitutto, chiedi all'agente di analizzare il profilo statistico e di proporre un piano d'azione. Chiedigli di non scrivere ancora il file YAML, in modo che si concentri sull'analisi e sulla giustificazione.

Nella sessione interattiva di Antigravity CLI, inserisci il seguente prompt strutturato:

# 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'agente analizzerà il file JSON e restituirà un piano strutturato come il seguente:

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']
   ...             │ ...                │ ...                        │ ...

Genera regole sulla qualità dei dati

Questo è il passaggio più importante dell'intero flusso di lavoro: la revisione human-in-the-loop (HITL). Il piano generato dall'agente si basa esclusivamente su pattern statistici nei dati. L'agente non comprende il contesto aziendale, le modifiche future ai dati o l'intent specifico alla base dei dati. Il tuo ruolo di esperto umano è convalidare, correggere e approvare questo piano prima di trasformarlo in codice.

Cosa convalidare durante la revisione HITL

Verifica il piano proposto dall'agente in base ai seguenti criteri aziendali fondamentali:

  • Anomalie statistiche e realtà aziendale:
    • Perché: un agente AI potrebbe presumere che una colonna con lo 0% di valori nulli in un campione di un giorno non debba mai contenere valori nulli o impostare un intervallo numerico rigoroso in base a distribuzioni storiche limitate.
    • Azione: verifica se i limiti suggeriti (ad esempio rangeExpectation o nonNullExpectation) riflettono i veri vincoli aziendali o semplicemente gli artefatti del set di esempi.
  • Metriche volatili (come i conteggi delle righe):
    • Perché: metriche come rowCount o la crescita delle tabelle variano ogni giorno negli ambienti aziendali attivi. Una regola statica causerà avvisi di falsi positivi.
    • Azione: rifiuta o modifica le regole che applicano soglie statiche alle tabelle transazionali dinamiche.
  • Completezza categoriale (setExpectation):
    • Perché: i dati del profilo rivelano solo i valori presenti nella finestra di esempio analizzata. Non può prevedere categorie valide che non si sono verificate in quel periodo di tempo.
    • Azione: confronta gli elenchi di categorie con il glossario aziendale ufficiale o con i dati di riferimento, aggiungendo eventuali valori validi omessi dal campione (ad esempio, aggiungendo codici regione o categorie di prodotto mancanti).

Perfeziona il piano con un feedback rapido

Fornisci un feedback all'agente e impartisci il comando finale per generare il codice. Adatta il seguente prompt in base al piano che hai effettivamente ricevuto e alle correzioni che vuoi apportare.

Il prompt è solo un template. La prima riga è quella in cui aggiungi le correzioni specifiche.

Questo prompt richiede la conformità alla specifica DataQualityRule perché Knowledge Catalog richiede una struttura YAML precisa, evitando errori di sintassi o versioni dello schema obsolete.

# 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'agente genera ora un file YAML denominato dq_rules.yaml nella directory di lavoro, in base alle istruzioni convalidate.

Crea ed esegui un'analisi della qualità dei dati

Ora hai un insieme di regole di qualità dei dati generate dall'agente e convalidate da un essere umano che puoi registrare ed eseguire il deployment come scansione.

  1. Esci dall'interfaccia a riga di comando di Antigravity inserendo /quit o premendo Ctrl+C due volte.

  2. Quindi, crea una scansione dei dati in 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. Esegui la scansione:

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

    Questo comando crea una scansione della qualità dei dati denominata dq-scan.

  4. Controlla l'avanzamento della scansione nella sezione Knowledge Catalog della console Google Cloud .

    1. Nel menu di navigazione, vai a Knowledge Catalog e Profilazione e qualità dei dati nella sezione Governa.
    2. Trova la risorsa dq-scan. Al termine della scansione, fai clic sulla scansione per visualizzare i risultati.

Esegui la pulizia

Per evitare addebiti di fatturazione ricorrenti per le risorse che hai creato in questo tutorial, eliminale.

Elimina le scansioni di Knowledge Catalog

Elimina il profilo e le scansioni della qualità utilizzando i nomi delle scansioni specifici di questo 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

Elimina il set di dati di esempio

Elimina il set di dati BigQuery temporaneo e le relative tabelle.

bq rm -r -f --dataset $PROJECT_ID:kc_dq_codelab

Elimina i file locali

Disattiva l'ambiente virtuale Python e rimuovi il repository clonato e i relativi contenuti:

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

Conclusione

Congratulazioni, hai creato un flusso di lavoro end-to-end di qualità dei dati e arricchimento dei metadati programmatico.

Abbinando un agente Antigravity CLI a Knowledge Catalog, stabilisci una base verificabile per l'arricchimento dei metadati assistito dall'AI. Questo approccio accelera la creazione di regole dichiarative, in modo che i Data Steward possano concentrarsi sulla convalida Human-in-the-Loop (HITL) e sul perfezionamento delle regole in base alla logica di business, garantendo che il catalogo dei dati funga da motore di contesto affidabile per l'utilizzo dell'AI aziendale.

Passaggi successivi