Criar a base de dados com metadados do Dataplex

1. Introdução

Os modelos de IA generativa são raciocinadores 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 seu data lake. Alguns são relatórios financeiros rigorosos, outros são estimativas de marketing em tempo real e muitos são provavelmente sandboxes descontinuados.

Sem um embasamento explícito, um agente de IA selecionará uma tabela com base na similaridade simples do nome, levando a respostas "convencionalmente erradas" derivadas de dados não verificados.

Este codelab faz parte de uma série de duas partes que explora 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 rigorosamente suas regras de governança.

Você pode ler a segunda parte desta série, que explica como implantar esse protótipo local em um aplicativo da Web seguro e corporativo 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.
• Entendimento básico e familiaridade com o BigQuery, o Dataplex Universal Catalog e o Terraform.
• Acesso ao Google Cloud Shell.

O que você vai aprender

• Implantar um data lake realista de várias camadas usando o Terraform.
• Criar modelos de metadados rigorosos (tipos de aspectos) no Dataplex para distinguir produtos de dados oficiais de tabelas de sandbox brutas.
• Verificar 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).

Conceitos-chave

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

2. Configuração e requisitos

Iniciar 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 fazer o download apenas da 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 do mundo real 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

Ponto de verificação: agora você tem um data lake totalmente preenchido, mas completamente não governado. Para uma IA, todas as tabelas são exatamente iguais.

3. Aplicar a governança

Essa é a etapa de engenharia crítica. Atualmente, a tabela finance_mart.fin_monthly_closing_internal e analyst_sandbox.tmp_data_dump_v2_final_real parecem idênticas a um LLM. Elas 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" que contém quatro arquivos YAML, definindo os cenários de governança (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).

Aplicar aspectos pela CLI

Antes de executar o script, vamos analisar o que estamos aplicando para desmistificar o processo. Execute o comando a seguir para conferir a estrutura do payload financeiro interno:

cat aspect_payloads/fin_internal.yaml

Ele vai mostrar o conteúdo a seguir.

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 a camada GOLD_CRITICAL. Isso oferece à IA regras claras e estruturadas para avaliar em vez de apenas adivinhar com base nos nomes das tabelas.

Agora, execute o script do aplicativo. Ele 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 do Google Cloud.

1. Abra a página Dataplex Universal Catalog no console do Google Cloud. Se você não encontrar "Dataplex Universal Catalog" 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. Pesquise 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" localizada 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 as 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 (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. Ela vai pedir confirmação e 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.

Esse arquivo é genérico. O agente precisa saber exatamente qual projeto na nuvem do Google Cloud pesquisar para evitar que ele alucine tabelas da Internet pública ou de outros contextos.

1. Injete 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, levando a respostas incorretas.
2. O algoritmo:observe a lógica da Fase 1 / Fase 2. Instruímos explicitamente o modelo a NÃO adivinhar o SQL. Ele precisa primeiro pesquisar a definição de tag correta (Fase 1) e só então pesquisar 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: você pode encontrar 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 desse projeto, além das instruções padrão para a extensão do Dataplex.

Verificar a instalação

Digite /mcp desc para confirmar que 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 segue 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 ela corresponde semanticamente a GOLD_CRITICAL (precisa) 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 estritamente 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-a em relação à camada GOLD_CRITICAL dos dados financeiros.

• Cenário D (experiência de 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 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 (a partir de fevereiro de 2026)

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

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

Se você tiver problemas que não estão cobertos neste codelab, consulte o repositório oficial do GitHub para conferir as atualizações mais recentes, problemas abertos ou deixar feedback.

5. Parabéns! A seguir

Você criou uma base de dados governada e comprovou que uma IA pode seguir rigorosamente 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ê estiver pronto para transformar esse protótipo local em um aplicativo da Web seguro e 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ê precisa dos dados atuais e das configurações do Dataplex para a Parte 2.

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

Se você quiser parar por hoje e evitar custos de nuvem, libere seus recursos.

Não se preocupe! Na Parte 2, vamos fornecer um "script de acesso rápido" que vai recriar completamente esse ambiente da Parte 1 em apenas dois minutos para que você possa continuar exatamente de onde parou.

👉 Acesse a seção Limpeza.

6. Liberar memória (somente para a opção B)

Se você estiver parando 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 seguintes comandos:

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