Si estableces reglas de calidad de los datos y generación de perfiles automatizadas, 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 defines mejor y las validas, puedes traducir rápidamente las estadísticas de los perfiles en un framework de calidad de los datos.
Objetivos
- Aplanar los datos anidados de BigQuery con vistas materializadas para habilitar la generación de perfiles de Knowledge Catalog
- Ejecutar análisis de perfiles de Knowledge Catalog con la biblioteca cliente de Python
- Usar la CLI de Antigravity para generar reglas de calidad de los datos basadas en estadísticas de perfiles
- Validar e implementar reglas generadas por IA como análisis de calidad de Knowledge Catalog con un proceso de revisión de interacción humana
Antes de comenzar
Antes de comenzar, asegúrate de tener un Google Cloud proyecto 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 derecha. El aprovisionamiento y la conexión al entorno demorarán unos minutos.
En Cloud Shell, configura el 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). Para las consultas de BigQuery, los datos de origen y la tabla de destino deben estar en la misma ubicación.Habilita los servicios obligatorios:
gcloud services enable dataplex.googleapis.com \ bigquery.googleapis.com \ serviceusage.googleapis.com \ aiplatform.googleapis.comCrea un conjunto de datos de BigQuery para almacenar datos de muestra y 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 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.
Genera perfiles de datos anidados
Con la generación de perfiles de datos, Knowledge Catalog encuentra estadísticas para las columnas de nivel superior, como porcentajes de valores nulos, singularidad y 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 tu 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.
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 realiza una unión cruzada implícita (producto cartesiano) entre los arrays, lo que multiplica las filas de forma incorrecta y daña tus datos.
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 perfiles con el cliente de Python
Ahora puedes crear y ejecutar análisis de perfiles de datos de Knowledge Catalog para cada vista materializada. La siguiente secuencia de comandos de Python usa la biblioteca cliente 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 instalada, puedes usar la secuencia de comandos 1_run_scan.py. Esta secuencia de comandos genera perfiles de tus tres vistas materializadas mediante la creación y la ejecución de un análisis para cada una. Cuando finaliza, genera un resumen estadístico enriquecido que usas 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
Verifica tus análisis de perfiles
Puedes consultar los nuevos análisis de perfiles en la Google Cloud consola de.
- 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 los tres análisis de perfiles que aparecen en la lista, junto con el estado más reciente del trabajo. Haz clic en un análisis para explorar sus resultados detallados.
Exporta los resultados del perfil a JSON
Para que la CLI de Antigravity lea tus análisis de perfiles, debes extraer su contenido en un archivo local.
Usa la secuencia de comandos 2_dq_profile_save.py para encontrar el último análisis exitoso 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 de perfiles local.
Escribir manualmente especificaciones de calidad de los datos para conjuntos de datos complejos lleva mucho tiempo y es propenso a errores. El uso de 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 interacción humana (HITL) de alto nivel y alineada con la empresa.
Para iniciar la CLI de Antigravity, usa el siguiente comando:
agy
Ya puedes generar reglas de calidad. Como la CLI puede leer archivos en tu directorio actual, puede usar directamente los datos nuevos del análisis de perfiles.
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 centre 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 mostrará 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 de interacción humana (HITL). El plan que generó el agente se basa únicamente en patrones estadísticos en 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
Comprueba el plan propuesto por el agente con estos criterios empresariales principales:
- Anomalías estadísticas vs. realidad empresarial:
- Por qué: Un agente de IA podría suponer que una columna con 0% de valores nulos en una muestra de un día nunca debería contener valores nulos o establecer un rango numérico estricto basado en distribuciones históricas limitadas.
- Acción: Verifica si los límites sugeridos (como
rangeExpectationononNullExpectation) reflejan restricciones empresariales verdaderas o simplemente artefactos de conjuntos de muestra.
- Métricas volátiles (como recuentos de filas):
- Por qué: Las métricas como
rowCounto el crecimiento de la tabla varían diariamente en los entornos empresariales activos. Una regla estática causará alertas de falsos positivos. - Acción: Rechaza o modifica las reglas que aplican umbrales estáticos en tablas transaccionales dinámicas.
- Por qué: Las métricas como
- Integridad categórica (
setExpectation):- Por qué: Los datos del perfil solo revelan los valores presentes en la ventana de muestra analizada. No puede predecir categorías válidas que no ocurrieron durante ese período.
- Acción: Comprueba las listas categóricas con tu glosario empresarial oficial o datos de referencia, y agrega los valores válidos que se omitieron de la muestra (por ejemplo, agrega códigos de región o categorías de productos faltantes).
Define mejor el plan con comentarios de 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 deseas realizar.
La instrucción es solo una plantilla. En la primera línea, agregas tus correcciones específicas.
Esta instrucción requiere el cumplimiento de la especificación DataQualityRule, ya que Knowledge Catalog requiere una estructura YAML precisa, lo que evita errores de sintaxis o versiones de esquema obsoletas.
# 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 el agente y validadas por humanos que puedes registrar e 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.Consulta el progreso del análisis en la sección Knowledge Catalog de la Google Cloud consola de.
- 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
dq-scan. Cuando se complete el análisis, haz clic en él para ver los resultados.
Limpia
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 tus análisis de perfiles y calidad con los nombres de análisis específicos 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 los 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 de calidad de los datos y enriquecimiento de metadatos programático de extremo a extremo.
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 centrarse en la validación de interacción humana (HITL) y en la definición de reglas con 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 Administración asistida por IA: Acelera la calidad de los datos con supervisión humana.
- Administra la calidad de los datos como código mediante la creación de 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 muestreo 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 .