Criar um fluxo de trabalho de qualidade de dados de política como código

Crie um fluxo de trabalho de qualidade de dados e enriquecimento de metadados de política como código. Neste tutorial, mostramos como ir além dos processos manuais definindo expectativas de qualidade de dados em arquivos declarativos e controlados por versão.

Ao estabelecer regras automatizadas de criação de perfis e qualidade de dados, você enriquece seus metadados com indicadores de confiança e contexto de negócios.

Com uma abordagem Human-in-the-Loop, em que a IA elabora as regras iniciais e você as revisa, refina e valida, é possível traduzir rapidamente as estatísticas de perfil em um framework de qualidade de dados.

Objetivos

  • Mescle dados aninhados do BigQuery com visualizações materializadas para permitir a criação de perfis do Knowledge Catalog.
  • Executar verificações de perfil do Knowledge Catalog usando a biblioteca de cliente do Python.
  • Use a CLI do Antigravity para gerar regras de qualidade de dados com base nas estatísticas do perfil.
  • Valide e implante regras geradas com IA como verificações de qualidade do Knowledge Catalog usando um processo de revisão human-in-the-loop.

Antes de começar

Antes de começar, verifique se você tem um projeto do Google Cloud com o faturamento ativado.

Preparar o ambiente

As etapas a seguir usam o Cloud Shell, um ambiente de linha de comando executado na nuvem.

  1. No console do Google Cloud , clique em Ativar o Cloud Shell na barra de ferramentas no canto superior direito. O provisionamento e a conexão do ambiente podem demorar um pouco.

  2. No Cloud Shell, configure o ID do projeto e as variáveis de ambiente:

    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"

    Use us (multirregional) como o local, já que os dados de amostra públicos também estão localizados em us (multirregional). Para consultas do BigQuery, os dados de origem e a tabela de destino precisam estar no mesmo local.

  3. Ative os serviços necessários:

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

  4. Crie um conjunto de dados do BigQuery para armazenar dados de amostra e resultados:

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

  5. Prepare os dados de amostra, que vêm de um conjunto de dados público de e-commerce da Google Merchandise Store.

    O comando bq a seguir cria uma nova tabela, ga4_transactions, no conjunto de dados kc_dq_codelab. Para garantir que as verificações sejam executadas rapidamente, ele copia apenas os dados de um dia (31/01/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. Clone o repositório do GitHub que contém a estrutura de pastas e os arquivos de suporte deste tutorial:

    # 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

    Esse diretório é sua área de trabalho ativa.

Criar perfil de dados aninhados

Com a criação de perfil de dados, o Knowledge Catalog encontra estatísticas para colunas de nível superior, como porcentagens nulas, exclusividade e distribuições de valores nos dados para ajudar você a entendê-los.

Para receber estatísticas de campos aninhados, é possível nivelar os dados usando um conjunto de visualizações materializadas. Isso transforma cada campo aninhado em uma coluna de nível superior que o Knowledge Catalog pode analisar.

Acessar o esquema aninhado

Consiga o esquema completo da tabela de origem, incluindo todas as estruturas aninhadas, e salve a saída como um arquivo JSON:

bq show --schema --format=json $PROJECT_ID:$DATASET_ID.$TABLE_ID > bq_schema.json

Confira o esquema:

jq < bq_schema.json

O arquivo bq_schema.json revela estruturas complexas.

Mesclar dados com uma visualização materializada

Ao nivelar dados aninhados, é importante não desaninhar várias matrizes independentes na mesma visualização. Isso realiza uma correlação implícita (produto cartesiano) entre as matrizes, o que multiplica as linhas incorretamente e corrompe os dados.

É melhor criar várias visualizações, cada uma com uma finalidade específica. Cada visualização precisa manter um nível de detalhe único e claro. Nesta etapa, você vai criar as seguintes visualizações materializadas:

  • Visualização simples da sessão (mv_ga4_user_session_flat.sql): uma linha por evento.
  • Visualização de transações (mv_ga4_ecommerce_transactions.sql): uma linha por transação.
  • Visualização de itens (mv_ga4_ecommerce_items.sql): uma linha por item.

O repositório do projeto fornece três arquivos SQL no diretório devrel-demos/data-analytics/programmatic-dq que definem essas visualizações.

Execute esses arquivos no Cloud Shell usando os seguintes comandos do 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

Executar verificações de perfil com o cliente Python

Agora é possível criar e executar verificações de perfil de dados do Knowledge Catalog para cada visualização materializada. O script Python a seguir usa a biblioteca de cliente google-cloud-dataplex para automatizar esse processo.

Antes de executar o script, crie um ambiente virtual Python isolado no diretório do projeto.

# Create the virtual environment
python3 -m venv dq_venv

# Activate the environment
source dq_venv/bin/activate

Instale a biblioteca de cliente do Knowledge Catalog no ambiente virtual.

# Install the Knowledge Catalog client library
pip install google-cloud-dataplex

Agora que você configurou o ambiente e instalou a biblioteca, já pode usar o script 1_run_scan.py. Esse script cria perfis das três visualizações materializadas criando e executando uma verificação para cada uma delas. Quando ela termina, gera um resumo estatístico detalhado que você usa na próxima etapa para gerar regras de qualidade de dados com tecnologia de IA.

Execute o script no terminal do Cloud Shell.

python3 1_run_scan.py

Verificar as verificações de perfil

Confira as novas verificações de perfil no console do Google Cloud .

  1. No menu de navegação, acesse Knowledge Catalog e Criação de perfil e qualidade de dados na seção Governar.
  2. Encontre as três verificações de perfil listadas, junto com o status do job mais recente. Clique em uma verificação para conferir os resultados detalhados.

Exportar resultados do perfil para JSON

Para que a CLI do Antigravity leia as verificações de perfil, é necessário extrair o conteúdo delas para um arquivo local.

Use o script 2_dq_profile_save.py para encontrar a verificação mais recente da visualização mv_ga4_user_session_flat, baixar os dados do perfil e salvá-los em um arquivo chamado dq_profile_results.json.

python3 2_dq_profile_save.py

Quando o script terminar, ele vai criar um arquivo dq_profile_results.json no diretório. Esse arquivo contém os metadados estatísticos detalhados necessários para gerar regras de qualidade de dados. Para conferir o conteúdo, execute o seguinte comando:

cat dq_profile_results.json

Gerar regras de qualidade de dados com a CLI do Antigravity

Agora você pode usar a CLI do Antigravity para ler os resultados da verificação do perfil local.

Escrever manualmente especificações de qualidade de dados para conjuntos de dados complexos é demorado e propenso a erros. O uso de um agente de IA generativa acelera esse fluxo de trabalho, elaborando uma configuração declarativa inicial em segundos. Isso permite que as equipes de dados deixem de elaborar sintaxes manualmente e passem a fazer uma supervisão human-in-the-loop (HITL) de alto nível e alinhada aos negócios.

Para iniciar a CLI do Antigravity, use o seguinte comando:

agy

Agora você já pode gerar regras de qualidade. Como a CLI pode ler arquivos no diretório atual, ela pode usar os novos dados de verificação de perfil diretamente.

Peça ao agente para criar um plano

Primeiro, peça ao agente para analisar o perfil estatístico e propor um plano de ação. Peça para ele não escrever o arquivo YAML ainda, para que se concentre na análise e na justificativa.

Na sessão interativa da CLI do Antigravity, insira o seguinte comando estruturado:

# 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.

O agente vai analisar o arquivo JSON e retornar um plano estruturado como este:

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']
   ...             │ ...                │ ...                        │ ...

Gerar regras de qualidade de dados

Esta é a etapa mais crítica de todo o fluxo de trabalho: a revisão human-in-the-loop (HITL). O plano gerado pelo agente é baseado puramente em padrões estatísticos nos dados. O agente não entende o contexto da sua empresa, as mudanças futuras nos dados ou a intenção específica por trás deles. Seu papel como especialista humano é validar, corrigir e aprovar esse plano antes de transformá-lo em código.

O que validar durante a revisão do HITL

Verifique se o plano proposto pelo agente atende a estes critérios de negócios:

  • Anomalias estatísticas x realidade empresarial:
    • Motivo: um agente de IA pode presumir que uma coluna com 0% de nulos em uma amostra de um dia nunca deve conter nulos ou definir um intervalo numérico estrito com base em distribuições históricas limitadas.
    • Ação: verifique se os limites sugeridos (como rangeExpectation ou nonNullExpectation) refletem restrições comerciais reais ou apenas artefatos do conjunto de amostras.
  • Métricas voláteis (como contagens de linhas):
    • Motivo: métricas como rowCount ou crescimento de tabelas variam diariamente em ambientes corporativos ativos. Uma regra estática vai causar alertas de falsos positivos.
    • Ação: rejeite ou modifique regras que aplicam limites estáticos em tabelas transacionais dinâmicas.
  • Integridade categórica (setExpectation):
    • Motivo: os dados do perfil revelam apenas os valores presentes na janela de amostra verificada. Ele não pode prever categorias válidas que não ocorreram durante esse período.
    • Ação: compare as listas categóricas com o glossário empresarial oficial ou os dados de referência, adicionando os valores válidos que foram omitidos da amostra (por exemplo, adicionando códigos de região ausentes ou categorias dos produtos).

Refinar o plano com feedback de comandos

Envie feedback ao agente e dê o comando final para gerar o código. Adapte o comando a seguir com base no plano que você recebeu e nas correções que quer fazer.

O comando é apenas um modelo. A primeira linha é onde você adiciona suas correções específicas.

Esse comando precisa estar em conformidade com a especificação DataQualityRule porque o Knowledge Catalog exige uma estrutura YAML precisa, evitando erros de sintaxe ou versões de esquema desatualizadas.

# 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.

O agente agora gera um arquivo YAML chamado dq_rules.yaml no diretório de trabalho, com base nas instruções validadas.

Criar e executar uma verificação de qualidade de dados

Agora você tem um conjunto de regras de qualidade de dados gerado por um agente e validado por humanos que pode ser registrado e implantado como uma verificação.

  1. Para sair da CLI do Antigravity, digite /quit ou pressione Ctrl+C duas vezes.

  2. Em seguida, crie uma verificação de dados no 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. Execute a verificação:

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

    Esse comando cria uma verificação de qualidade de dados chamada dq-scan.

  4. Verifique o progresso da verificação na seção Knowledge Catalog do console do Google Cloud .

    1. No menu de navegação, acesse Knowledge Catalog e Criação de perfil e qualidade de dados na seção Governar.
    2. Encontre o dq-scan. Quando a verificação for concluída, clique nela para ver os resultados.

Limpar

Para evitar cobranças recorrentes pelos recursos criados neste tutorial, exclua-os.

Excluir as verificações do Knowledge Catalog

Exclua as verificações de perfil e qualidade usando os nomes específicos deste 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

Excluir o conjunto de dados de amostra

Exclua o conjunto de dados temporário do BigQuery e as tabelas dele.

bq rm -r -f --dataset $PROJECT_ID:kc_dq_codelab

Excluir arquivos locais

Desative o ambiente virtual do Python e remova o repositório clonado e o conteúdo dele:

deactivate
cd ../../..
rm -rf devrel-demos

Conclusão

Parabéns, você criou um fluxo de trabalho programático de qualidade de dados e enriquecimento de metadados de ponta a ponta.

Ao combinar um agente da CLI do Antigravity com o Knowledge Catalog, você estabelece uma base verificável para o enriquecimento de metadados assistido por IA. Essa abordagem acelera a criação de regras declarativas para que os administradores de dados possam se concentrar na validação human-in-the-loop (HITL) e no refinamento de regras em relação à lógica de negócios, garantindo que o catálogo de dados atue como um mecanismo de contexto confiável para o consumo de IA empresarial.

A seguir