Gobernanza fundamental con Knowledge Catalog Universal Catalog: primeros pasos

1. Introducción

Como desarrolladores y ingenieros de datos, a menudo heredamos grandes colecciones de datos que se parecen más a pantanos de datos. Nos enfrentamos a los mismos puntos de fricción una y otra vez: "¿Cuál es la definición real de esta columna ‘amt’?", "¿Quién es responsable si este conjunto de datos se rompe?" o "¿Podemos usar esta tabla en el motor de recomendaciones personalizadas?".

Tradicionalmente, los catálogos de datos han sido inventarios pasivos llenos de etiquetas de texto libre que rápidamente se vuelven incoherentes y obsoletas. No aplican la estructura, lo que hace que la administración programática sea casi imposible.

Para que esto sea práctico, trabajaremos en un caso en este lab: establecer una administración sólida sobre los datos de ventas minoristas sin procesar para que un departamento de finanzas pueda confiar en ellos para la generación de informes oficiales. Moverás estos datos de un estado ambiguo de "pantano" a un producto administrado.

Knowledge Catalog Universal Catalog cambia esto proporcionando un framework de administración de metadatos activo y estructurado. Te permite adjuntar metadatos estructurados basados en esquemas (Aspectos) y definiciones empresariales aceptadas (Glosarios) directamente a tus recursos de datos (Entradas).

Antes de que puedas escribir secuencias de comandos de Python o módulos de Terraform para automatizar esto a gran escala, debes comprender el modelo de objetos subyacente.

En este codelab, realizaremos los pasos de administración de forma manual en la consola de Google Cloud. Conectaremos explícitamente los puntos entre las entradas, los tipos de aspecto, los aspectos y los glosarios para brindarte un modelo mental sólido sobre cómo hacer que tus datos sean detectables, comprensibles y confiables.

Requisitos previos

• Un proyecto de Google Cloud con acceso de propietario o editor
• Conocimientos sobre la consola de Google Cloud
• Habilidades básicas de gcloud y bq CLI en Cloud Shell

Qué aprenderás

• La distinción crucial entre una entrada, un tipo de aspecto y un aspecto de Knowledge Catalog
• Cómo crear un glosario empresarial para resolver la ambigüedad en la terminología
• Cómo diseñar un tipo de aspecto para aplicar un esquema estricto para los metadatos técnicos (más allá de las "etiquetas")
• Cómo vincular un término del glosario empresarial a una columna específica de BigQuery
• Cómo adjuntar un aspecto estructurado a un recurso de datos y validar las entradas
• Cómo ejecutar consultas de búsqueda precisas en estos nuevos metadatos estructurados

Requisitos

• Una cuenta de Google Cloud y un proyecto de Google Cloud
• Un navegador web, como Chrome

Conceptos clave

• Entrada: Es la representación canónica y abstracta de un recurso de datos en el catálogo. Piensa en esto como el "puntero" o el "sustantivo". Cuando creas una tabla de BigQuery, Knowledge Catalog crea automáticamente una entrada para ella. No administramos la tabla directamente, sino su entrada.
• Glosario empresarial: Es un diccionario centralizado y versionado de los términos empresariales de tu organización. Es la única fuente de información. Evita el problema de que "Ventas define el GMV de manera diferente a Finanzas".
• Tipo de aspecto: Es el esquema o la plantilla para una categoría específica de metadatos. Un tipo de aspecto define campos, tipos de datos (cadena, enum, fecha y hora, etcétera) y restricciones (obligatorio/opcional). Es el contrato que garantiza la coherencia de los metadatos.
• Aspecto: Es una pieza específica de metadatos adjunta a una entrada que sigue la estructura definida por el tipo de aspecto. Contiene los datos reales que cumplen con el esquema del tipo de aspecto.

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 la consola de Google Cloud, 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.

Habilita las APIs necesarias y configura el entorno

Ejecuta los siguientes comandos para configurar tu ID del proyecto, definir la región y habilitar las APIs de servicios necesarias.

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

gcloud services enable dataplex.googleapis.com \
                       bigquery.googleapis.com \
                       datacatalog.googleapis.com

Crea un conjunto de datos de BigQuery y prepara datos de muestra

Necesitamos un recurso de datos concreto para administrar. Crearemos un conjunto de datos de BigQuery y cargaremos un pequeño CSV de muestra que represente las transacciones. Knowledge Catalog detectará automáticamente esta tabla y creará una entrada para ella.

# Create the BigQuery Dataset in the us-central1 region
bq --location=$LOCATION mk --dataset \
    --description "Retail data for governance codelab" \
    $PROJECT_ID:retail_data

# Create a temporary CSV file with the sample data
echo "transaction_id,user_email,gmv,transaction_date
1001,[e-mail],150.50,2025-08-28
1002,[e-mail],75.00,2025-08-28" > /tmp/transactions.csv

# Load the data from the temporary CSV file into BigQuery
bq load \
    --source_format=CSV \
    --autodetect \
    retail_data.transactions \
    /tmp/transactions.csv

# (Optional) Clean up the temporary file
rm /tmp/transactions.csv

