Lab 3: Descubre la carga perdida con BigQuery Graph y Conversational Analytics

1. Introducción

Te damos la bienvenida a la etapa final de la investigación de la carga perdida. Después de rastrear el contenedor robado de figuras de Android desde Londres hasta Sídney, el rastro se enfrió. Al inhabilitar su transpondedor, la caja fuerte inteligente del contenedor activó un cierre de emergencia automático.

Para recuperar la valiosa carga antes de que se cierre para siempre, tu misión es encontrar la ubicación final del contenedor y recuperar la contraseña de anulación manual para abrir la caja fuerte de forma física.

Para encontrar el contenedor faltante y asegurar la carga, crearás un gráfico de propiedades de BigQuery para hacer un seguimiento del viaje del envío. Luego, consultarás esta red en lenguaje natural con Conversational Analytics y, para finalizar, realizarás una búsqueda semántica en los metadatos de tus datos con Knowledge Catalog para ubicar los códigos de anulación.

💡 ¿Te perdiste el lab 1 o el lab 2? ¡No te preocupes! Este lab es completamente autónomo. Los pasos de configuración del entorno aprovisionarán todo lo que necesitas para que puedas comenzar de inmediato y completar el proceso de forma independiente.

Actividades

• Clona el repositorio y ejecuta la secuencia de comandos de configuración en Google Cloud Shell.
• Crea un gráfico de propiedades en BigQuery que vincule los datos de la empresa, el buque y el manifiesto.
• Usa Conversational Analytics para consultar el gráfico en lenguaje natural y rastrear el viaje de la carga para identificar al operador responsable.
• Ubica la tabla que contiene los códigos de anulación finales con Knowledge Catalog.
• Usa el control de acceso a nivel de columna de BigQuery para desenmascarar y revelar el código final.

Requisitos

• Un navegador web, como Chrome
• Un proyecto de Google Cloud con la facturación habilitada.
• Acceso a Google Cloud Shell

Este codelab está diseñado para profesionales de datos de todos los niveles.

Los recursos creados en este codelab deberían costar menos de USD 5.

Duración estimada: Completar este codelab te llevará aproximadamente 45 minutos.

2. Antes de comenzar

Crea un proyecto de Google Cloud

1. En la consola de Google Cloud, en la página del selector de proyectos, selecciona o crea un proyecto de Google Cloud.
2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud.

Inicie Cloud Shell

Usarás Google Cloud Shell para descargar el código, ejecutar secuencias de comandos de configuración y, luego, implementar la aplicación.

1. En una pestaña nueva del navegador, abre Cloud Shell:

2. Una vez que te conectes, configura tu ID del proyecto y confirma tu entorno:

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

Deberías ver un mensaje similar a este:

Your active configuration is: [cloudshell-####]
Updated property [core/project]

Habilita las API obligatorias

Ejecuta el siguiente comando en Cloud Shell para habilitar las APIs requeridas:

gcloud services enable \
 bigquery.googleapis.com \
 aiplatform.googleapis.com \
 datacatalog.googleapis.com  \
 geminidataanalytics.googleapis.com \
 cloudaicompanion.googleapis.com 

Si la ejecución se realiza correctamente, deberías ver un mensaje similar al siguiente:

Operation "operations/..." finished successfully.

3. Configura tu entorno

En los labs anteriores de esta serie, sentamos las bases para nuestra investigación.

1. Clona el repositorio

Clona el repositorio del codelab en tu entorno de Cloud Shell:

cd ~/
git clone --filter=blob:none --no-checkout https://github.com/GoogleCloudPlatform/devrel-demos.git
cd ~/devrel-demos
git sparse-checkout init --cone
git sparse-checkout set codelabs/bigquery-graph-analytics
git checkout main
cd codelabs/bigquery-graph-analytics/

2. Configura tablas base y etiquetas de política

Ejecuta la secuencia de comandos de configuración para completar tu conjunto de datos de BigQuery y aplicar etiquetas de seguridad a nivel de la columna para restringir los datos sensibles:

bash setup_lab.sh

Confirma que el resultado de la terminal muestre que la inicialización se realizó correctamente:

🚀 Provisioning foundational tables and deploying Policy Tag security bindings...
🎯 Active Project: your-project-id
...
🎉 Success! Foundational tables initialized and Column-Level Policy Tags fully mapped out of the box!

Ahora que configuraste correctamente tu entorno y BigQuery se completó con los datos de logística, puedes compilar un gráfico de propiedades para conectar tus tablas y hacer un seguimiento del viaje de la carga.

4. Conecta tus datos con BigQuery Graph

Para analizar nuestros datos de la cadena de suministro, definiremos cómo se relacionan entre sí las empresas, las embarcaciones y los manifiestos. La creación de un gráfico de propiedades nos permite consultar estas conexiones con facilidad.

1. Cómo los gráficos de propiedades modelan las relaciones

Un gráfico de propiedades de BigQuery modela redes con los siguientes elementos:

• Nodos: Son las entidades de la red. En este lab, los nodos representan empresas (que almacenan detalles de contacto directamente), manifiestos y buques.
• Bordes: Son las relaciones que vinculan los nodos. Por ejemplo:
  • Una arista conecta un Manifiesto con un Recipiente (a través de relaciones en la tabla manifests).
  • Una arista conecta un Vessel con una Company (a través de relaciones en la tabla vessels).
• Propiedades: Son los metadatos almacenados en los nodos o los bordes. Por ejemplo, un nodo Company tiene columnas como company_name y phone_number, y un nodo Manifest tiene seal_integrity_status y coordenadas (last_ping_lat, last_ping_long).
• Etiquetas: Son los nombres de las etiquetas asignadas a los nodos (p.ej., Company, Vessel, Manifest) y a las aristas (p.ej., CARRIED_BY, OPERATED_BY) para que las herramientas de consulta puedan reconocer los tipos de nodos y relaciones.

2. Implementa el gráfico de propiedades en BigQuery

El archivo setup_graph.sql contiene el DDL de SQL para definir y crear el gráfico de propiedades, pero actualmente está incompleto. Debes definir las etiquetas de borde (relaciones) en este archivo de esquema antes de compilarlo y, luego, implementarlo:

1. Abrir el editor de Cloud Shell

2. Abre el archivo setup_graph.sql en el editor de Cloud Shell.

3. Ubica los marcadores de posición para las etiquetas de borde:
   • Línea 22: Reemplaza `EDGE_TABLE_PLACEHOLDER` por una etiqueta significativa que represente cómo se relacionan los manifiestos con los buques (p.ej., CARRIED_BY).
   • Línea 27: Reemplaza `EDGE_TABLE_PLACEHOLDER` por una etiqueta que represente cómo se relacionan los buques con las empresas (p.ej., OPERATED_BY).
4. Guarda el archivo.

Ahora, regresa a la terminal de Cloud Shell y, con la secuencia de comandos completada, implementa el gráfico de propiedades actualizado:

bq query --use_legacy_sql=false < setup_graph.sql

Deberías ver un resultado que indique que el trabajo se completó:

Waiting on bqjob_r... ... (0s) Current status: DONE

Puedes ver los detalles del gráfico de propiedad en la consola de BigQuery:

Busca el conjunto de datos lost_cargo_dataset y selecciona Gráficos:

Ahora que compilamos correctamente nuestro gráfico de propiedades, exploremos BigQuery Studio para consultar y visualizar las conexiones.

5. Cómo consultar tu gráfico

Puedes consultar y explorar el gráfico de forma visual con el Graph Query Language (GQL) nativo directamente en BigQuery Studio.

1. Consulta la cadena de contenedor -> buque -> empresa

Exploremos las consultas de GQL para averiguar quién opera los buques que transportan carga. Para encontrar el operador, se debe recorrer tres nodos de entidades independientes en nuestra red de logística:

1. Comienza en el nodo del contenedor Manifest.
2. Sigue la arista de relación CARRIED_BY para encontrar el Vessel que lo transporta.
3. Sigue el borde de relación OPERATED_BY desde esa embarcación hasta el Company responsable y recupera su ID.

Primero, ejecutemos una consulta para visualizar la red completa (sin filtros) y ver el gráfico completo.

1. Abre una pestaña nueva en el editor de SQL de BigQuery Studio, pega la siguiente consulta en GQL y haz clic en Ejecutar:

   SELECT * FROM GRAPH_TABLE(
     `lost_cargo_dataset.logistics_network`
     MATCH p = (m:Manifest)-[:CARRIED_BY]->(v:Vessel)-[:OPERATED_BY]->(comp:Company)
     RETURN TO_JSON(p) AS path
   );
   

2. Cuando se complete la consulta, en el panel Resultados de la consulta que se encuentra en la parte inferior, haz clic en la pestaña Gráfico (Graph) (ubicada junto a la pestaña Tabla de resultados [Results table]).

3. BigQuery renderiza los resultados como una representación visual interactiva. Acerca el mapa para ver la red completa de contenedores, buques y operadores conectados.

Anatomía de una consulta de GQL

Desglosemos la consulta de GQL que acabamos de ejecutar:

• GRAPH_TABLE: Dirige BigQuery para que ejecute una consulta de gráfico de propiedad en el gráfico logistics_network.
• MATCH: Declara el patrón de recorrido de varios saltos. Comenzamos en Manifest (m), hacemos coincidir la relación de borde :CARRIED_BY que apunta a Vessel (v) y, luego, hacemos coincidir la relación de borde :OPERATED_BY que apunta a Company (comp).
• GQL reemplaza la lógica de unión compleja con flechas de relación intuitivas y legibles en ASCII ()->[]->(), lo que hace que sea muy sencillo escribir y optimizar consultas de múltiples saltos.
• RETURN: Muestra las propiedades o la ruta de acceso JSON de los elementos coincidentes.

2. Cómo filtrar los resultados de consultas de GQL

Ahora, filtremos la consulta para que solo veamos la ruta de acceso de nuestro contenedor objetivo vulnerado MV-CAPYBARA-003.

1. Pega la siguiente consulta en el editor de SQL y haz clic en Ejecutar:

   SELECT * FROM GRAPH_TABLE(
     `lost_cargo_dataset.logistics_network`
     MATCH p = (m:Manifest {shipment_id: 'MV-CAPYBARA-003'})-[:CARRIED_BY]->(v:Vessel)-[:OPERATED_BY]->(comp:Company)
     RETURN TO_JSON(p) AS path
   );
   

2. Haz clic en la pestaña Gráfico en los resultados.

3. Ahora el visualizador solo muestra la ruta de navegación activa para MV-CAPYBARA-003. Acerca la imagen para ver los nodos y las conexiones:
   • Haz doble clic en el nodo Company para abrir el panel de propiedades. En Propiedades, verás el operador company_id: 103 (Davy Jones Shipping). Anota el ID de esta empresa, ya que lo necesitarás más adelante para recuperar la contraseña de autorización del registro de seguridad.
   • Haz doble clic en el nodo Vessel para verificar que sea el Flying Dutchman.

Verificación de estado:

• Qué logramos: Consultamos nuestra red de grafos de propiedades para ubicar al operador del buque que transportaba el envío faltante (company_id: 103 / Davy Jones Shipping).
• Qué debemos hacer a continuación: Explorar más nuestro gráfico para ubicar hacia dónde se dirige el buque comprometido.

6. Chatea con tu gráfico usando Conversational Analytics

Ahora que consultaste tu gráfico de forma manual para encontrar el ID de la empresa, usemos Conversational Analytics para chatear directamente con nuestro gráfico y determinar hacia dónde se dirige nuestro contenedor.

1. Cómo iniciar una sesión de Conversational Analytics

1. En la consola de Google Cloud, navega a la consola de BigQuery y expande el panel de recursos para encontrar tu conjunto de datos (lost_cargo_dataset).
2. Haz clic en tu recurso de Property Graph: logistics_network.
3. En la barra de herramientas del panel de detalles que se encuentra en la parte superior, haz clic en el botón Chat. Se abrirá una sesión de Conversational Analytics precargada con el contexto de tu gráfico.

Nota: El agente de Conversational Analytics lee automáticamente la estructura de tu gráfico y precarga su contexto cuando haces clic en Chat.

2. Ubica el puerto de acoplamiento más cercano para el contenedor secuestrado.

Un avión de patrulla marítima acaba de detectar una embarcación que coincide con la descripción de nuestro buque de carga navegando fuera de la red (con el transpondedor desactivado) en las coordenadas POINT(-122.48 37.55). Para interceptar el cargamento, debemos encontrar el puerto de atraque más cercano en el que opera el sindicato clandestino Davy Jones Shipping.

En lugar de buscar manualmente todos los puertos globales, consultaremos nuestra red de gráficos para extraer los puertos conectados a la flota activa del sindicato y medir cuál es el más cercano físicamente al avistamiento.

1. En el cuadro de chat de Conversational Analytics, ingresa la siguiente instrucción:

   Find all ports associated with Davy Jones Shipping vessels. Which port is closest to coordinate POINT(-122.48 37.55), show the distance in km, and display it on a map.
   

2. Observa la respuesta con atención. El agente recorre el gráfico y devuelve la instalación de atraque más cercana y su distancia:
   • Puerto de conexión: Mountain View Terminal
   • Distancia: 39.42 kilometers
3. Dado que Conversational Analytics funciona con Gemini y tiene integración geoespacial (SIG) nativa, puede interpretar puntos de coordenadas geográficas y aprovechar su conocimiento del mundo para verificar la ubicación:"El buque se encuentra a aproximadamente 39.42 kilómetros de la terminal de Mountain View, California, lo que indica que se dirige allí para atracar".

Esto confirma que nuestra carga se dirige directamente a Mountain View.

Bajo el capó: Graph Query Language (GQL) y GIS geoespacial

Tras bambalinas, el agente de Conversational Analytics compiló y ejecutó de forma dinámica una consulta que combina la coincidencia de rutas del grafo con los cálculos de distancia geoespacial. Esto se logra con una cláusula COLUMNS nativa de GQL, que calcula la distancia geodésica de forma nativa dentro de la coincidencia de recorrido del grafo:

SELECT port_id, port_name, country, latitude, longitude, distance_km 
FROM GRAPH_TABLE(
  `lost_cargo_dataset.logistics_network`
  MATCH (c:Company)<-[]-(v:Vessel)-[]->(p:Port)
  WHERE LOWER(c.company_name) = 'davy jones shipping'
  COLUMNS (
    p.port_id, 
    p.port_name, 
    p.country, 
    p.latitude, 
    p.longitude, 
    ROUND(ST_DISTANCE(ST_GEOGPOINT(p.longitude, p.latitude), ST_GEOGPOINT(-122.48, 37.55)) / 1000, 2) AS distance_km
  )
)
ORDER BY distance_km ASC;

Al combinar las funciones geoespaciales (GIS) nativas (ST_DISTANCE, ST_GEOGPOINT) con una coincidencia de gráfico de propiedades de GQL, BigQuery resuelve de forma dinámica la huella operativa del sindicato y calcula la proximidad física en el mundo real en una sola consulta.

Verificación de estado:

• Qué logramos: Usamos Conversational Analytics para rastrear los puertos de atraque de la flota del operador fantasma (Manifest ➔ Vessel ➔ Company ➔ Docks) y calculamos que el barco sospechoso se dirige directamente a la terminal de Mountain View (a solo unos 39 km de distancia).
• Qué debemos hacer a continuación: Encontrar el registro de datos que contiene el código de anulación manual para que nuestro equipo local de intervención táctica pueda interceptar el envío y desbloquear manualmente el contenedor una vez que atraque en la terminal de Mountain View.

7. Encuentra los datos faltantes con Knowledge Catalog

El gráfico de propiedades muestra relaciones, pero no contiene la tabla en la que se almacenan los códigos de anulación reales.

En un entorno empresarial real con cientos de conjuntos de datos y tablas, encontrar esta información puede ser difícil. Usaremos Knowledge Catalog para realizar una búsqueda semántica y ubicar la tabla correcta.

1. Búsqueda semántica en Knowledge Catalog

1. En la consola de Google Cloud, busca Knowledge Catalog ➔ Search y navega a él.
2. En la columna de filtro de búsqueda, en Sistemas, marca BigQuery para acotar los resultados.
3. En el cuadro de búsqueda, ingresa la siguiente consulta:

   container override codes
   

4. Haz clic en el recurso de tabla maritime_security_registry que aparece en los resultados de la búsqueda:

Cuando inspecciones el esquema de metadatos, verás que la tabla contiene columnas para los datos de seguridad del contenedor, como la empresa coordinadora co_id, el token de custodio cust_tok y, lo que es más importante, la columna de contraseña de anulación del contenedor seguro: clc_ovr_cd.

Encontramos correctamente la mesa y la columna segura exacta que necesitamos para recuperar nuestra carga.

Bajo el capó: Correlación semántica: El nombre de la tabla (maritime_security_registry) y el nombre de su columna clave (clc_ovr_cd) son completamente oscuros. Sin el análisis de búsqueda semántica del Catálogo de conocimiento de la descripción de la columna ("Código de anulación del contenedor seguro"), encontrar esta tabla buscando "códigos de anulación" habría sido casi imposible.

🔓 Administración del mundo real: En un entorno empresarial de producción, los equipos de seguridad y administración también aprovechan lo siguiente:

• Aspectos y plantillas de etiquetas: Para adjuntar metadatos empresariales (como Propietario de los datos, Período de retención o Clasificación de PII) a los esquemas de tablas
• Linaje de datos: Para generar automáticamente diagramas de flujo visuales que representan cómo los sistemas posteriores consultan y consumen tablas como maritime_security_registry.

2. Inspecciona la seguridad de las columnas en BigQuery

1. Regresa a la consola de BigQuery.
2. En la pestaña Explorador, selecciona lost_cargo_dataset y haz clic en la tabla maritime_security_registry.
3. Haz clic en la pestaña Esquema.

4. Observa que la columna clc_ovr_cd está protegida por una etiqueta de política llamada MaskShippingDetails (que se muestra en la columna Etiquetas de política).
5. Abre una nueva pestaña del editor de SQL en BigQuery y ejecuta la siguiente consulta para intentar ver los códigos de anulación del registro:

   SELECT * FROM `lost_cargo_dataset.maritime_security_registry` 
   WHERE co_id = 103;
   

6. Dado que tu cuenta aún no tiene permisos para leer las columnas etiquetadas con MaskShippingDetails, la consulta fallará de inmediato con un error de seguridad de la base de datos Access Denied:

Verificación de estado:

• Qué logramos: Encontramos la tabla (maritime_security_registry) y la columna (clc_ovr_cd) seguras que contienen el código de anulación.
• Qué debemos hacer a continuación: Otorgar permisos de lectura a tu cuenta para la columna protegida

8. Cómo vulnerar la seguridad de columnas para recuperar el código

Para leer el código de anulación final en texto no cifrado, debemos otorgar permiso a nuestra cuenta de usuario para leer las columnas etiquetadas con MaskShippingDetails.

1. Otorga permisos de etiquetas de política

1. En el panel de navegación de la izquierda de la consola de BigQuery, navega a Etiquetas de política.
2. Selecciona la taxonomía llamada LostCargoSecurity_.
3. En la lista de etiquetas, haz clic en MaskShippingDetails.
4. En el panel de información que se encuentra en el lado derecho de la pantalla, haz clic en Agregar principal. (Si el panel está oculto, haz clic en Mostrar panel de información en la esquina superior derecha).
5. En el campo Principales nuevas, ingresa tu correo electrónico de usuario activo de Google Cloud.
6. En el menú desplegable Selecciona un rol, busca y selecciona Lector detallado y, luego, haz clic en Guardar.

2. Consulta para el código de anulación

Vuelve al editor del espacio de trabajo de BigQuery. Como ahora tienes acceso de lectura detallado, deberíamos poder ejecutar la consulta de nuevo y ver los datos sin máscara:

SELECT *  FROM `lost_cargo_dataset.maritime_security_registry` 
WHERE co_id = 103;

🔓 Resultado

La consulta devuelve el código de anulación sin máscara:

SHIVER-ME-TIMBERS-888

¡Misión cumplida! 🚢

¡Felicitaciones! Si combinaste los gráficos de propiedades de BigQuery y Conversational Analytics con Knowledge Catalog y la seguridad a nivel de columnas, pudiste hacer un seguimiento de la flota fantasma y extraer el código de anulación del contenedor seguro.

El equipo de interceptación táctica se dirigió a la terminal de Mountain View. Con el código de anulación descifrado, están listos para abrir el contenedor de Capybara, asegurar la carga y recuperar con éxito nuestros activos perdidos.

9. Limpia

Para evitar que se generen cobros, limpia los recursos de zona de pruebas que se crearon durante este lab.

Vuelve a la terminal de Cloud Shell y borra el conjunto de datos de BigQuery que contiene las tablas de logística:

bq rm -r -f -d lost_cargo_dataset

Quita los archivos del repositorio clonado:

cd ..
rm -rf data-cloud-roadshow-26

10. Felicitaciones

Resolviste correctamente la investigación y recuperaste el código de anulación de la autorización.

Qué aprendiste

• Cómo compilar un gráfico de propiedades en BigQuery para representar entidades y relaciones complejas
• Cómo se configuran los nodos, las aristas, las propiedades y las etiquetas para capturar las conexiones de datos
• Cómo consultar gráficos de propiedades con lenguaje natural con Conversational Analytics de BigQuery
• Cómo se estructuran las expresiones del lenguaje de consultas de gráficos (GQL) para recorrer rutas relacionales
• Cómo descubrir recursos protegidos con Knowledge Catalog y acceder a datos restringidos a nivel de la columna con etiquetas de política

Vínculos a recursos

• Descripción general de BigQuery Conversational Analytics
• Referencia de sintaxis de grafos de propiedades de BigQuery
• Integración de Knowledge Catalog