Durch die Einrichtung automatisierter Profilerstellungs- und Datenqualitätsregeln reichern Sie Ihre Metadaten mit Vertrauenssignalen und Geschäftskontext an.
Mit einem Human-in-the-Loop-Ansatz, bei dem die KI die ersten Regeln entwirft und Sie diese überprüfen, verfeinern und validieren, können Sie Profilstatistiken schnell in ein Datenqualitäts-Framework übersetzen.
Ziele
- Verschachtelte BigQuery-Daten mit materialisierten Ansichten vereinfachen, um Knowledge Catalog-Profiling zu ermöglichen.
- Knowledge Catalog-Profilscans mit der Python-Clientbibliothek ausführen
- Verwenden Sie die Antigravity CLI, um Regeln für die Datenqualität basierend auf Profilstatistiken zu 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
In 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_IDBeispieldaten vorbereiten, die aus einem öffentlichen E-Commerce-Dataset des Google Merchandise Store stammen.
Mit dem folgenden
bq-Befehl wird eine neue Tabellega4_transactionsim Datasetkc_dq_codelaberstellt. Damit Scans schnell ausgeführt werden, werden nur Daten von einem Tag (31.01.2021) 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.
Profil für verschachtelte Daten erstellen
Mit der Datenprofilerstellung findet Knowledge Catalog Statistiken für Spalten auf oberster Ebene, z. B. Nullprozentsätze, Eindeutigkeit und Werteverteilungen in Ihren Daten, um Ihnen das Verständnis zu erleichtern.
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, für die Knowledge Catalog ein Profil erstellen 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 vereinfachen
Wenn Sie verschachtelte Daten vereinfachen, ist es wichtig, nicht mehrere unabhängige Arrays in derselben Ansicht zu entpacken. Dadurch wird ein impliziter Cross Join (kartesisches Produkt) zwischen den Arrays ausgeführt, wodurch Zeilen fälschlicherweise multipliziert und Ihre Daten beschädigt werden.
Erstellen Sie stattdessen am besten mehrere Ansichten, die jeweils für einen bestimmten Zweck gedacht sind. Jede Ansicht sollte einen einzigen, klaren Detaillierungsgrad haben. In diesem Schritt erstellen Sie die folgenden materialisierten Ansichten:
- Sitzung – flache Ansicht (
mv_ga4_user_session_flat.sql): eine Zeile pro Ereignis. - Transaktionsansicht (
mv_ga4_ecommerce_transactions.sql): eine Zeile pro Transaktion. - Artikelansicht (
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 über die Cloud Shell mit den folgenden BigQuery-Befehlen 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. Im folgenden Python-Skript wird die Clientbibliothek google-cloud-dataplex verwendet, um diesen Prozess zu automatisieren.
Bevor Sie das Script ausführen, erstellen Sie eine isolierte virtuelle Python-Umgebung in Ihrem Projektverzeichnis.
# 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 Script 1_run_scan.py verwenden. Mit diesem Script werden Ihre drei materialisierten Ansichten profiliert, indem für jede ein Scan erstellt und ausgeführt wird. Nach Abschluss wird eine umfangreiche statistische Zusammenfassung ausgegeben, die Sie im nächsten Schritt verwenden, um KI-basierte Regeln für die Datenqualität zu generieren.
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 Console ansehen.
- Gehen Sie im Navigationsmenü im Abschnitt Verwalten zu Knowledge Catalog und Datenprofilerstellung und ‑qualität.
- Hier finden Sie Ihre drei Profilscans und den Status des jeweils letzten Jobs. 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 Inhalte in eine lokale Datei extrahieren.
Verwenden Sie das Script 2_dq_profile_save.py, um den letzten erfolgreichen Scan für die Ansicht mv_ga4_user_session_flat zu finden, die Profildaten herunterzuladen und in einer Datei mit dem Namen dq_profile_results.json zu speichern.
python3 2_dq_profile_save.py
Wenn das Script abgeschlossen ist, wird im Verzeichnis eine dq_profile_results.json-Datei 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 CLI verwenden, um die Ergebnisse des lokalen Profilscans zu lesen.
Das manuelle Schreiben von Datenqualitätsspezifikationen für komplexe Datasets ist zeitaufwendig und fehleranfällig. Mit einem KI-Agenten für generative KI wird dieser Workflow beschleunigt, da in Sekundenschnelle eine erste deklarative Konfiguration erstellt wird. So können Datenteams von der manuellen Syntaxerstellung zu einer übergeordneten, geschäftsorientierten Human-in-the-Loop-Überwachung (HITL) übergehen.
Verwenden Sie den folgenden Befehl, um die Antigravity CLI zu starten:
agy
Jetzt können Sie Qualitätsregeln generieren. Da die Befehlszeile Dateien in Ihrem aktuellen Verzeichnis lesen kann, kann sie die neuen Profildaten direkt verwenden.
KI-Agenten auffordern, einen Plan zu erstellen
Bitten Sie den KI-Agenten zuerst, das statistische Profil zu analysieren und einen Aktionsplan vorzuschlagen. Weisen Sie es an, die YAML-Datei noch nicht zu schreiben, damit es sich auf die Analyse und Begründung konzentriert.
Geben Sie in der 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 KI-Agenten erstellte Plan basiert ausschließlich auf statistischen Mustern in den Daten. Der KI-Agent versteht weder Ihren Geschäftskontext noch zukünftige Datenänderungen oder die spezifische Absicht hinter Ihren Daten. 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-Überprüfung validiert werden muss
Prüfen Sie den vom KI-Agenten vorgeschlagenen Plan anhand dieser zentralen Geschäftskriterien:
- Statistische Anomalien im Vergleich zur geschäftlichen Realität:
- Warum: Ein KI-Agent könnte davon ausgehen, dass eine Spalte mit 0% Nullwerten in einer eintägigen Stichprobe niemals Nullwerte enthalten sollte, oder einen strengen numerischen Bereich basierend auf begrenzten historischen Verteilungen festlegen.
- Maßnahme: Prüfen Sie, ob die vorgeschlagenen Grenzen (z. B.
rangeExpectationodernonNullExpectation) tatsächliche geschäftliche Einschränkungen oder lediglich Artefakte des Stichprobensatzes widerspiegeln.
- Flüchtige Messwerte (z. B. Zeilenanzahl):
- Warum: Messwerte wie
rowCountoder das Tabellenwachstum variieren in aktiven Unternehmensumgebungen täglich. Eine statische Regel führt zu falsch positiven Warnungen. - Aktion: Regeln ablehnen oder ändern, die statische Schwellenwerte für dynamische Transaktionstabellen erzwingen.
- Warum: Messwerte wie
- Kategorische Vollständigkeit (
setExpectation):- Warum: Profildaten zeigen nur Werte, die im gescannten Stichprobenfenster vorhanden sind. Es können keine gültigen Kategorien vorhergesagt werden, die in diesem Zeitraum nicht aufgetreten sind.
- Maßnahme: Vergleichen Sie kategorische Listen mit Ihrem offiziellen Unternehmensglossar oder Ihren Referenzdaten und fügen Sie alle gültigen Werte hinzu, die in der Stichprobe weggelassen wurden (z. B. fehlende Regionscodes oder Produktkategorien).
Plan mit Prompt-Feedback optimieren
Geben Sie dem KI-Agenten Feedback und den endgültigen Befehl, den Code zu generieren. 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.
Dieser Prompt erfordert die Einhaltung der DataQualityRule-Spezifikation, da Knowledge Catalog eine genaue YAML-Struktur erfordert, 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 KI-Agent generiert jetzt basierend auf Ihren validierten Anweisungen eine YAML-Datei mit dem Namen dq_rules.yaml in Ihrem Arbeitsverzeichnis.
Datenqualitätsscan erstellen und ausführen
Sie haben jetzt einen von einem KI-Agenten generierten und von einem Menschen validierten Satz von Datenqualitätsregeln, die Sie registrieren und als Scan 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.Sie können den Fortschritt des Scans im Bereich „Knowledge Catalog“ der Google Cloud Console prüfen.
- Rufen Sie im Navigationsmenü im Abschnitt Verwalten die Option Knowledge Catalog und dann Datenprofilerstellung und ‑qualität auf.
- Suchen Sie nach
dq-scan. Klicken Sie nach Abschluss des Scans auf den Scan, um die Ergebnisse aufzurufen.
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 Ihre 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 das temporäre 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
Glückwunsch! Sie haben einen programmatischen End-to-End-Workflow für Datenqualität und Metadatenanreicherung erstellt.
Durch die Kombination eines Antigravity-CLI-Agenten mit Knowledge Catalog 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 Human-in-the-Loop-Validierung (HITL) und die Verfeinerung von Regeln anhand der Geschäftslogik konzentrieren können. So wird sichergestellt, dass Ihr Datenkatalog als vertrauenswürdige Kontext-Engine für die KI-Nutzung im Unternehmen fungiert.
Nächste Schritte
- Weitere Informationen zur Philosophie hinter dieser Architektur finden Sie unter KI-gestützte Governance: Datenqualität mit menschlicher Aufsicht beschleunigen.
- Verwalten Sie die Datenqualität als Code, indem Sie eine CI/CD-Pipeline erstellen.
- Sie können benutzerdefinierte SQL-Regeln verwenden, um geschäftsspezifische Logik zu erzwingen.
- Optimieren Sie Ihre Scans mit Filtern und Stichproben, um die Kosten zu senken.
- Automatisieren Sie Ihre Infrastruktur, indem Sie Knowledge Catalog-Ressourcen mit Terraform bereitstellen, um Ihre Datenqualitätsspezifikationen und die Metadatenanreicherung in großem Umfang zu verwalten.
- Weitere Informationen finden Sie in der Antigravity CLI-Kurzanleitung.
- Probieren Sie andere Knowledge Catalog-Anwendungsfälle aus.