Crea un flujo de trabajo de calidad de los datos basado en políticas como código

Crea un flujo de trabajo de calidad de los datos y enriquecimiento de metadatos de política como código. En este instructivo, se explica cómo ir más allá de los procesos manuales definiendo las expectativas de calidad de los datos en archivos declarativos con control de versiones.

Si estableces reglas automatizadas de generación de perfiles y calidad de los datos, enriqueces tus metadatos con indicadores de confianza y contexto empresarial.

Con un enfoque Human-in-the-Loop, en el que la IA redacta las reglas iniciales y tú las revisas, perfeccionas y validas, puedes traducir rápidamente las estadísticas de los perfiles en un marco de calidad de los datos.

Objetivos

  • Aplanar datos de BigQuery anidados 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 las 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 con intervenció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.

  1. En la consola de Google Cloud , haz clic en Activar Cloud Shell en la barra de herramientas de la parte superior derecha. El aprovisionamiento y la conexión al entorno tardan solo unos momentos.

  2. 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 ubicación, ya que los datos de muestra públicos también se encuentran en us (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.

  3. Habilita los servicios obligatorios:

    gcloud services enable dataplex.googleapis.com \
                       bigquery.googleapis.com \
                       serviceusage.googleapis.com \
                       aiplatform.googleapis.com

  4. Crea un conjunto de datos de BigQuery para almacenar los datos y resultados de muestra:

    bq --location=us mk --dataset $PROJECT_ID:$DATASET_ID

  5. Prepara los datos de muestra, que provienen de un conjunto de datos público de comercio electrónico de Google Merchandise Store.

    El siguiente comando bq crea una tabla nueva, ga4_transactions, en tu conjunto de datos kc_dq_codelab. Para garantizar que los análisis se ejecuten con rapidez, solo copia datos de un día (31 de enero de 2021).

    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`'

  6. Clona el repositorio de GitHub que contiene la estructura de carpetas y los archivos de respaldo 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-dq

    Este directorio es tu área de trabajo activa.

Datos anidados de 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 unicidad y las distribuciones de valores en tus datos para ayudarte a comprenderlos.

Para obtener estadísticas de los campos anidados, puedes compactar 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 compactas datos anidados, es importante no anular la anidación de 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.

En su lugar, lo mejor es crear varias vistas, cada una diseñada para un propósito específico. Cada vista debe mantener un nivel de detalle único y 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 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, además, instalaste la biblioteca, todo está listo para que uses la secuencia de comandos 1_run_scan.py. Este script genera perfiles de tus tres vistas materializadas creando y ejecutando un análisis para cada una. Cuando finaliza, genera un resumen estadístico enriquecido que usarás en el siguiente paso para crear 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 verificar tus análisis de perfiles

Puedes consultar los nuevos análisis de perfiles en la consola de Google Cloud .

  1. En el menú de navegación, ve a Knowledge Catalog y Calidad y creación de perfiles de datos en la sección Administrar.
  2. Encontrarás los tres análisis de perfiles que se enumeran, junto con el estado de su trabajo más reciente. 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 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 exitoso 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 la secuencia de comandos finaliza, 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. Ejecuta el siguiente comando para ver su contenido:

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 de forma manual 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 una supervisión de alto nivel y alineada con el negocio con intervención humana (HITL).

Para iniciar la CLI de Antigravity, usa el siguiente comando:

agy

Ahora tienes todo listo para generar reglas de calidad. Como la CLI puede leer archivos en tu directorio actual, puede usar los datos de análisis de tu nuevo perfil directamente.

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 enfoque 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 intervenció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 ellos. 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

Verifica el plan propuesto por el agente en función de estos criterios comerciales principales:

  • Anomalías estadísticas frente a la 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 establecer un rango numérico estricto en función de distribuciones históricas limitadas.
    • Acción: Verifica si los límites sugeridos (como rangeExpectation o nonNullExpectation) reflejan restricciones comerciales reales o simplemente artefactos del conjunto de muestras.
  • Métricas volátiles (como los recuentos de filas):
    • Por qué: Las métricas como rowCount o el crecimiento de las tablas varían a diario 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.
  • Integridad categórica (setExpectation):
    • Por qué: Los datos de 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: Compara las listas categóricas con el glosario empresarial oficial de tu empresa o con los datos de referencia, y agrega los valores válidos que se hayan omitido en la muestra (por ejemplo, agrega los códigos de región o las categorías de productos que falten).

Definir mejor el plan con comentarios de instrucciones

Proporciona comentarios al agente y dale el comando final para que genere 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 tus correcciones específicas.

Esta instrucción requiere que se cumpla con la especificación de DataQualityRule porque Knowledge Catalog requiere una estructura de 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.

El agente ahora genera un archivo YAML llamado dq_rules.yaml en tu directorio de trabajo, según tus instrucciones validadas.

Crea y ejecuta un análisis de calidad de los datos

Ahora tienes un conjunto de reglas de calidad de los datos generado por el agente y validado por un humano que puedes registrar e implementar como un análisis.

  1. Para salir de la CLI de Antigravity, ingresa /quit o presiona Ctrl+C dos veces.

  2. 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"

  3. Ejecuta el análisis:

    gcloud dataplex datascans run $DQ_SCAN --location=$LOCATION --project=$PROJECT_ID

    Este comando crea un análisis de calidad de los datos llamado dq-scan.

  4. Verifica el progreso de la exploración en la sección Knowledge Catalog de la consola de Google Cloud .

    1. En el menú de navegación, ve a Knowledge Catalog y Calidad y creación de perfiles de datos en la sección Administrar.
    2. Busca el dq-scan. Cuando se complete el análisis, haz clic en él para ver los resultados.

Realiza una limpieza

Para evitar que se generen cargos de facturación recurrentes 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

Cómo borrar 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 enriquecimiento de metadatos y calidad de los datos programático de extremo a extremo.

Cuando 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 intervención humana (HITL) y 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?