Ao estabelecer regras automatizadas de criação de perfis e qualidade de dados, você enriquece seus metadados com indicadores de confiança e contexto comercial.
Usando uma abordagem Human-in-the-Loop, em que a IA cria as regras iniciais e você as revisa, refina e valida, é possível traduzir rapidamente as estatísticas de perfil em uma estrutura de qualidade de dados.
Objetivos
- Achatam dados aninhados do BigQuery com visualizações materializadas para ativar a criação de perfil do Knowledge Catalog.
- Execute verificações de perfil do Knowledge Catalog usando a biblioteca de cliente Python.
- Use a CLI do Antigravity para gerar regras de qualidade de dados com base nas estatísticas de 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.
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 levar alguns instantes.
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(multirregião) como o local, já que os dados de amostra públicos também estão localizados emus(multirregião). Para consultas do BigQuery, os dados de origem e a tabela de destino precisam estar no mesmo local.Ative os serviços necessários:
gcloud services enable dataplex.googleapis.com \ bigquery.googleapis.com \ serviceusage.googleapis.com \ aiplatform.googleapis.comCrie um conjunto de dados do BigQuery para armazenar dados de amostra e resultados:
bq --location=us mk --dataset $PROJECT_ID:$DATASET_IDPrepare os dados de amostra, que vêm de um conjunto de dados público de e-commerce da Google Merchandise Store.
O comando
bqa seguir cria uma tabela,ga4_transactions, no conjunto de dadoskc_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`'Clone o repositório do GitHub que contém a estrutura de pastas e os arquivos de suporte para este 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-dqEsse diretório é sua área de trabalho ativa.
Dados aninhados de perfil
Com a criação de perfil de dados, o Knowledge Catalog encontra estatísticas para colunas de nível superior, como porcentagens de nulos, exclusividade e distribuições de valores nos seus dados para ajudar você a entender.
Para receber estatísticas de campos aninhados, você pode achatar 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 criar um perfil.
Receber o esquema aninhado
Extraia o esquema completo da sua 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.
Simplificar dados com uma visualização materializada
Ao achatar dados aninhados, é importante não desagrupar 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 seus dados.
É melhor criar várias visualizações, cada uma criada para uma finalidade específica. Cada visualização deve manter um único nível de detalhes claro. Nesta etapa, você vai criar as seguintes visualizações materializadas:
- Visualização simples de sessão (
mv_ga4_user_session_flat.sql): uma linha por evento. - Visualização "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 do 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, está tudo pronto para usar o script 1_run_scan.py. Esse script cria um perfil das três visualizações materializadas criando e executando uma verificação para cada uma delas. Quando terminar, ele vai gerar um resumo estatístico detalhado que você vai usar 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 suas verificações de perfis
Confira as novas verificações de perfil no console Google Cloud .
- No menu de navegação, acesse Knowledge Catalog e Qualidade e criação do perfil de dados na seção Governança.
- 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 de 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, faça o download dos dados de perfil e salve-os 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. Confira o conteúdo dele executando o comando a seguir:
cat dq_profile_results.json
Gerar regras de qualidade de dados com a CLI do Antigravity
Agora é possível 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. Usar um agente de IA generativa acelera esse fluxo de trabalho ao criar um rascunho de uma configuração declarativa inicial em segundos. Isso permite que as equipes de dados mudem da criação manual de sintaxe para uma supervisão de alto nível, alinhada aos negócios e com human-in-the-loop (HITL).
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 diretamente os novos dados de verificação de perfil.
Peça ao agente para criar um plano
Primeiro, peça para o agente analisar o perfil estatístico e propor um plano de ação. Instrua-o a não gravar o arquivo YAML ainda para que ele 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
Essa é a etapa mais importante de todo o fluxo de trabalho: a revisão human-in-the-loop (HITL). O plano gerado pelo agente se baseia apenas 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. Sua função como especialista humano é validar, corrigir e aprovar esse plano antes de transformá-lo em código.
O que validar durante a revisão de HITL
Confira se o plano proposto pelo agente atende a estes critérios comerciais principais:
- Anomalias estatísticas x realidade empresarial:
- Por quê: um agente de IA pode presumir que uma coluna com 0% de valores nulos em uma amostra de um dia nunca deve conter valores nulos ou definir um intervalo numérico estrito com base em distribuições históricas limitadas.
- Ação: verifique se os limites sugeridos (como
rangeExpectationounonNullExpectation) refletem restrições comerciais verdadeiras ou apenas artefatos do conjunto de amostras.
- Métricas voláteis (como contagens de linhas):
- Por quê: métricas como
rowCountou crescimento da tabela variam diariamente em ambientes empresariais ativos. Uma regra estática vai gerar alertas de falsos positivos. - Ação: rejeite ou modifique regras que aplicam limites estáticos em tabelas dinâmicas de transações.
- Por quê: métricas como
- Integridade categórica (
setExpectation):- Por quê: os dados de perfil revelam apenas os valores presentes na janela de amostra verificada. Ela não pode prever categorias válidas que não ocorreram durante esse período.
- Ação: compare as listas categóricas com seu glossário empresarial oficial ou dados de referência, adicionando valores válidos que foram omitidos da amostra (por exemplo, adicionando códigos regionais ou categorias de produtos ausentes).
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. Na primeira linha, adicione suas correções específicas.
Essa solicitação exige 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 seu 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 geradas por um agente e validadas por humanos que pode registrar e implantar como uma verificação.
Para sair da CLI do Antigravity, digite
/quitou pressioneCtrl+Cduas vezes.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"Execute a verificação:
gcloud dataplex datascans run $DQ_SCAN --location=$LOCATION --project=$PROJECT_IDEsse comando cria uma verificação de qualidade de dados chamada
dq-scan.Verifique o progresso da verificação na seção "Knowledge Catalog" do Google Cloud console.
- No menu de navegação, acesse Knowledge Catalog e Qualidade e criação do perfil de dados na seção Governança.
- Encontre o
dq-scan. Quando a verificação for concluída, clique nela para conferir os resultados.
Limpar
Para evitar cobranças recorrentes pelos recursos criados neste tutorial, exclua-os.
Excluir as verificações do Knowledge Catalog
Exclua seu perfil e as verificações de 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 completo e programático de qualidade de dados e enriquecimento de metadados.
Ao parear 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. Assim, o catálogo de dados atua como um mecanismo de contexto confiável para o consumo de IA empresarial.
A seguir
- Leia mais sobre a filosofia por trás dessa arquitetura em Governança assistida por IA: aceleração da qualidade de dados com supervisão humana.
- Gerencie a qualidade de dados como código criando um pipeline de CI/CD.
- Use regras SQL personalizadas para aplicar uma lógica específica da empresa.
- Otimize suas verificações com filtros e amostragem para reduzir custos.
- Automatize sua infraestrutura provisionando recursos do Knowledge Catalog com o Terraform para gerenciar suas especificações de qualidade de dados e o enriquecimento de metadados em grande escala.
- Saiba mais usando o guia de início rápido da CLI do Antigravity.
- Confira outros casos de uso do Knowledge Catalog