Durch die Einrichtung automatisierter Profiling- und Datenqualitätsregeln reichern Sie Ihre Metadaten mit Vertrauenssignalen und Geschäftskontext an.
Mit einem Human-in-the-Loop-Ansatz, bei dem KI die ersten Regeln entwirft und Sie sie überprüfen, optimieren und validieren, können Sie Profilstatistiken schnell in ein Datenqualitätsframework umwandeln.
Ziele
- Verschachtelte BigQuery-Daten mit materialisierten Ansichten reduzieren, um das Knowledge Catalog-Profiling zu ermöglichen
- Knowledge Catalog-Profilscans mit der Python-Clientbibliothek ausführen
- Mit der Antigravity-Befehlszeile können Sie Datenqualitätsregeln auf Grundlage von Profilstatistiken generieren.
- Validieren und stellen Sie KI-generierte Regeln als Knowledge Catalog-Qualitätsscans mithilfe eines Human-in-the-Loop-Überprüfungsprozesses bereit.
Hinweis
Bevor Sie beginnen, benötigen Sie ein Google Cloud -Projekt mit aktivierter Abrechnung.
Umgebung vorbereiten
Bei den folgenden Schritten wird Cloud Shell verwendet, eine Befehlszeilenumgebung, die in der Cloud ausgeführt wird.
Klicken Sie in der Google Cloud Console in der Symbolleiste rechts oben auf Cloud Shell aktivieren. Die Bereitstellung und Verbindung mit der Umgebung dauert einen kleinen Moment.
Legen Sie in Cloud Shell Ihre Projekt-ID und Umgebungsvariablen fest:
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"Verwenden Sie
us(multiregional) als Standort, da sich die öffentlichen Beispieldaten ebenfalls inus(multiregional) befinden. Bei BigQuery-Abfragen müssen sich die Quelldaten und die Zieltabelle am selben Standort befinden.Aktivieren Sie die erforderlichen Dienste:
gcloud services enable dataplex.googleapis.com \ bigquery.googleapis.com \ serviceusage.googleapis.com \ aiplatform.googleapis.comErstellen Sie ein BigQuery-Dataset zum Speichern von Beispieldaten und Ergebnissen:
bq --location=us mk --dataset $PROJECT_ID:$DATASET_IDBereiten Sie die Beispieldaten vor, die aus einem öffentlichen E-Commerce-Dataset des Google Merchandise Store stammen.
Mit dem folgenden
bq-Befehl wird eine neue Tabelle,ga4_transactions, in Ihremkc_dq_codelab-Dataset erstellt. Damit die Scans schnell ausgeführt werden, werden nur Daten von einem Tag (2021-01-31) kopiert.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`'Klonen Sie das GitHub-Repository, das die Ordnerstruktur und die unterstützenden Dateien für diese Anleitung enthält:
# 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-dqDieses Verzeichnis ist Ihr aktiver Arbeitsbereich.
Verschachtelte Daten analysieren
Mit Data Profiling findet Knowledge Catalog Statistiken für Spalten der obersten Ebene, wie Nullprozentsätze, Eindeutigkeit und Werteverteilungen in Ihren Daten, damit Sie diese besser nachvollziehen können.
Wenn Sie Statistiken für verschachtelte Felder abrufen möchten, können Sie die Daten mithilfe einer Reihe von materialisierten Ansichten vereinfachen. Dadurch wird jedes verschachtelte Feld in eine Spalte der obersten Ebene umgewandelt, die vom Knowledge Catalog profiliert werden kann.
Verschachteltes Schema abrufen
Rufen Sie das vollständige Schema Ihrer Quelltabelle ab, einschließlich aller verschachtelten Strukturen, und speichern Sie die Ausgabe als JSON-Datei:
bq show --schema --format=json $PROJECT_ID:$DATASET_ID.$TABLE_ID > bq_schema.json
Sehen Sie sich das Schema an:
jq < bq_schema.json
Die Datei bq_schema.json enthält komplexe Strukturen.
Daten mit einer materialisierten Ansicht zusammenführen
Wenn Sie verschachtelte Daten vereinfachen, sollten Sie nicht mehrere unabhängige Arrays in derselben Ansicht entnesten. Dadurch wird ein impliziter Cross Join (kartesisches Produkt) zwischen den Arrays ausgeführt, wodurch Zeilen falsch multipliziert werden und Ihre Daten beschädigt werden.
Stattdessen sollten Sie mehrere Ansichten erstellen, die jeweils für einen bestimmten Zweck konzipiert sind. Jede Ansicht sollte einen einzigen, klaren Detaillierungsgrad haben. In diesem Schritt erstellen Sie die folgenden materialisierten Ansichten:
- Sitzungsansicht (
mv_ga4_user_session_flat.sql): eine Zeile pro Ereignis. - Transaktionsansicht (
mv_ga4_ecommerce_transactions.sql): eine Zeile pro Transaktion. - Ansicht „Artikel“ (
mv_ga4_ecommerce_items.sql): eine Zeile pro Artikel.
Das Projekt-Repository enthält drei SQL-Dateien im Verzeichnis devrel-demos/data-analytics/programmatic-dq, in denen diese Ansichten definiert sind.
Führen Sie diese Dateien mit den folgenden BigQuery-Befehlen in Cloud Shell aus.
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
Profilscans mit dem Python-Client ausführen
Sie können jetzt Knowledge Catalog-Datenprofilscans für jede materialisierte Ansicht erstellen und ausführen. Das folgende Python-Skript verwendet die google-cloud-dataplex-Clientbibliothek, um diesen Vorgang zu automatisieren.
Bevor Sie das Script ausführen, erstellen Sie im Projektverzeichnis eine isolierte virtuelle Python-Umgebung.
# Create the virtual environment
python3 -m venv dq_venv
# Activate the environment
source dq_venv/bin/activate
Installieren Sie die Knowledge Catalog-Clientbibliothek in der virtuellen Umgebung.
# Install the Knowledge Catalog client library
pip install google-cloud-dataplex
Nachdem Sie die Umgebung eingerichtet und die Bibliothek installiert haben, können Sie das 1_run_scan.py-Skript verwenden. In diesem Skript werden Ihre drei materialisierten Ansichten profiliert, indem für jede ein Scan erstellt und ausgeführt wird. Anschließend wird eine ausführliche statistische Zusammenfassung ausgegeben, die Sie im nächsten Schritt zum Generieren von KI-basierten Datenqualitätsregeln verwenden.
Führen Sie das Skript über das Cloud Shell-Terminal aus.
python3 1_run_scan.py
Profilscans prüfen
Sie können sich die neuen Profilscans in der Google Cloud -Konsole ansehen.
- Rufen Sie im Navigationsmenü im Bereich Verwalten die Seiten Knowledge Catalog und Datenprofilerstellung und ‑qualität auf.
- Dort finden Sie die drei Profilscans mit dem jeweils aktuellen Jobstatus. Klicken Sie auf einen Scan, um die detaillierten Ergebnisse aufzurufen.
Profilergebnisse in JSON exportieren
Damit die Antigravity CLI Ihre Profilscans lesen kann, müssen Sie deren Inhalt in eine lokale Datei extrahieren.
Mit dem 2_dq_profile_save.py-Script können Sie den letzten erfolgreichen Scan für die Ansicht mv_ga4_user_session_flat finden, die Profildaten herunterladen und in einer Datei mit dem Namen dq_profile_results.json speichern.
python3 2_dq_profile_save.py
Wenn das Script fertig ist, wird im Verzeichnis eine Datei dq_profile_results.json erstellt. Diese Datei enthält die detaillierten statistischen Metadaten, die Sie zum Generieren von Datenqualitätsregeln benötigen. Sehen Sie sich den Inhalt mit dem folgenden Befehl an:
cat dq_profile_results.json
Datenqualitätsregeln mit der Antigravity CLI generieren
Jetzt können Sie die Antigravity-Befehlszeile verwenden, um die Ergebnisse des lokalen Profilscans zu lesen.
Das manuelle Schreiben von Datenqualitätsspezifikationen für komplexe Datasets ist zeitaufwendig und fehleranfällig. Ein KI-Agent mit generativer KI beschleunigt diesen Workflow, indem er in Sekundenschnelle eine erste deklarative Konfiguration entwirft. So können sich Datenteams von der manuellen Syntaxerstellung auf die übergeordnete, geschäftsorientierte Human-in-the-Loop-Aufsicht (HITL) konzentrieren.
Verwenden Sie den folgenden Befehl, um die Antigravity CLI zu starten:
agy
Jetzt können Sie Qualitätsregeln generieren. Da die CLI Dateien in Ihrem aktuellen Verzeichnis lesen kann, kann sie Ihre neuen Profilscandaten direkt verwenden.
KI‑Agenten auffordern, einen Plan zu erstellen
Bitten Sie den KI-Agenten zuerst, das statistische Profil zu analysieren und einen Maßnahmenplan vorzuschlagen. Weisen Sie den Assistenten an, die YAML-Datei noch nicht zu schreiben, damit er sich auf die Analyse und Begründung konzentriert.
Geben Sie in Ihrer interaktiven Antigravity CLI-Sitzung den folgenden strukturierten Prompt ein:
# 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.
Der KI-Agent analysiert die JSON-Datei und gibt einen strukturierten Plan wie den folgenden zurück:
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']
... │ ... │ ... │ ...
Datenqualitätsregeln generieren
Dies ist der wichtigste Schritt im gesamten Workflow: die Human-in-the-Loop-Prüfung (HITL). Der vom Agent generierte Plan basiert ausschließlich auf statistischen Mustern in den Daten. Der Agent versteht Ihren Geschäftskontext, zukünftige Datenänderungen oder die spezifische Intention hinter Ihren Daten nicht. Ihre Rolle als menschlicher Experte besteht darin, diesen Plan zu validieren, zu korrigieren und zu genehmigen, bevor er in Code umgewandelt wird.
Was bei der HITL-Prüfung validiert werden muss
Prüfen Sie den vom Kundenservicemitarbeiter vorgeschlagenen Plan anhand dieser wichtigen Geschäftskriterien:
- Statistische Anomalien im Vergleich zur geschäftlichen Realität:
- Grund: Ein KI-Agent geht möglicherweise davon aus, dass eine Spalte mit 0% Nullwerten in einer eintägigen Stichprobe niemals Nullwerte enthalten sollte. Oder er legt einen strengen numerischen Bereich auf Grundlage begrenzter historischer Verteilungen fest.
- Maßnahme: Prüfen Sie, ob die vorgeschlagenen Grenzen (z. B.
rangeExpectationodernonNullExpectation) tatsächliche geschäftliche Einschränkungen oder nur Artefakte der Stichprobengruppe widerspiegeln.
- Volatile Messwerte (z. B. Zeilenanzahl):
- Grund: Messwerte wie
rowCountoder das Tabellenwachstum variieren in aktiven Unternehmensumgebungen täglich. Eine statische Regel führt zu falsch-positiven Benachrichtigungen. - Aktion: Regeln ablehnen oder ändern, mit denen statische Grenzwerte für dynamische Transaktionstabellen erzwungen werden.
- Grund: Messwerte wie
- Kategorische Vollständigkeit (
setExpectation):- Grund: In den Profildaten werden nur Werte angezeigt, die im gescannten Stichprobenfenster vorhanden sind. Es kann keine gültigen Kategorien vorhersagen, die in diesem Zeitraum nicht aufgetreten sind.
- Aktion: Prüfen Sie kategorische Listen anhand Ihres offiziellen Unternehmensglossars oder Ihrer Referenzdaten und fügen Sie alle gültigen Werte hinzu, die in der Stichprobe ausgelassen wurden (z. B. fehlende Regionscodes oder Produktkategorien).
Plan mit Prompt-Feedback optimieren
Geben Sie dem Agenten Feedback und den endgültigen Befehl zum Generieren des Codes. Passen Sie den folgenden Prompt an den Plan an, den Sie tatsächlich erhalten haben, und an die Korrekturen, die Sie vornehmen möchten.
Der Prompt ist nur eine Vorlage. In der ersten Zeile fügen Sie Ihre spezifischen Korrekturen hinzu.
Für diesen Prompt ist die Einhaltung der DataQualityRule-Spezifikation erforderlich, da für den Knowledge Catalog eine präzise YAML-Struktur erforderlich ist, um Syntaxfehler oder veraltete Schemaversionen zu vermeiden.
# 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.
Der Agent generiert jetzt eine YAML-Datei namens dq_rules.yaml in Ihrem Arbeitsverzeichnis, die auf Ihren validierten Anweisungen basiert.
Datenqualitätsscan erstellen und ausführen
Sie haben jetzt einen von einem Agent generierten und von einem Menschen validierten Satz von Datenqualitätsregeln, die Sie als Scan registrieren und bereitstellen können.
Beenden Sie die Antigravity CLI, indem Sie
/quiteingeben oder zweimalCtrl+Cdrücken.Erstellen Sie dann einen Datenscan 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"Führen Sie den Scan aus:
gcloud dataplex datascans run $DQ_SCAN --location=$LOCATION --project=$PROJECT_IDMit diesem Befehl wird ein Datenqualitätsscan mit dem Namen
dq-scanerstellt.Sehen Sie sich den Fortschritt Ihres Scans im Bereich „Knowledge Catalog“ der Google Cloud Console an.
- Rufen Sie im Navigationsmenü im Bereich Verwalten die Seiten Knowledge Catalog und Datenprofilerstellung und ‑qualität auf.
- Suchen Sie nach dem
dq-scan. Wenn der Scan abgeschlossen ist, klicken Sie darauf, um die Ergebnisse zu sehen.
Bereinigen
Löschen Sie die in dieser Anleitung erstellten Ressourcen, um wiederkehrende Zahlungen zu vermeiden.
Knowledge Catalog-Scans löschen
Löschen Sie Ihr Profil und die Qualitätsscans mit den spezifischen Scannamen aus diesem 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
Beispiel-Dataset löschen
Löschen Sie Ihr temporäres BigQuery-Dataset und die zugehörigen Tabellen.
bq rm -r -f --dataset $PROJECT_ID:kc_dq_codelab
Lokale Dateien löschen
Deaktivieren Sie die virtuelle Python-Umgebung und entfernen Sie das geklonte Repository und seinen Inhalt:
deactivate
cd ../../..
rm -rf devrel-demos
Fazit
Herzlichen Glückwunsch! Sie haben einen End-to-End-Workflow für die programmatische Datenqualität und Metadatenanreicherung erstellt.
Wenn Sie einen Antigravity CLI-Agenten mit Knowledge Catalog kombinieren, schaffen Sie eine überprüfbare Grundlage für die KI-gestützte Metadatenanreicherung. Dieser Ansatz beschleunigt die Erstellung deklarativer Regeln, sodass sich Data Stewards auf die HITL-Validierung (Human-in-the-Loop) und die Optimierung von Regeln anhand der Geschäftslogik konzentrieren können. So wird sichergestellt, dass Ihr Datenkatalog als vertrauenswürdige Kontext-Engine für die Nutzung von KI im Unternehmen dient.
Nächste Schritte
- Weitere Informationen zur Philosophie hinter dieser Architektur finden Sie unter AI-Assisted Governance: Accelerating Data Quality with Human Oversight.
- Sie können die Datenqualität als Code verwalten, indem Sie eine CI/CD-Pipeline erstellen.
- Benutzerdefinierte SQL-Regeln können verwendet werden, um geschäftsspezifische Logik zu erzwingen.
- Mit Filtern und Stichproben können Sie Ihre Scans optimieren und Kosten senken.
- Automatisieren Sie Ihre Infrastruktur, indem Sie Knowledge Catalog-Ressourcen mit Terraform bereitstellen, um Ihre Datenqualitätsvorgaben und die Anreicherung von Metadaten im großen Maßstab zu verwalten.
- Weitere Informationen
- Andere Anwendungsfälle für Knowledge Catalog ausprobieren