Establece el contexto de datos fundamental con Knowledge Catalog

Knowledge Catalog (anteriormente, Dataplex Universal Catalog) te permite adjuntar metadatos estructurados y definiciones empresariales claras directamente a tus recursos de datos. Proporcionar este contexto hace que tus datos sean detectables, genera confianza para los usuarios y fundamenta los agentes de IA.

En este instructivo para administradores de datos y analistas empresariales, completarás pasos basados en la IU para crear términos empresariales estándar y contexto de metadatos antes de automatizar estos flujos de trabajo. También explorarás cómo funcionan juntos los conceptos clave de Knowledge Catalog.

Objetivos

En este instructivo, aprenderás a realizar lo siguiente:

• Crea una fuente única de información para los términos empresariales con un glosario empresarial.
• Estructura y organiza los metadatos con tipos de aspectos.
• Adjunta metadatos a los recursos de datos con aspectos.
• Usa la búsqueda de Knowledge Catalog para encontrar exactamente lo que necesitas con estos nuevos metadatos estructurados.

Antes de comenzar

Antes de comenzar, haz lo siguiente:

• Selecciona un proyecto deGoogle Cloud para este instructivo.
• Confirma que la facturación esté habilitada para tu proyecto.

Configura tu entorno

En este instructivo, se usa Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.

1. En la consola de Google Cloud , haz clic en Activar Cloud Shell en la barra de herramientas de la parte superior derecha. El aprovisionamiento y la conexión al entorno demorarán unos minutos.

2. En Cloud Shell, configura tus variables PROJECT_ID y LOCATION para que todos los comandos futuros se orienten a tu proyecto de Google Cloud específico.

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

   Nota: En ocasiones, se agota el tiempo de espera de las sesiones de Cloud Shell. Antes de ejecutar las secuencias de comandos de shell, puedes verificar tus variables de entorno ejecutando echo $PROJECT_ID. Si el comando devuelve una línea vacía, vuelve a ejecutar los comandos de exportación de este paso de configuración del entorno.

3. Habilita los servicios de Google Cloud necesarios.

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

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

Usa el siguiente código para crear un conjunto de datos de BigQuery y cargar algunas transacciones de CSV de muestra en una tabla. Después de crear la tabla, Knowledge Catalog la descubre y crea una entrada para ella en el catálogo.

Piensa en una entrada como la representación que hace Knowledge Catalog de un recurso de datos. Es como un registro en el catálogo al que puedes adjuntar metadatos. En lugar de agregar contexto a la tabla de BigQuery (o enriquecerla) directamente, lo agregas a su entrada en Knowledge Catalog.

# Create the BigQuery Dataset in the us-central1 region
bq --location=$LOCATION mk --dataset \
    --description "Sample retail data for foundational data context tutorial" \
    $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 a BigQuery table
bq load \
    --source_format=CSV \
    --autodetect \
    retail_data.transactions \
    /tmp/transactions.csv

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

Ejecuta una consulta SELECT para verificar tu configuración:

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

Resultado de ejemplo:

+----------------+------------------+-------+------------------+
| transaction_id |    user_email    |  gmv  | transaction_date |
+----------------+------------------+-------+------------------+
|           1001 | [e-mail] | 150.5 |       2025-08-28 |
|           1002 | [e-mail] |  75.0 |       2025-08-28 |
+----------------+------------------+-------+------------------+

Nota: No es necesario que registres o importes la tabla de forma manual en Knowledge Catalog. Knowledge Catalog transfiere automáticamente metadatos técnicos de las tablas de BigQuery y crea entradas.

Establece términos comunes con un glosario empresarial

Un buen contexto de datos se basa en definiciones claras que responden preguntas como "¿Qué significa este nombre de columna?" Por ejemplo, un desarrollador no debería tener que adivinar si una columna llamada gmv significa valor total de transacciones o si incluye impuestos y devoluciones. Un glosario empresarial crea una fuente única de información para estas definiciones en toda tu organización. Cuando los compañeros de equipo o los agentes de IA analizan tus datos, heredan este contexto empresarial preciso. Las definiciones compartidas alinean las métricas entre equipos, como Finanzas, Ventas y Operaciones, y ayudan a los agentes de IA a evitar alucinaciones.

Sigue estos pasos para crear un glosario y definir tu primer término:

1. En la consola de Google Cloud , ve a la página Glosarios de Knowledge Catalog.

   Ir a Glosarios

2. Haz clic en Crear glosario empresarial.

3. Ingresa los siguientes detalles:

   • Nombre visible: Retail Business Glossary
   • Ubicación: us-central1 (Iowa)

