Al establecer reglas automatizadas de perfilamiento y calidad de los datos, enriqueces tus metadatos con indicadores de confianza y contexto empresarial.
Con un enfoque de Human-in-the-Loop, en el que la IA redacta las reglas iniciales y tú las revisas, las perfeccionas y las validas, puedes traducir rápidamente las estadísticas del perfil en un marco de calidad de los datos.
Objetivos
- Aplanar los datos anidados de BigQuery con vistas materializadas para habilitar la creación de perfiles de Knowledge Catalog
- Ejecutar análisis de perfiles de Knowledge Catalog con la biblioteca cliente de Python
- Usa la CLI de Antigravity para generar reglas de calidad de los datos basadas en estadísticas de perfil.
- Valida y, luego, implementa las reglas generadas por IA como análisis de calidad de Knowledge Catalog a través de un proceso de revisión con interacción humana.
Antes de comenzar
Antes de comenzar, asegúrate de tener un proyecto de Google Cloud con la facturación habilitada.
Prepara el entorno
En los siguientes pasos, se usa Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.
En la Google Cloud consola, haz clic en Activar Cloud Shell en la barra de herramientas de la esquina superior derecha. El aprovisionamiento y la conexión al entorno demorarán unos minutos.
En Cloud Shell, configura tu ID del proyecto y las variables de entorno:
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"Usa
us(multirregión) como la ubicación, ya que los datos de muestra públicos también se encuentran enus(multirregión). En el caso de las consultas de BigQuery, los datos de origen y la tabla de destino deben estar en la misma ubicación.Habilita los servicios requeridos:
gcloud services enable dataplex.googleapis.com \ bigquery.googleapis.com \ serviceusage.googleapis.com \ aiplatform.googleapis.comCrea un conjunto de datos de BigQuery para almacenar los datos de muestra y los resultados:
bq --location=us mk --dataset $PROJECT_ID:$DATASET_IDPrepara los datos de muestra, que provienen de un conjunto de datos de comercio electrónico público de Google Merchandise Store.
El siguiente comando
bqcrea una tabla nueva,ga4_transactions, en tu conjunto de datoskc_dq_codelab. Para garantizar que los análisis se ejecuten rápidamente, solo copia los datos de un día (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 el repositorio de GitHub que contiene la estructura de carpetas y los archivos de asistencia para este instructivo:
# 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-dqEste directorio es tu área de trabajo activa.
Datos anidados del perfil
Con la creación de perfiles de datos, Knowledge Catalog encuentra estadísticas para las columnas de nivel superior, como los porcentajes de valores nulos, la singularidad y las distribuciones de valores en tus datos para ayudarte a comprenderlos.
Para obtener estadísticas de los campos anidados, puedes aplanar los datos con un conjunto de vistas materializadas. Esto convierte cada campo anidado en una columna de nivel superior que Knowledge Catalog puede perfilar.
Obtén el esquema anidado
Obtén el esquema completo de la tabla de origen, incluidas todas las estructuras anidadas, y guarda el resultado como un archivo JSON:
bq show --schema --format=json $PROJECT_ID:$DATASET_ID.$TABLE_ID > bq_schema.json
Visualiza el esquema:
jq < bq_schema.json
El archivo bq_schema.json revela estructuras complejas.
Cómo aplanar datos con una vista materializada
Cuando aplanas datos anidados, es importante no desagrupar varios arrays independientes en la misma vista. Si lo haces, se realizará una unión cruzada implícita (producto cartesiano) entre los arrays, lo que multiplicará las filas de forma incorrecta y dañará tus datos.
En su lugar, es mejor crear varias vistas, cada una diseñada para un propósito específico. Cada vista debe mantener un solo nivel de detalle claro. En este paso, crearás las siguientes vistas materializadas:
- Vista plana de la sesión (
mv_ga4_user_session_flat.sql): Una fila por evento. - Vista de transacciones (
mv_ga4_ecommerce_transactions.sql): Una fila por transacción. - Vista de elementos (
mv_ga4_ecommerce_items.sql): Una fila por elemento.
El repositorio del proyecto proporciona tres archivos SQL en el directorio devrel-demos/data-analytics/programmatic-dq que definen estas vistas.
Ejecuta estos archivos desde Cloud Shell con los siguientes comandos de 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
Ejecuta análisis de perfil con el cliente de Python
Ahora puedes crear y ejecutar análisis de perfil de datos de Knowledge Catalog para cada vista materializada. La siguiente secuencia de comandos de Python usa la biblioteca cliente de google-cloud-dataplex para automatizar este proceso.
Antes de ejecutar la secuencia de comandos, crea un entorno virtual de Python aislado en el directorio de tu proyecto.
# Create the virtual environment
python3 -m venv dq_venv
# Activate the environment
source dq_venv/bin/activate
Instala la biblioteca cliente de Knowledge Catalog dentro del entorno virtual.
# Install the Knowledge Catalog client library
pip install google-cloud-dataplex
Ahora que configuraste el entorno y la biblioteca, puedes usar la secuencia de comandos 1_run_scan.py. Este script crea perfiles de tus tres vistas materializadas creando y ejecutando un análisis para cada una. Cuando finaliza, genera un resumen estadístico detallado que usarás en el siguiente paso para generar reglas de calidad de los datos potenciadas por IA.
Ejecuta la secuencia de comandos desde la terminal de Cloud Shell.
python3 1_run_scan.py
Cómo revisar los análisis de tu perfil
Puedes consultar los nuevos análisis de perfil en la consola de Google Cloud .
- En el menú de navegación, ve a Knowledge Catalog y Calidad y creación de perfiles de datos en la sección Administrar.
- Verás los tres análisis de perfil junto con el estado de trabajo más reciente. Haz clic en un análisis para explorar sus resultados detallados.
Cómo exportar los resultados del perfil a JSON
Para que la CLI de Antigravity lea los análisis de tu perfil, debes extraer su contenido en un archivo local.
Usa la secuencia de comandos 2_dq_profile_save.py para encontrar el análisis correcto más reciente de la vista mv_ga4_user_session_flat, descargar los datos del perfil y guardarlos en un archivo llamado dq_profile_results.json.
python3 2_dq_profile_save.py
Cuando finaliza la secuencia de comandos, se crea un archivo dq_profile_results.json en el directorio. Este archivo contiene los metadatos estadísticos detallados que necesitas para generar reglas de calidad de los datos. Para ver su contenido, ejecuta el siguiente comando:
cat dq_profile_results.json
Genera reglas de calidad de los datos con la CLI de Antigravity
Ahora puedes usar la CLI de Antigravity para leer los resultados del análisis del perfil local.
Escribir manualmente especificaciones de calidad de los datos para conjuntos de datos complejos lleva mucho tiempo y es propenso a errores. Usar un agente de IA generativa acelera este flujo de trabajo, ya que redacta una configuración declarativa inicial en segundos. Esto permite que los equipos de datos pasen de la redacción manual de sintaxis a la supervisión de alto nivel con interacción humana (HITL) alineada con la empresa.
Para iniciar la CLI de Antigravity, usa el siguiente comando:
agy
Ahora puedes generar reglas de calidad. Dado que la CLI puede leer archivos en tu directorio actual, puede usar directamente los datos de análisis de tu nuevo perfil.
Dale instrucciones al agente para que cree un plan
Primero, pídele al agente que analice el perfil estadístico y proponga un plan de acción. Indícale que aún no escriba el archivo YAML para que se concentre en el análisis y la justificación.
En tu sesión interactiva de la CLI de Antigravity, ingresa la siguiente instrucción estructurada:
# 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.
El agente analizará el archivo JSON y devolverá un plan estructurado como el siguiente:
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 reglas de calidad de los datos
Este es el paso más importante de todo el flujo de trabajo: la revisión con interacción humana (HITL). El plan que generó el agente se basa únicamente en patrones estadísticos de los datos. El agente no comprende el contexto de tu empresa, los cambios futuros en los datos ni la intención específica detrás de tus datos. Tu función como experto humano es validar, corregir y aprobar este plan antes de convertirlo en código.
Qué validar durante la revisión de HITL
Compara el plan propuesto del agente con estos criterios comerciales principales:
- Anomalías estadísticas vs. realidad empresarial:
- Por qué: Un agente de IA podría suponer que una columna con un 0% de valores nulos en una muestra de un día nunca debería contener valores nulos, o bien establecer un rango numérico estricto basado en distribuciones históricas limitadas.
- Acción: Verifica si los límites sugeridos (como
rangeExpectationononNullExpectation) reflejan restricciones comerciales reales o simplemente artefactos del conjunto de muestras.
- Métricas volátiles (como los recuentos de filas):
- Motivo: Las métricas como
rowCounto el crecimiento de la tabla varían a diario en los entornos empresariales activos. Una regla estática generará alertas de falsos positivos. - Acción: Rechaza o modifica las reglas que aplican umbrales estáticos en las tablas transaccionales dinámicas.
- Motivo: Las métricas como
- Integridad de las categorías (
setExpectation):- Motivo: Los datos del perfil solo revelan los valores presentes en la ventana de muestra analizada. No puede predecir categorías válidas que no se hayan producido durante ese período.
- Acción: Comprueba las listas de categorías con tu glosario empresarial oficial o datos de referencia, y agrega los valores válidos que se omitieron en la muestra (por ejemplo, agrega los códigos de región o las categorías de productos faltantes).
Cómo definir mejor el plan con comentarios sobre las instrucciones
Proporciona comentarios al agente y dale el comando final para generar el código. Adapta la siguiente instrucción según el plan que recibiste y las correcciones que quieras hacer.
La instrucción es solo una plantilla. En la primera línea, agrega las correcciones específicas.
Esta instrucción requiere el cumplimiento de la especificación de DataQualityRule porque Knowledge Catalog requiere una estructura YAML precisa, lo que evita errores de sintaxis o versiones de esquema desactualizadas.
# 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.
Ahora, el agente genera un archivo YAML llamado dq_rules.yaml en tu directorio de trabajo, según las instrucciones validadas.
Crea y ejecuta un análisis de calidad de los datos
Ahora tienes un conjunto de reglas de calidad de los datos generadas por un agente y validadas por humanos que puedes registrar y, luego, implementar como un análisis.
Para salir de la CLI de Antigravity, ingresa
/quito presionaCtrl+Cdos veces.Luego, crea un análisis de datos en 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"Ejecuta el análisis:
gcloud dataplex datascans run $DQ_SCAN --location=$LOCATION --project=$PROJECT_IDEste comando crea un análisis de calidad de los datos llamado
dq-scan.Verifica el progreso del análisis en la sección Knowledge Catalog de la consola de Google Cloud .
- En el menú de navegación, ve a Knowledge Catalog y Calidad y creación de perfiles de datos en la sección Administrar.
- Busca el elemento
dq-scan. Cuando se complete el análisis, haz clic en él para ver los resultados.
Realiza una limpieza
Para evitar cargos recurrentes de facturación por los recursos que creaste en este instructivo, bórralos.
Borra los análisis de Knowledge Catalog
Borra tu perfil y los análisis de calidad con los nombres específicos de los análisis de este 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
Borra el conjunto de datos de muestra
Borra tu conjunto de datos temporal de BigQuery y sus tablas.
bq rm -r -f --dataset $PROJECT_ID:kc_dq_codelab
Borra archivos locales
Desactiva el entorno virtual de Python y quita el repositorio clonado y su contenido:
deactivate
cd ../../..
rm -rf devrel-demos
Conclusión
Felicitaciones. Creaste un flujo de trabajo programático de extremo a extremo para la calidad de los datos y el enriquecimiento de metadatos.
Si vinculas un agente de la CLI de Antigravity con Knowledge Catalog, estableces una base verificable para el enriquecimiento de metadatos asistido por IA. Este enfoque acelera la creación de reglas declarativas para que los administradores de datos puedan enfocarse en la validación con interacción humana (HITL) y en el perfeccionamiento de las reglas en función de la lógica empresarial, lo que garantiza que tu catálogo de datos actúe como un motor de contexto confiable para el consumo de IA empresarial.
¿Qué sigue?
- Obtén más información sobre la filosofía detrás de esta arquitectura en Gobernanza asistida por IA: Aceleración de la calidad de los datos con supervisión humana.
- Administra la calidad de los datos como código creando una canalización de CI/CD.
- Explora el uso de reglas de SQL personalizadas para aplicar la lógica específica de la empresa.
- Optimiza tus análisis con filtros y muestreos para reducir los costos.
- Automatiza tu infraestructura aprovisionando recursos de Knowledge Catalog con Terraform para administrar tus especificaciones de calidad de los datos y el enriquecimiento de metadatos a gran escala.
- Obtén más información con la guía de inicio rápido de la CLI de Antigravity.
- Prueba otros casos de uso de Knowledge Catalog