Criar a base de dados com metadados do Dataplex

1. Introdução

Os modelos de IA generativa são poderosos, mas não têm contexto institucional. Se um executivo perguntar a um agente de IA: "Qual é nossa receita do primeiro trimestre?", o agente poderá encontrar dezenas de tabelas chamadas "receita" no data lake. Alguns são relatórios financeiros rigorosos, outros são estimativas de marketing em tempo real, e muitos provavelmente são sandboxes descontinuados.

Sem embasamento explícito, um agente de IA seleciona uma tabela com base em uma simples semelhança de nome, o que leva a respostas "convincentemente erradas" derivadas de dados não verificados.

Este codelab faz parte de uma série de duas partes que mostra como criar um agente de IA generativa com reconhecimento de governança.

Nesta primeira parte, você vai criar a base de dados. Você vai configurar um data lake realista e "bagunçado" no BigQuery, aplicar tags de metadados rígidas (aspectos do Dataplex) para diferenciar dados válidos de ruídos e usar a CLI do Gemini para testar localmente se o LLM segue estritamente suas regras de governança.

Leia a segunda parte desta série, que aborda como implantar esse protótipo local em um aplicativo da Web seguro e de nível empresarial usando o Protocolo de Contexto de Modelo (MCP) e o Cloud Run. 👉 Leia a Parte 2)

Pré-requisitos

• Ter um projeto do Google Cloud com o faturamento ativado.
• Conhecimento básico e familiaridade com o BigQuery, o Dataplex Universal Catalog e o Terraform.
• Acesso ao Google Cloud Shell.

O que você vai aprender

• Implante um data lake realista de várias camadas usando o Terraform.
• Projete modelos de metadados estritos (tipos de aspectos) no Dataplex para distinguir produtos de dados oficiais de tabelas brutas do sandbox.
• Verifique as regras de governança localmente usando a CLI do Gemini antes de escrever qualquer código de aplicativo.

O que é necessário

• Acesso ao Google Cloud Shell
• Terraform (pré-instalado no Cloud Shell).
• CLI do Gemini (pré-instalada no Cloud Shell).

Principais conceitos

• Dataplex Universal Catalog:o serviço unificado de gerenciamento de metadados. Usamos isso para enriquecer metadados técnicos (esquemas) com contexto comercial (governança).
• Tipo de aspecto:um modelo de metadados estruturados. Ao contrário das tags de texto livre, os aspectos aplicam tipagem forte (enums, booleanos), o que os torna confiáveis para avaliação por máquinas.

2. Configuração e requisitos

Inicie o Cloud Shell

Embora o Google Cloud e o Spanner possam ser operados remotamente do seu laptop, neste codelab usaremos o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.

No Console do Google Cloud, clique no ícone do Cloud Shell na barra de ferramentas superior à direita:

O provisionamento e a conexão com o ambiente levarão apenas alguns instantes para serem concluídos: Quando o processamento for concluído, você verá algo como:

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, todo o trabalho pode ser feito com um navegador. Você não precisa instalar nada.

Inicializar o ambiente

Abra o Cloud Shell e defina as variáveis do projeto para garantir que todos os comandos sejam direcionados à infraestrutura correta.

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

Ativar APIs

Ative os serviços necessários do Google Cloud para executar a instrução a seguir.

gcloud services enable \
  artifactregistry.googleapis.com \
  bigqueryunified.googleapis.com \
  cloudaicompanion.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com \
  datacatalog.googleapis.com \
  run.googleapis.com

Clonar o repositório

Acesse o código de infraestrutura e os scripts de automação no repositório do GitHub. Para economizar espaço em disco no Cloud Shell, vamos baixar apenas a pasta específica necessária para este laboratório.

# 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/governance-context
cd data-analytics/governance-context

Criar o data lake "bagunçado"

Os ambientes de dados reais raramente são limpos. Para simular a realidade, precisamos de uma combinação de data marts "oficiais" e tabelas de "sandbox" não confiáveis.

Vamos usar o Terraform para implantar esse ambiente. A configuração processa duas tarefas:

• Infraestrutura:cria tipos de aspectos do Dataplex e conjuntos de dados/tabelas do BigQuery.
• Carregamento de dados:executa jobs INSERT do BigQuery para preencher as tabelas com dados de amostra imediatamente após a criação.

1. Navegue até o diretório terraform e inicialize-o.

cd terraform
terraform init

2. Aplique a configuração. Isso pode levar até um minuto.

terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

Checkpoint: agora você tem um data lake totalmente preenchido, mas sem governança. Para uma IA, todas as tabelas são exatamente iguais.

