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 crea le regole iniziali e tu le esamini, le perfezioni e le convalidi, puoi tradurre rapidamente le statistiche del profilo in un framework di qualità dei dati.
Obiettivi
- Appiattisci i dati BigQuery nidificati con le viste materializzate per abilitare la profilazione di Knowledge Catalog.
- Esegui le scansioni del profilo di Knowledge Catalog utilizzando la libreria client Python.
- Utilizza l'interfaccia a riga di comando di Antigravity per generare regole di qualità dei dati basate sulle statistiche del profilo.
- Convalida ed esegui il deployment delle regole generate dall'AI come scansioni di qualità di Knowledge Catalog utilizzando un processo di revisione human-in-the-loop.
Prima di iniziare
Prima di iniziare, assicurati di avere un Google Cloud progetto con la fatturazione abilitata.
Prepara l'ambiente
I passaggi seguenti utilizzano Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.
Nella Google Cloud console, fai clic su Attiva Cloud Shell nella barra degli strumenti in alto a destra. L'ambiente richiede alcuni istanti per il provisioning e la connessione.
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(più regioni) come località, poiché anche i dati di esempio pubblici si trovano inus(più regioni). Per le query BigQuery, i dati di origine e la tabella di destinazione devono trovarsi nella stessa località.Abilita i servizi richiesti:
gcloud services enable dataplex.googleapis.com \ bigquery.googleapis.com \ serviceusage.googleapis.com \ aiplatform.googleapis.comCrea un set di dati BigQuery per archiviare i dati e i risultati di esempio:
bq --location=us mk --dataset $PROJECT_ID:$DATASET_IDPrepara i dati di esempio, che provengono da un set di dati di e-commerce pubblico del Google Merchandise Store.
Il seguente comando
bqcrea una nuova tabella,ga4_transactions, nel set di datikc_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`'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-dqQuesta directory è la tua area di lavoro attiva.
Profila i dati nidificati
Con la profilazione dei dati, Knowledge Catalog trova statistiche per le colonne di primo livello, come percentuali di valori nulli, unicità e 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
Ottieni 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 annidare più array indipendenti nella stessa visualizzazione. In questo modo, viene eseguito un cross join implicito (prodotto cartesiano) tra gli array, che moltiplica le righe in modo errato e danneggia i dati.
È preferibile creare più visualizzazioni, ognuna creata per uno scopo specifico. Ogni visualizzazione deve mantenere un singolo livello di dettaglio chiaro. In questo passaggio devi creare le seguenti viste materializzate:
- Visualizzazione piatta della sessione (
mv_ga4_user_session_flat.sql): una riga per evento. - Visualizzazione delle transazioni (
mv_ga4_ecommerce_transactions.sql): una riga per transazione. - Visualizzazione degli articoli (
mv_ga4_ecommerce_items.sql): una riga per articolo.
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 le scansioni del profilo con il client Python
Ora puoi creare ed eseguire scansioni del profilo 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 ognuna. Al termine, genera un riepilogo statistico completo che utilizzerai nel passaggio successivo per generare regole di qualità dei dati basate sull'AI.
Esegui lo script dal terminale Cloud Shell.
python3 1_run_scan.py
Controlla le scansioni del profilo
Puoi controllare le nuove scansioni del profilo nella Google Cloud console.
- Nel menu di navigazione, vai a Knowledge Catalog e Profilazione e qualità dei dati nella sezione Gestisci.
- 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 profilo, devi estrarne i contenuti in un file locale.
Utilizza lo script 2_dq_profile_save.py per trovare l'ultima scansione riuscita per la visualizzazione mv_ga4_user_session_flat, scaricare i dati del profilo e salvarli 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 regole di qualità dei dati. Dai un'occhiata ai contenuti eseguendo il seguente comando:
cat dq_profile_results.json
Genera regole di qualità dei dati con Antigravity CLI
Ora puoi utilizzare l'Antigravity CLI per leggere i risultati della scansione di profilazione locale.
La scrittura manuale delle specifiche di qualità dei dati per set di dati complessi richiede tempo e può causare errori. L'utilizzo di un agente AI generativo accelera questo workflow creando una configurazione dichiarativa iniziale in pochi secondi. In questo modo, i team di dati possono passare dalla stesura manuale della sintassi alla 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 nuovi dati di scansione di profilazione.
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 simile al 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 di 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 dei dati o l'intento specifico alla base dei dati. Il tuo ruolo di esperto umano è quello di convalidare, correggere e approvare questo piano prima di trasformarlo in codice.
Cosa convalidare durante la revisione HITL
Controlla il piano proposto dall'agente rispetto a questi criteri aziendali principali:
- Anomalie statistiche rispetto alla realtà aziendale:
- Motivo: un agente AI potrebbe presupporre che una colonna con lo 0% di valori nulli in un campione di un giorno non debba mai contenere valori nulli oppure impostare un intervallo numerico rigoroso basato su distribuzioni storiche limitate.
- Azione: verifica se i limiti suggeriti (ad esempio
rangeExpectationononNullExpectation) riflettono vincoli aziendali reali o semplicemente artefatti del set di campioni.
- Metriche volatili (ad esempio conteggi delle righe):
- Motivo: metriche come
rowCounto la crescita delle tabelle variano quotidianamente negli ambienti aziendali attivi. Una regola statica genererà avvisi di falsi positivi. - Azione: rifiuta o modifica le regole che applicano soglie statiche alle tabelle transazionali dinamiche.
- Motivo: metriche come
- Completezza categorica (
setExpectation):- Motivo: i dati del profilo rivelano solo i valori presenti nella finestra di esempio scansionata. Non può prevedere categorie valide che non si sono verificate durante quel periodo di tempo.
- Azione: controlla gli elenchi categorici rispetto al glossario aziendale ufficiale o ai dati di riferimento, aggiungendo eventuali valori validi omessi dal campione (ad esempio, aggiungendo codici di regione o categorie di prodotti mancanti).
Perfeziona il piano con il feedback del prompt
Fornisci feedback all'agente e impartisci il comando finale per generare il codice. Adatta il seguente prompt in base al piano che hai ricevuto e alle correzioni che vuoi apportare.
Il prompt è solo un modello. Nella prima riga devi aggiungere 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 una scansione della qualità dei dati
Ora hai un insieme di regole di qualità dei dati generate dall'agente e convalidate da persone fisiche che puoi registrare ed eseguire il deployment come scansione.
Esci dall'interfaccia a riga di comando di Antigravity inserendo
/quito premendoCtrl+Cdue volte.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"Esegui la scansione:
gcloud dataplex datascans run $DQ_SCAN --location=$LOCATION --project=$PROJECT_IDQuesto comando crea una scansione della qualità dei dati denominata
dq-scan.Controlla lo stato di avanzamento della scansione nella sezione Knowledge Catalog della Google Cloud console.
- Nel menu di navigazione, vai a Knowledge Catalog e Profilazione e qualità dei dati nella sezione Gestisci.
- Trova
dq-scan. Al termine della scansione, fai clic sulla scansione per visualizzare i risultati.
Libera spazio
Per evitare addebiti di fatturazione ricorrenti per le risorse create in questo tutorial, eliminale.
Elimina le scansioni di Knowledge Catalog
Elimina le scansioni del profilo e della qualità utilizzando i nomi specifici delle scansioni 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 e programmatico di qualità dei dati e arricchimento dei metadati.
Associando un agente Antigravity CLI a Knowledge Catalog, crei una base verificabile per l'arricchimento dei metadati assistito dall'AI. Questo approccio accelera la creazione di regole dichiarative in modo che i responsabili dei dati 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 attendibile per il consumo di AI aziendale.
Passaggi successivi
- Scopri di più sulla filosofia alla base di questa architettura in Governance assistita dall'AI: accelerare la qualità dei dati con la supervisione umana.
- Gestisci la qualità dei dati come codice creando una pipeline CI/CD.
- Scopri come utilizzare le regole SQL personalizzate per applicare la logica specifica dell'attività.
- Ottimizza le scansioni con filtri e campionamento per ridurre i costi.
- Automatizza l'infrastruttura eseguendo il provisioning delle risorse di Knowledge Catalog con Terraform per gestire le specifiche di qualità dei dati e l'arricchimento dei metadati su larga scala.
- Scopri di più utilizzando la guida rapida di Antigravity CLI.
- Prova altri casi d'uso di Knowledge Catalog