4. Haz clic en Crear.

5. Haz clic en Crear categoría.

6. Asígnale el nombre Sales Metrics a la categoría y haz clic en Crear.

7. Selecciona la categoría Métricas de ventas y haz clic en Agregar término.

8. Asigna el nombre Gross Merchandise Value al término y haz clic en Crear.

9. Haz clic en el término valor total de transacciones para abrir su página de detalles.

10. Haz clic en Agregar junto a Descripción general. Ingresa los siguientes detalles: 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.

11. Haz clic en Guardar.

Ahora creaste un término del glosario que puedes vincular a las entradas de datos de tu organización.

Define metadatos técnicos con un tipo de aspecto

Cuando trabajas con datos, a menudo necesitas responder preguntas como "¿Quién es el propietario de este conjunto de datos dañado?" o "¿Se aprobó el uso de esta tabla?". Las etiquetas de metadatos no estructurados intentan responder estas preguntas, pero se vuelven obsoletas o incoherentes con rapidez. Por ejemplo, una tabla podría etiquetarse como owner:bob y otra como steward:[e-mail]. Para mantener tus metadatos organizados a gran escala, necesitas un esquema coherente.

Aquí es donde entran en juego los tipos de aspectos. Un tipo de aspecto es un plano de metadatos que te permite establecer reglas claras y campos obligatorios. Exigir campos estándar, como direcciones de correo electrónico válidas para los administradores de datos, permite que las secuencias de comandos downstream validen y protejan tus metadatos automáticamente.

Sigue estos pasos para crear un tipo de aspecto:

1. En la consola de Google Cloud , ve a la pestaña Tipos de aspectos de Knowledge Catalog en la página Tipos de metadatos.

   Ir a Tipos de aspectos

2. En la pestaña Personalizada, haz clic en Crear.

3. Ingresa los siguientes detalles:

   • Nombre visible: Data Asset Context
   • Ubicación: us-central1 (Iowa)

4. En la sección Plantilla, haz clic en Agregar campo para crear los siguientes tres campos:

   • Campo 1:

     • Nombre visible: Data Steward
     • Tipo: Text
     • Es obligatorio: Selecciona la casilla de verificación.
     • Tipo de texto: Plain text

   • Campo 2 (haz clic en Agregar campo):

     • Nombre visible: Data Sensitivity
     • Tipo: Enum
     • Is Required: Déjalo como opcional.
     • Valores: Agrega Public, Internal y Confidential

   • Campo 3 (haz clic en Agregar campo):

     • Nombre visible: Last Review Date
     • Is Required: Déjalo como opcional.
     • Tipo: Date and time

5. Haz clic en Guardar.

Ahora tienes un tipo de aspecto para los campos de metadatos relacionados con la administración de datos, como el administrador de datos, el nivel de sensibilidad y la fecha de revisión. En la siguiente sección, aplicarás este esquema a una entrada de tabla adjuntando un aspecto con valores específicos para estos campos.

Enriquece una entrada con contexto empresarial y técnico

Los nombres de las columnas suelen ser abreviados o ambiguos. Vincular una columna a un término de tu glosario empresarial proporciona una definición clara y coherente. En este paso, enriquecerás la entrada de la tabla retail_data.transactions vinculando el término Gross Merchandise Value a una columna llamada gmv y adjuntando un aspecto a la entrada de la tabla con tu tipo de aspecto.

Vincula una columna a un término empresarial

Para aclarar qué es la columna gmv en retail_data.transactions, vincúlala a tu término Gross Merchandise Value.

1. En la consola de Google Cloud , ve a la página Búsqueda de Knowledge Catalog.

   Ir a Búsqueda

2. Haz clic en Filtros para abrir el panel Filtros.

3. En Alcance, selecciona Proyecto actual.

4. Busca retail_data.transactions y haz clic en la tabla de transacciones devueltas.

5. Haz clic en la pestaña Esquema.

6. Selecciona la casilla de verificación junto a la columna gmv y haz clic en Agregar término empresarial.

7. Selecciona Gross Merchandise Value.

Adjunta un aspecto a la entrada de la tabla

Además de vincular términos empresariales a columnas, puedes adjuntar un aspecto a una entrada de tabla para capturar metadatos a nivel de tabla, como la propiedad y la sensibilidad de los datos.

Un aspecto es una instancia de un tipo de aspecto, con valores específicos para los campos de metadatos. Cuando adjuntas un aspecto a una entrada, Knowledge Catalog compara la información que proporcionas con el esquema definido en el tipo de aspecto para garantizar la coherencia.