Para verificar la configuración, ejecuta una consulta rápida:

bq query --nouse_legacy_sql "SELECT * FROM retail_data.transactions"

3. Establece un lenguaje común con un glosario empresarial

La administración eficaz comienza con definiciones inequívocas. Si un desarrollador ve una columna llamada gmv, no debería tener que adivinar si incluye impuestos o devoluciones. Un glosario empresarial resuelve este problema desacoplando la definición empresarial de la implementación técnica.

1. En la consola de Google Cloud, navega a Knowledge Catalog Universal Catalog.
2. En el menú de navegación de la izquierda, selecciona Glosarios (en Administrar metadatos).

3. Haz clic en Crear glosario empresarial.
4. Ingresa los siguientes detalles:
   • Nombre: Retail Business Glossary
   • Ubicación: us-central1 (o la ubicación que definiste en la configuración).
5. Haz clic en Crear.

6. Haz clic en el glosario empresarial de venta minorista recién creado para ingresar en él.

7. Haz clic en Crear categoría , asígnale el nombre Sales Metrics y, luego, haz clic en Crear. Las categorías ayudan a agrupar términos relacionados.
8. Selecciona la categoría Sales Metrics, haz clic en Agregar término, asígnale el nombre Gross Merchandise Value y, luego, haz clic en Crear.
9. Haz clic en el botón + Agregar en Descripción general y, luego, completa los siguientes detalles:
   • Descripción general: The total value of merchandise sold over a given period of time before the deduction of any fees or expenses. This is a key indicator of e-commerce business growth.
10. Haz clic en Guardar.

Ahora estableciste una definición clara que se puede vincular a los recursos técnicos de tu organización.

4. Define metadatos técnicos estructurados con un tipo de aspecto

Las etiquetas simples "clave:valor" no son suficientes para la rigurosidad de la ingeniería. Si necesitas hacer un seguimiento de los "propietarios de datos", no querrás que una tabla tenga la etiqueta owner:bob y otra contact:[e-mail]. Necesitas un esquema para aplicar que se requiera un propietario y que deba tener un formato de correo electrónico válido.

Usaremos un tipo de aspecto para definir este contrato.

1. En la navegación izquierda de Knowledge Catalog, en Catálogo, selecciona Tipos de aspecto y plantillas de etiquetas.

⚠️ Advertencia: Aviso de baja

Notarás que la IU actualmente hace referencia a "Plantillas de etiquetas" junto con los tipos de aspecto. Las plantillas de etiquetas forman parte del servicio heredado de Data Catalog, que dejó de estar disponible y se descontinuará en febrero de 2026.

2. Selecciona la pestaña Personalizado y haz clic en Crear tipo de aspecto.

3. Ingresa los siguientes detalles:
   • Nombre visible: Data Asset Governance
   • Ubicación: us-central1
4. En la sección Plantilla, definiremos el esquema de nuestro Aspect. Haz clic en Agregar un campo para crear los siguientes tres campos:
   • Campo 1:
     • Nombre visible: Data Steward
     • Tipo: Text
     • Tipo de texto: Plain text
     • Cardinalidad: Es obligatorio (marca la casilla)
   • Campo 2 (vuelve a hacer clic en Agregar un campo):
     • Nombre visible: Data Sensitivity
     • Tipo: Enum
     • Valores: Agrega Public, Internal y Confidential.
     • Cardinalidad: Opcional
   • Campo 3 (vuelve a hacer clic en Agregar un campo):
     • Nombre visible: Last Review Date
     • Tipo: Date and time
     • Cardinalidad: Opcional
5. Haz clic en Guardar.

Acabas de crear un contrato de metadatos reutilizable. Aún no se usa nada, pero la estructura existe.

5. Conecta la administración al recurso

Ahora, uniremos todo. Tenemos una tabla de BigQuery (retail_data.transactions), una definición empresarial (Gross Merchandise Value) y un esquema de administración (Data Asset Governance).

Enriqueceremos la entrada de Knowledge Catalog para la tabla de BigQuery.

Enriquece el esquema con contexto empresarial (nivel de columna)

Expliquemos a los usuarios lo que realmente significa la columna gmv vinculándola al glosario.

1. En la navegación izquierda de Knowledge Catalog, haz clic en Buscar.
2. En la parte superior derecha, haz clic en la pestaña Knowledge Catalog Universal Catalog si no está activada.

3. Busca retail_data.transactions. Haz clic en el resultado de la tabla de BigQuery.

4. Haz clic en la pestaña Esquema en los detalles de la entrada.
5. Marca la casilla de verificación de la fila de la columna gmv y haz clic en Agregar término empresarial.
6. Selecciona el término Gross Merchandise Value.

La columna gmv ya no es solo un "FLOAT", sino que ahora está vinculada a la definición corporativa de Gross Merchandise Value.

Enriquece la entrada con metadatos técnicos estructurados (nivel de tabla)

A continuación, adjuntaremos el aspecto Data Asset Governance a la tabla para definir la propiedad y la sensibilidad.

