Crea la base de datos con los metadatos de Dataplex

1. Introducción

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

Sin una fundamentación explícita, un agente de IA seleccionará una tabla según 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 en la que se explora cómo compilar un agente de IA generativa que tenga en cuenta la gobernanza.

En esta primera parte, creará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 administración.

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

Requisitos previos

• Un proyecto de Google Cloud con facturación habilitada.
• Comprensión básica 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ña plantillas de metadatos estrictas (tipos de aspectos) en Dataplex para distinguir los productos de datos oficiales de las tablas sin procesar de la zona de pruebas.
• Verifica las reglas de gobierno 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)
• Gemini CLI (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 contexto empresarial (administración).
• Tipo de aspecto: Es una plantilla de metadatos estructurados. A diferencia de las etiquetas de texto libre, los aspectos aplican un tipado sólido (enums, booleanos), lo que los hace confiables para que las máquinas los evalúen.

2. Configuración y requisitos

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

Inicializa el entorno

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

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

Habilita las APIs

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

Clona 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 disco en Cloud Shell, solo descargaremos la carpeta específica que se necesita 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

Crea 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 "sandbox" 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 INSERT de BigQuery 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 completado, pero sin ningún tipo de administración. Para una IA, todas las tablas se ven exactamente iguales.

3. Aplicación de la administración

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 para un LLM. Son solo objetos con columnas.

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

Cómo generar cargas útiles de gobernanza

Las claves de Aspect 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).

Aplica aspectos a través de la CLI

Antes de ejecutar el script, veamos qué aplicaremos para desmitificar el proceso. Ejecuta el siguiente comando para ver la estructura de la carga útil de finanzas interna:

cat aspect_payloads/fin_internal.yaml

Se 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 comercial, por ejemplo, estableciendo la marca is_certified: true y asignando el nivel GOLD_CRITICAL. Proporcionar 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. Este comando itera 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 que se encuentra 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 "Aspectos y etiquetas opcionales" que se encuentra en la parte inferior.
4. Encontrarás el aspecto official-data-product-spec. Confirma que los valores coincidan con el escenario "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 lógicamente por metadatos legibles por máquina.

4. Configura y crea un prototipo del agente

Antes de compilar una aplicación web (lo que haremos en la Parte 2), verificaremos nuestra lógica de administración de forma local. Debemos instalar la extensión de Dataplex y configurar la instrucción del sistema.

Instala la extensión

En Cloud Shell, instala la extensión de Dataplex. Se te pedirá que confirmes la acción y que ingreses 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 el ID del proyecto cuando se te solicite).

Define el archivo de política

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

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

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

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 de 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 y 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, solo entonces, buscar los datos (fase 2).

Inicia el agente y prueba situaciones

Inicia la sesión de Gemini CLI, esta vez cargando tu política de gobernanza como 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.

Verifica la instalación

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

Situaciones de prueba (prototipado)

Pega las siguientes instrucciones en la sesión del agente en ejecución una por una para verificar que cumpla con tus reglas.

💡 Nota: Si se te solicita, selecciona "2. Permitir la 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?"

Esperado: La búsqueda fin_monthly_closing_internal porque coincide semánticamente con GOLD_CRITICAL (precisa) 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 la prioriza por sobre el nivel GOLD_CRITICAL de los datos financieros.

• Situación D (experimentación en 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 pruebas) en su Aspecto.

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

⚠️ Nota: Lanzamiento de la versión beta (a partir de febrero de 2026)

Actualmente, la extensión de Dataplex para Gemini CLI y su caja de herramientas de MCP subyacente se encuentran en versión beta (anterior a la versión 1.0).

Dado que se trata de un proyecto de código abierto en evolución, es posible que, en ocasiones, observes comportamientos inesperados, tiempos de espera silenciosos (como la devolución de null) o cambios que interrumpan el funcionamiento. 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 ver las actualizaciones más recientes, los problemas abiertos o dejar comentarios.

5. ¡Felicitaciones! Próximos pasos

Creaste 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 quieres convertir este prototipo local en una aplicación web segura y apta para la producción con el Protocolo de contexto del modelo (MCP) y Cloud Run, sigue estos pasos:

👉 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 de Dataplex para la Parte 2.

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

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

¡No te preocupes! En la Parte 2, te proporcionaremos una "Secuencia de comandos de aceleración" 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 con la sección Limpieza.

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

Si detienes el proceso aquí, destruye los recursos para evitar cargos.

Destruye el lago de datos (Terraform)

Si te encuentras en el entorno de Gemini CLI, presiona Ctrl+C dos veces o escribe /quit para salir de la sesión. 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

Desinstala la extensión de Gemini CLI y quita los archivos locales

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