3. Aplicar a governança

Essa é a etapa de engenharia essencial. No momento, as tabelas finance_mart.fin_monthly_closing_internal e analyst_sandbox.tmp_data_dump_v2_final_real parecem idênticas para um LLM. São apenas objetos com colunas.

Como engenheiro de governança, você precisa anexar um aspecto (um rótulo de metadados certificado) a essas tabelas para diferenciá-las. Em uma empresa real, você automatizaria isso usando pipelines de CI/CD. Vamos simular essa automação com scripts.

Gerar payloads de governança

As chaves de aspecto do Dataplex precisam ser globalmente exclusivas (prefixadas com o ID do projeto). O script ./generate_payloads.sh vai gerar dinamicamente os arquivos de metadados YAML.

cd ..
chmod +x ./generate_payloads.sh
./generate_payloads.sh

Saída:

Isso cria uma pasta "./aspect_payloads" com quatro arquivos YAML, definindo os cenários de governança (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).

Aplicar aspectos usando a CLI

Antes de executar o script, vamos analisar o que estamos aplicando para simplificar o processo. Execute o comando a seguir para conferir a estrutura da carga útil financeira interna:

cat aspect_payloads/fin_internal.yaml

Ele vai mostrar o seguinte conteúdo.

your-project-id.us-central1.official-data-product-spec:
  data:
    product_tier: GOLD_CRITICAL
    data_domain: FINANCE
    usage_scope: INTERNAL_ONLY
    update_frequency: DAILY_BATCH
    is_certified: true

Observe como esse YAML define explicitamente o contexto comercial, como definir a flag is_certified: true e atribuir o nível GOLD_CRITICAL. Fornecer à IA regras claras e estruturadas para avaliação, em vez de simplesmente adivinhar com base nos nomes das tabelas.

Agora, execute o script do aplicativo. Isso itera pelas tabelas do BigQuery e executa o comando gcloud dataplex entries update para anexar esses metadados rígidos.

chmod +x ./apply_governance.sh
./apply_governance.sh

Verificação (opcional)

Antes de continuar, verifique se os metadados foram aplicados corretamente no console.

1. Abra a página Catálogo universal do Dataplex no console do Google Cloud. Se "Dataplex Universal Catalog" não aparecer no menu de navegação à esquerda, use a barra de pesquisa na parte de cima da janela do console do Google Cloud, digite Dataplex e selecione o resultado em "Principais resultados" ou "Produtos e páginas".
2. Pesquisar por fin_monthly_closing_internal. A tabela do BigQuery vai aparecer nos resultados. Clique no nome da tabela para acessar a página de detalhes.

3. Na página de detalhes da tabela, procure a seção Tags e aspectos opcionais na parte de baixo.
4. Você vai encontrar o aspecto official-data-product-spec. Confirme se os valores correspondem ao cenário "Gold Internal" que aplicamos.

Agora você confirmou que tabelas do BigQuery tecnicamente idênticas (fin_monthly_closing_internal e tmp_data_dump_v2_final_real) são diferenciadas logicamente por metadados legíveis por máquina.

4. Configurar e criar um protótipo do agente

Antes de criar um aplicativo da Web (o que faremos na Parte 2), vamos verificar nossa lógica de governança localmente. Precisamos instalar a Extensão do Dataplex e configurar o comando do sistema.

Instalar a extensão

No Cloud Shell, instale a extensão do Dataplex. Ele vai pedir confirmação e os detalhes da configuração.

export DATAPLEX_PROJECT="${PROJECT_ID}"

gemini extensions install https://github.com/gemini-cli-extensions/dataplex

Digite Y para aceitar a instalação e insira o ID do projeto quando solicitado.

Definir o arquivo de política

O arquivo GEMINI.md contém a lógica que traduz regras humanas abstratas (por exemplo, "Preciso de dados seguros") em pesquisas técnicas rigorosas.

No momento, este arquivo é genérico. O agente precisa saber exatamente qual projeto do Google Cloud pesquisar para evitar alucinações de tabelas da Internet pública ou de outros contextos.

1. Insira seu PROJECT_ID no arquivo de política.

envsubst < GEMINI.md > GEMINI.md.tmp && mv GEMINI.md.tmp GEMINI.md

2. Inspecione o arquivo para entender o algoritmo que estamos ensinando à IA.

cat GEMINI.md

Observe duas coisas neste arquivo:

