Crea la base de datos con los metadatos de Dataplex

1. Introducción

Los modelos de IA generativa son razonadores potentes, pero carecen de contexto institucional. Si un ejecutivo le pregunta a un agente de IA: "¿Cuáles son nuestros ingresos del primer trimestre?", el agente podría encontrar docenas de tablas llamadas "ingresos" en tu data lake. Algunas son informes financieros rigurosos, otras son estimaciones de marketing en tiempo real y es probable que muchas sean zonas de pruebas obsoletas.

Sin una base explícita, un agente de IA seleccionará una tabla en función de la similitud simple del nombre, lo que generará respuestas "convincentemente incorrectas" derivadas de datos no verificados.

Este codelab es parte de una serie de dos partes que explora cómo compilar un agente de IA generativa con reconocimiento de la gobernanza.

En esta primera parte, compilarás la base de datos. Configurarás un data lake realista y "desordenado" en BigQuery, aplicarás etiquetas de metadatos rígidas (aspectos de Dataplex) para diferenciar los datos válidos del ruido y usarás la CLI de Gemini para probar de forma local si el LLM sigue estrictamente tus reglas de gobernanza.

(Puedes leer la segunda parte de esta serie, que abarca cómo implementar este prototipo local en una aplicación web segura de nivel empresarial con el Protocolo de contexto del modelo (MCP) y Cloud Run. 👉 Leer la parte 2)

Requisitos previos

• Un proyecto de Google Cloud con facturación habilitada.
• Conocimientos básicos y familiaridad con BigQuery, Dataplex Universal Catalog y Terraform.
• Acceso a Google Cloud Shell

Qué aprenderás

• Implementar un data lake realista de varios niveles con Terraform
• Diseñar plantillas de metadatos estrictas (tipos de aspectos) en Dataplex para distinguir los productos de datos oficiales de las tablas de zonas de pruebas sin procesar
• Verificar las reglas de gobernanza de forma local con la CLI de Gemini antes de escribir cualquier código de aplicación

Requisitos

• Acceso a Google Cloud Shell
• Terraform (preinstalado en Cloud Shell)
• CLI de Gemini (preinstalada en Cloud Shell)

Conceptos clave

• Dataplex Universal Catalog: Es el servicio unificado de administración de metadatos. Lo usamos para enriquecer los metadatos técnicos (esquemas) con el contexto empresarial (gobernanza).
• Tipo de aspecto: Es una plantilla de metadatos estructurada. A diferencia de las etiquetas de texto libre, los aspectos aplican un tipo fuerte (enums, booleanos), lo que los hace confiables para que las máquinas los evalúen.

2. Configuración y requisitos

Iniciar Cloud Shell

Si bien Google Cloud y Spanner se pueden operar de manera remota desde tu laptop, en este codelab usarás Google Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.

En el Google Cloud Console, haz clic en el ícono de Cloud Shell en la barra de herramientas en la parte superior derecha:

El aprovisionamiento y la conexión al entorno deberían tomar solo unos minutos. Cuando termine el proceso, debería ver algo como lo siguiente:

Esta máquina virtual está cargada con todas las herramientas de desarrollo que necesitarás. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud, lo que permite mejorar considerablemente el rendimiento de la red y la autenticación. Todo tu trabajo en este codelab se puede hacer en un navegador. No es necesario que instales nada.

Inicializar el entorno

Abre Cloud Shell y configura las variables de tu proyecto para asegurarte de que todos los comandos apunten a la infraestructura correcta.

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

Habilita las API

Habilita los servicios de Google Cloud necesarios para ejecutar la siguiente instrucción.

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 el repositorio

Obtén el código de infraestructura y las secuencias de comandos de automatización del repositorio de GitHub. Para ahorrar espacio en el disco en Cloud Shell, solo descargaremos la carpeta específica necesaria para este lab.

# 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

Compilar el data lake "desordenado"

Los entornos de datos del mundo real rara vez están limpios. Para simular la realidad, necesitamos una combinación de data marts "oficiales" y tablas de "zonas de pruebas" no confiables.

Usaremos Terraform para implementar este entorno. La configuración controla dos tareas:

• Infraestructura: Crea tipos de aspectos de Dataplex y conjuntos de datos o tablas de BigQuery.
• Carga de datos: Ejecuta trabajos de BigQuery INSERT para propagar las tablas con datos de muestra inmediatamente después de la creación.

1. Navega al directorio terraform y, luego, inicialízalo.

cd terraform
terraform init