1. Permanece en la página de entrada retail_data.transactions.
2. Haz clic en la pestaña Agregar etiqueta o aspecto y, luego, selecciona el tipo Data Asset Governance en el menú desplegable.

3. El formulario ahora mostrará los campos definidos en el esquema de tu tipo de aspecto. Completa los campos de la siguiente manera:
   • Administrador de datos: [e-mail]
   • Sensibilidad de los datos: Selecciona Internal.
   • Fecha de la última revisión: Selecciona la fecha de hoy.
4. Haz clic en Guardar.

Adjuntaste correctamente un aspecto estructurado a la entrada. A diferencia de una etiqueta simple, estos datos se validan con el esquema que creaste.

6. Detección y verificación unificadas

No hicimos este trabajo solo para completar formularios. Lo hicimos para que los datos sean detectables y confiables. Veamos cómo estos metadatos cambian la experiencia del desarrollador para la búsqueda y la detección.

Vuelve a la página principal de Búsqueda en Knowledge Catalog Universal Catalog.

⚠️ Advertencia: Knowledge Catalog Universal Catalog ofrece dos experiencias de búsqueda distintas con diferentes sintaxis: Lenguaje natural (con asistencia de IA) y Palabra clave (coincidencia estructurada/exacta). En este codelab, usamos la búsqueda por palabra clave.

Imagina que eres un ingeniero de plataformas que aplica la administración. Debes encontrar todos los activos marcados como "Internos" que estén regidos por tu tipo de aspecto específico. Debes usar predicados precisos basados en tu esquema.

Puedes verificar esto de dos maneras: usando una sintaxis de consulta precisa (esencial para la automatización) o usando filtros interactivos de la IU.

Método 1: Realiza la verificación mediante la consulta estructurada

1. En la barra de búsqueda (en el modo de búsqueda por palabra clave), ingresa la siguiente consulta estructurada.

aspect:data-asset-governance.data-sensitivity=Internal

2. Deberías ver tu tabla retail_data.transactions.

Método 2: Realiza la verificación mediante las facetas de filtro de la IU

1. Borra la barra de búsqueda para restablecer la vista.
2. Mira el panel Filtrar por propiedades en el lado izquierdo de la pantalla.
3. Desplázate hacia abajo y expande la sección Administración de recursos de datos (esto representa el tipo de aspecto que creaste).
4. En Sensibilidad de los datos, marca la casilla de Internal.
5. Los resultados de la búsqueda se actualizarán para mostrar la tabla retail_data.transactions.

Ya sea que uses la consulta escrita o los filtros de la IU, el mecanismo subyacente es el mismo.

Esto demuestra la diferencia fundamental entre Knowledge Catalog y una wiki simple: tus metadatos son una estructura consultable. Ahora puedes compilar auditorías automatizadas (p.ej., "Buscar todas las tablas en las que last_review_date sea > 1 año") que se basen en esta estructura predecible.

7. Limpia tu entorno

Para evitar que se generen cargos continuos, borra los recursos creados en este codelab.

Borra el conjunto de datos de BigQuery

Este comando es irreversible y usa la marca -f (forzar) para quitar el conjunto de datos y todas sus tablas sin confirmación.

⚠️ Advertencia: Para evitar la pérdida accidental de datos, te recomendamos que escribas el siguiente comando de forma manual en lugar de copiarlo y pegarlo, y que te asegures de que el nombre del conjunto de datos sea correcto.

# Re-run these exports if your Cloud Shell session timed out
export PROJECT_ID=$(gcloud config get-value project)

# Manually type this command to confirm you are deleting the correct dataset
bq rm -r -f --dataset $PROJECT_ID:retail_data

Borra los artefactos de Knowledge Catalog

1. Navega a IU de Knowledge Catalog Universal Catalog > Administrar metadatos > Catálogo.
2. En Tipos de aspecto y plantillas de etiquetas , selecciona el tipo de aspecto data_asset_governance y bórralo.
3. Navega a Administrar metadatos > Glosarios , selecciona el Retail Business Glossary y bórralo. Asegúrate de borrar primero el término Gross Merchandise Value y, luego, borrar el glosario.

8. ¡Felicitaciones!

Dejaste atrás el simple etiquetado de datos y estableciste un modelo de administración estructurado y fundamental en Knowledge Catalog.

Aprendiste lo siguiente:

• Los glosarios resuelven la ambigüedad empresarial.
• Los tipos de aspecto proporcionan el contrato de esquema para los metadatos técnicos.
• Los aspectos aplican ese esquema a las entradas de datos reales.
• Knowledge Catalog Search utiliza estos metadatos estructurados para una detección precisa.

Próximos pasos

• Administración como código: Usa el proveedor de Google Cloud Terraform para definir tus tipos de aspecto y glosarios en el control de versiones, lo que garantiza esquemas coherentes en los entornos de desarrollo, prueba y producción.
• Etiquetado automatizado: Escribe una Cloud Function o un paso de Cloud Build que se active con la creación de un conjunto de datos nuevo que adjunte automáticamente tu aspecto "Administración de recursos de datos" con valores predeterminados (p.ej., sensitivity=Internal, steward=TBD) y lo marque para su revisión.