1. Escopo do projeto:confira a Fase 2. Verifique se projectid:${PROJECT_ID} foi substituído pelo ID do projeto real (e.g., projectid:my-lab-project). Se essa variável não for substituída, o agente vai pesquisar em todos os projetos a que você tem acesso, o que vai gerar respostas incorretas.
2. O algoritmo:observe a lógica da Fase 1 / Fase 2. Instruímos explicitamente o modelo a NÃO adivinhar SQL. Primeiro, ele precisa pesquisar a definição de tag correta (fase 1) e só depois os dados (fase 2).

Iniciar o agente e testar cenários

Inicie a sessão da CLI do Gemini, desta vez carregando sua política de governança como o contexto do sistema.

gemini

Observação: talvez você veja vários arquivos de contexto sendo carregados (por exemplo, GEMINI.md e outros). Isso é normal. A CLI carrega o GEMINI.md local para as regras específicas deste projeto, além das instruções padrão da própria extensão do Dataplex.

Verificar a instalação

Digite /mcp desc para confirmar se a extensão do Dataplex está ativa. dataplex vai aparecer como um servidor MCP configurado com ferramentas disponíveis.

Cenários de teste (prototipagem)

Cole os comandos a seguir na sessão do agente em execução um por um para verificar se ele obedece às suas regras.

💡 Dica: se solicitado, selecione "2. Permitir ferramenta para esta sessão" para ativar testes sem problemas.

• Cenário A (certificar os dados do CFO):

"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"

Esperado:consultas fin_monthly_closing_internal porque corresponde semanticamente a GOLD_CRITICAL (preciso) e INTERNAL_ONLY (reunião do conselho) no aspecto.

• Cenário B (divulgação pública):

"I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?"

Esperado:o agente precisa ignorar a tabela interna mensal e selecionar fin_quarterly_public_report porque é o único recurso marcado como EXTERNAL_READY.

• Cenário C (necessidades operacionais):

"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"

Esperado:o agente seleciona mkt_realtime_campaign_performance porque identifica a frequência de atualização REALTIME_STREAMING, priorizando isso em vez do nível GOLD_CRITICAL dos dados financeiros.

• Cenário D (experiência no sandbox):

"I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment."

Esperado:o agente seleciona tmp_data_dump_v2_final_real porque ele corresponde semanticamente a BRONZE_ADHOC (dados brutos) e is_certified: false (ambiente de sandbox) no aspecto.

Para sair da sessão do Gemini, digite /quit.

⚠️ Observação: versão Beta (em fevereiro de 2026)

A extensão do Dataplex para a CLI do Gemini e a MCP Toolbox estão atualmente na versão Beta (pré-v1.0).

Como este é um projeto de código aberto em evolução, você pode encontrar comportamentos inesperados, tempos limite silenciosos (como o retorno de null) ou mudanças significativas. O Google ainda não garante a estabilidade completa para uso em produção.

Se você tiver problemas que não são abordados neste codelab, consulte o repositório oficial do GitHub para verificar as atualizações mais recentes, problemas em aberto ou deixar feedback.

5. Parabéns! A seguir

Você criou uma base de dados gerenciada e provou que uma IA pode seguir estritamente suas regras de metadados usando um protótipo de CLI local.

Agora você chegou a um ponto de verificação. Escolha a próxima etapa:

Opção A: quero continuar para a Parte 2 agora mesmo!

Se você quiser transformar esse protótipo local em um aplicativo da Web seguro e de nível de produção usando o Protocolo de Contexto de Modelo (MCP) e o Cloud Run:

👉 Link para o Codelab da Parte 2

⚠️ PARE:não execute as etapas de limpeza abaixo. Você vai precisar dos seus dados atuais e das configurações do Dataplex para a Parte 2.

Opção B: vou fazer a Parte 2 depois ou só queria concluir a Parte 1.

Se você quiser parar por hoje e evitar custos na nuvem, limpe seus recursos.

Não se preocupe! Na Parte 2, vamos fornecer um "Script de faixa rápida" que vai reconstruir completamente o ambiente da Parte 1 em apenas 2 minutos para que você possa continuar exatamente de onde parou.

👉 Vá para a seção "Limpeza".

6. Limpeza (somente para a opção B)

Se você vai parar por aqui, destrua os recursos para evitar cobranças.

Destruir o data lake (Terraform)

Se você estiver no ambiente da CLI do Gemini, saia da sessão pressionando Ctrl+C duas vezes ou digitando /quit. Em seguida, execute os comandos abaixo:

cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

Desinstalar a extensão da CLI do Gemini e remover arquivos locais

gemini extensions uninstall dataplex
cd ~
rm -rf ~/devrel-demos