2. Aplica la configuración. Esto puede tardar hasta un minuto.

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

Punto de control: Ahora tienes un data lake completamente propagado, pero sin gobernanza. Para una IA, todas las tablas se ven exactamente iguales.

3. Aplicar la gobernanza

Este es el paso de ingeniería fundamental. Actualmente, las tablas finance_mart.fin_monthly_closing_internal y analyst_sandbox.tmp_data_dump_v2_final_real se ven idénticas a un LLM. Son solo objetos con columnas.

Como ingeniero de gobernanza, debes adjuntar un aspecto (una etiqueta de metadatos certificada) a estas tablas para diferenciarlas. En una empresa real, automatizarías esto a través de canalizaciones de CI/CD. Simularemos esa automatización con secuencias de comandos.

Generar cargas útiles de gobernanza

Las claves de aspecto de Dataplex deben ser únicas a nivel global (con el prefijo de tu ID del proyecto). La secuencia de comandos ./generate_payloads.sh generará de forma dinámica los archivos de metadatos YAML.

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

Resultado:

Esto crea una carpeta "./aspect_payloads" que contiene 4 archivos YAML, que definen las situaciones de gobernanza (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).

Aplicar aspectos a través de la CLI

Antes de ejecutar la secuencia de comandos, veamos lo que realmente aplicamos para desmitificar el proceso. Ejecuta el siguiente comando para ver la estructura de la carga útil de finanzas internas:

cat aspect_payloads/fin_internal.yaml

Te mostrará el siguiente contenido.

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

Observa cómo este YAML define de forma explícita el contexto empresarial, como configurar la marca is_certified: true y asignar el nivel GOLD_CRITICAL. Esto le da a la IA reglas claras y estructuradas para evaluar en lugar de solo adivinar en función de los nombres de las tablas.

Ahora, ejecuta la secuencia de comandos de la aplicación. Esto itera a través de las tablas de BigQuery y ejecuta el comando gcloud dataplex entries update para adjuntar estos metadatos rígidos.

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

Verificación (opcional)

Antes de continuar, verifica que los metadatos se hayan aplicado correctamente en la consola.

1. Abre la página Dataplex Universal Catalog en Google Cloud Console. Si no ves "Dataplex Universal Catalog" en el menú de navegación de la izquierda, usa la barra de búsqueda en la parte superior de la ventana de la consola de Google Cloud, escribe Dataplex y selecciona el resultado en "Resultados principales" o "Productos y páginas".
2. Busca fin_monthly_closing_internal. Deberías ver la tabla de BigQuery en los resultados. Haz clic en el nombre de la tabla para ingresar a su página de detalles.

3. En la página de detalles de la tabla, busca la sección "Etiquetas y aspectos opcionales" ubicada en la parte inferior.
4. Encontrarás el aspecto official-data-product-spec. Confirma que los valores coincidan con la situación "Gold Internal" que aplicamos.

Ahora confirmaste que las tablas de BigQuery técnicamente idénticas (fin_monthly_closing_internal y tmp_data_dump_v2_final_real) se diferencian de forma lógica por metadatos legibles por máquina.

4. Configurar y crear un prototipo del agente

Antes de compilar una aplicación web (que haremos en la parte 2), verificaremos nuestra lógica de gobernanza de forma local. Debemos instalar la extensión de Dataplex y configurar el mensaje del sistema.

Instala la extensión

En Cloud Shell, instala la extensión de Dataplex. Te pedirá confirmación y los detalles de configuración.

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

(Escribe Y para aceptar la instalación y, luego, ingresa tu ID del proyecto cuando se te solicite).

Definir el archivo de política

El archivo GEMINI.md contiene la lógica que traduce reglas humanas abstractas (p.ej., "Necesito datos seguros") en búsquedas técnicas estrictas.

Actualmente, este archivo es genérico. El agente necesita saber exactamente qué proyecto de Google Cloud buscar para evitar que alucine tablas de Internet pública o de otros contextos.

1. Inserta tu PROJECT_ID en el archivo de política.

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

2. Inspecciona el archivo para comprender el algoritmo que le enseñamos a la IA.

cat GEMINI.md

Observa dos aspectos en este archivo:

1. Alcance del proyecto: Consulta la fase 2. Asegúrate de que projectid:${PROJECT_ID} se haya reemplazado por tu ID del proyecto real (e.g., projectid:my-lab-project). Si no se reemplaza esta variable, el agente buscará en todos los proyectos a los que tengas acceso, lo que generará respuestas incorrectas.
2. El algoritmo: Observa la lógica de la fase 1 o la fase 2. Le indicamos explícitamente al modelo que NO adivine SQL. Primero debe buscar la definición de etiqueta correcta (fase 1) y, luego, buscar datos (fase 2).