Para definir la propiedad y la sensibilidad de la tabla retail_data.transactions, adjunta el aspecto Data Asset Context:

1. En la pestaña Detalles de la página de entrada retail_data.transactions, haz clic en Agregar junto a Aspectos opcionales.
2. Selecciona Data Asset Context en la lista.

3. Ingresa los valores en los campos:

   • Administrador de datos: [e-mail]
   • Sensibilidad de los datos: Selecciona Internos.
   • Last Review Date: Selecciona la fecha de hoy.

4. Haz clic en Guardar.

Enriqueciendo tus datos de muestra de transacciones de venta minorista, estableciste una base sólida de contexto de datos en Knowledge Catalog.

Busca entradas con metadatos enriquecidos

Ahora puedes usar la búsqueda de Knowledge Catalog para encontrar entradas según el contexto empresarial que configuraste. Por ejemplo, puedes encontrar todos los recursos con un nivel de sensibilidad específico o buscar el término del glosario para descubrir las tablas subyacentes.

Nota: Knowledge Catalog ofrece dos experiencias de búsqueda distintas con sintaxis diferentes: Lenguaje natural (asistida por IA) y Palabra clave (concordancia exacta o estructurada). Este instructivo se enfoca en el lenguaje natural.

1. En la consola de Google Cloud , ve a la página Búsqueda de Knowledge Catalog.

   Ir a Búsqueda

2. Haz clic en Filtros para abrir el panel Filtros.

3. En Alcance, selecciona Proyecto actual.

4. En la barra de búsqueda, ingresa Find tables where the Data Asset Context aspect has Internal sensitivity..

5. Deberías ver tu tabla retail_data.transactions en la lista de resultados.

6. Borra la barra de búsqueda y escribe Find tables with the Gross Merchandise Value term attached..

7. Deberías volver a ver la tabla retail_data.transactions en los resultados, ya que su columna gmv está vinculada directamente a este término empresarial.

Cuando conectas un agente de IA a Knowledge Catalog, hereda estos metadatos enriquecidos automáticamente. Por ejemplo, cuando le pides a un agente que recupere métricas de ventas internas, lee el aspecto Sensibilidad de los datos (que estableciste como Interno) y el término del glosario valor total de transacciones vinculado. Este contexto compartido ayuda al agente a verificar sus fuentes de datos, respetar las políticas de acceso y evitar las alucinaciones.

Realiza una limpieza

Para evitar que se generen cargos, borra los recursos que creaste en este instructivo.

Borra el conjunto de datos de muestra

Para borrar el conjunto de datos de muestra de BigQuery y todas sus tablas, usa el siguiente comando. Esta acción es irreversible.

Advertencia: Este comando de eliminación recursiva no solicita confirmación. Para evitar la pérdida accidental de datos por variables de entorno incorrectas, verifica el ID del proyecto y el nombre del conjunto de datos antes de ejecutarlo.

# 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 artefactos de Knowledge Catalog

1. En la consola de Google Cloud , ve a la pestaña Tipos de aspectos de Knowledge Catalog en la página Tipos de metadatos.

   Ir a Tipos de aspectos

2. Selecciona el tipo de aspecto Data Asset Context y haz clic en Borrar.

3. En la consola de Google Cloud , ve a la página Glosarios de Knowledge Catalog.

   Ir a Glosarios

   Nota: Debes borrar todos los términos y categorías antes de poder borrar el glosario.

4. Selecciona el término Gross Merchandise Value y haz clic en Borrar.

5. Selecciona la categoría Sales Metrics y haz clic en Borrar.

6. Selecciona Retail Business Glossary y haz clic en Borrar.

¿Qué sigue?

Para obtener más información sobre la selección de catálogos y la creación de agentes con Knowledge Catalog, consulta los siguientes recursos:

• Administra aspectos y enriquece los metadatos: Obtén información para definir esquemas personalizados y adjuntar metadatos estructurados en Administra aspectos y enriquece los metadatos.
• Administra glosarios empresariales: Obtén información para establecer un vocabulario estandarizado para tu organización en Administra un glosario empresarial.
• Administra con Terraform: Obtén información para aprovisionar tipos de aspectos y glosarios personalizados con Terraform.
• Trabaja con términos del glosario a gran escala: Realiza un enriquecimiento masivo de metadatos con archivos JSON en Acerca de la importación y exportación de glosarios y vínculos de entradas.
• Enriquece los metadatos con agentes: Crea un agente de IA para extraer el contexto y enriquecer tus recursos de datos en Crea un agente para enriquecer tus metadatos.
• Explora más casos de uso: Descubre flujos de trabajo y situaciones personalizables adicionales en Casos de uso.