Iniciar el agente y probar situaciones

Inicia la sesión de la CLI de Gemini y, esta vez, carga tu política de gobernanza como el contexto del sistema.

gemini

Nota: Es posible que veas que se cargan varios archivos de contexto (p.ej., GEMINI.md y otros). Esto es normal. La CLI carga el archivo GEMINI.md local para las reglas específicas de este proyecto, además de las instrucciones predeterminadas para la extensión de Dataplex.

Verificar la instalación

Escribe /mcp desc para confirmar que la extensión de Dataplex esté activa. Deberías ver dataplex como un servidor MCP configurado con herramientas disponibles.

Situaciones de prueba (creación de prototipos)

Pega los siguientes mensajes en la sesión del agente en ejecución uno por uno para verificar que cumpla con tus reglas.

💡 Sugerencia: Si se te solicita, selecciona "2. Permitir herramienta para esta sesión" para habilitar pruebas sin problemas.

• Situación A (certificar los datos del 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?"

Resultado esperado: Consulta fin_monthly_closing_internal porque coincide semánticamente con GOLD_CRITICAL (preciso) y INTERNAL_ONLY (reunión de la junta) en su aspecto.

• Situación B (divulgación 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?"

Resultado esperado: El agente debe omitir la tabla interna mensual y seleccionar estrictamente fin_quarterly_public_report porque es el único activo etiquetado como EXTERNAL_READY.

• Situación C (necesidades operativas):

"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?"

Resultado esperado: El agente selecciona mkt_realtime_campaign_performance porque identifica la frecuencia de actualización REALTIME_STREAMING y le da prioridad sobre el nivel GOLD_CRITICAL de los datos financieros.

• Situación D (experimentación en la zona de pruebas):

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

Resultado esperado: El agente selecciona tmp_data_dump_v2_final_real porque coincide semánticamente con BRONZE_ADHOC (datos sin procesar) y is_certified: false (entorno de zona de pruebas) en su aspecto.

(Para salir de la sesión de Gemini, escribe /quit)

⚠️ Nota: Versión beta (a partir de febrero de 2026)

La extensión de Dataplex para la CLI de Gemini y su caja de herramientas MCP subyacente se encuentran actualmente en versión beta (anterior a la v1.0).

Como se trata de un proyecto de código abierto en evolución, es posible que, en ocasiones, encuentres comportamientos inesperados, tiempos de espera silenciosos (como mostrar null) o cambios rotundos. Google aún no garantiza su estabilidad completa para el uso en producción.

Si tienes problemas que no se abordan en este codelab, consulta el repositorio oficial de GitHub para verificar las actualizaciones más recientes, los problemas abiertos o dejar comentarios.

5. ¡Felicitaciones! Próximos pasos

Compilaste correctamente una base de datos gobernada y demostraste que una IA puede seguir estrictamente tus reglas de metadatos con un prototipo de CLI local.

Ahora llegaste a un punto de control. Elige el siguiente paso:

Opción A: Quiero continuar con la parte 2 ahora mismo

Si estás listo para convertir este prototipo local en una aplicación web segura de nivel de producción con el Protocolo de contexto del modelo (MCP) y Cloud Run:

👉 Vínculo al codelab de la parte 2

⚠️ DETENTE: No ejecutes los pasos de limpieza que se indican a continuación. Necesitas tu configuración actual de datos y Dataplex para la parte 2.

Opción B: Haré la parte 2 más tarde o solo quería completar la parte 1

Si quieres detenerte por hoy y evitar los costos de la nube, debes limpiar tus recursos.

¡No te preocupes! En la parte 2, proporcionaremos una "secuencia de comandos de acceso rápido" que volverá a compilar por completo este entorno de la parte 1 en solo 2 minutos para que puedas retomar exactamente donde lo dejaste.

👉 Continúa a la sección Limpieza.

6. Limpieza (solo para la opción B)

Si quieres detenerte aquí, destruye los recursos para evitar que se generen cargos.

Destruir el data lake (Terraform)

Si te encuentras en el entorno de la CLI de Gemini, sal de la sesión presionando Ctrl+C dos veces o escribiendo /quit. Luego, ejecuta los siguientes comandos:

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

Desinstalar la extensión de la CLI de Gemini y quitar los archivos locales

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