Laboratório 3: como descobrir cargas perdidas com o BigQuery Graph e a Análise Conversacional

1. Introdução

Esta é a última etapa da investigação sobre a carga perdida. Depois de rastrear o contêiner roubado de bonecos do Android de Londres até Sydney, a pista esfriou. Ao desativar o transponder, o cofre de segurança inteligente do contêiner acionou um bloqueio de emergência automático.

Para recuperar a carga de alto valor antes que ela seja trancada para sempre, sua missão é encontrar o local final do contêiner e recuperar a senha de substituição manual para destrancar o cofre.

Para encontrar o contêiner perdido e proteger a carga, você vai criar um gráfico de propriedades do BigQuery para rastrear a jornada da remessa. Em seguida, você vai consultar essa rede em linguagem natural usando a Análise de conversação e concluir fazendo uma pesquisa semântica nos metadados dos seus dados com o Knowledge Catalog para localizar os códigos de substituição.

💡 Não fez o Laboratório 1 ou o Laboratório 2? Não se preocupe! Este laboratório é totalmente independente. As etapas de configuração do ambiente vão provisionar tudo o que você precisa para começar e concluir o processo de forma independente.

Atividades deste laboratório

• Clone o repositório e execute o script de configuração no Google Cloud Shell.
• Crie um gráfico de propriedades no BigQuery vinculando dados de empresa, embarcação e manifesto.
• Use a análise de conversação para consultar o gráfico em linguagem natural, rastreando a jornada da carga para identificar o operador responsável.
• Localize a tabela com os códigos de substituição finais usando o Knowledge Catalog.
• Use o controle de acesso no nível da coluna do BigQuery para remover a máscara e revelar o código final.

O que é necessário

• Um navegador da web, como o Chrome
• Tenha um projeto do Google Cloud com o faturamento ativado.
• Acesso ao Google Cloud Shell

Este codelab foi criado para profissionais de dados de todos os níveis.

Os recursos criados neste codelab custam menos de US $5.

Duração estimada:este codelab leva aproximadamente 45 minutos para ser concluído.

2. Antes de começar

Criar um projeto do Google Cloud

1. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto na nuvem do Google Cloud.
2. Verifique se o faturamento está ativado para seu projeto do Cloud.

Iniciar o Cloud Shell

Você vai usar o Google Cloud Shell para baixar o código, executar scripts de configuração e implantar o aplicativo.

1. Em uma nova guia do navegador, abra o Cloud Shell:

2. Depois de se conectar, defina o ID do projeto e confirme o ambiente:

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

Você verá uma mensagem semelhante a:

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

Ativar APIs obrigatórias

Execute o comando a seguir no Cloud Shell para ativar as APIs necessárias:

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

Se a execução for bem-sucedida, você vai receber uma mensagem semelhante a esta:

Operation "operations/..." finished successfully.

3. Configuração de seu ambiente

Nos laboratórios anteriores desta série, preparamos o terreno para nossa investigação.

1. Clonar o repositório

Clone o repositório do codelab no ambiente do 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. Configurar tabelas de base e tags de política

Execute o script de configuração para preencher o conjunto de dados do BigQuery e aplique tags de segurança no nível da coluna para restringir dados sensíveis:

bash setup_lab.sh

Confirme se a saída no terminal mostra uma inicialização bem-sucedida:

🚀 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!

Com o ambiente configurado e os dados de logística no BigQuery, agora é possível criar um gráfico de propriedades para conectar as tabelas e rastrear a jornada da carga.

4. Conectar seus dados usando o BigQuery Graph

Para analisar os dados da cadeia de suprimentos, vamos definir como empresas, embarcações e manifestos se relacionam. A criação de um gráfico de propriedades permite consultar essas conexões com facilidade.

1. Como os gráficos de propriedades modelam relacionamentos

Um gráfico de propriedades do BigQuery modela redes usando:

• Nós: as entidades na rede. Neste laboratório, os nós representam Empresas (que armazenam detalhes de contato diretamente), Manifestos e Embarcações.
• Bordas: as relações que vinculam os nós. Por exemplo:
  • Uma aresta conecta um Manifest a um Vessel (por meio de relações na tabela manifests).
  • Uma aresta conecta um navio a uma empresa (por meio de relações na tabela vessels).
• Propriedades: metadados armazenados em nós ou arestas. Por exemplo, um nó Company tem colunas como company_name e phone_number, e um nó Manifest tem seal_integrity_status e coordenadas (last_ping_lat, last_ping_long).
• Rótulos: nomes de tags atribuídos a nós (por exemplo, Company, Vessel, Manifest) e arestas (por exemplo, CARRIED_BY, OPERATED_BY) para que as ferramentas de consulta possam reconhecer os tipos de nós e relações.

2. Implantar o gráfico de propriedades no BigQuery

O arquivo setup_graph.sql contém a DDL SQL para definir e criar o gráfico de propriedades, mas está incompleto. É necessário definir os rótulos de aresta (relacionamentos) nesse arquivo de esquema antes de compilá-lo e implantá-lo:

1. Abrir o editor do Cloud Shell.

2. Abra o arquivo setup_graph.sql no editor do Cloud Shell.

3. Localize os marcadores de posição para rótulos de borda:
   • Linha 22: substitua `EDGE_TABLE_PLACEHOLDER` por uma tag significativa que represente como os manifestos se relacionam com as embarcações (por exemplo, CARRIED_BY).
   • Linha 27: substitua `EDGE_TABLE_PLACEHOLDER` por uma tag que represente como as embarcações se relacionam com as empresas (por exemplo, OPERATED_BY).
4. Salve o arquivo.

Agora, volte ao terminal do Cloud Shell e implante o gráfico de propriedades atualizado usando o script concluído:

bq query --use_legacy_sql=false < setup_graph.sql

Você vai ver uma saída indicando que o job foi concluído:

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

É possível conferir os detalhes do gráfico de propriedades no console do BigQuery:

Encontre o lost_cargo_dataset e selecione "Gráficos":

Com o gráfico de propriedades compilado, vamos acessar o BigQuery Studio para consultar e visualizar as conexões.

5. Consultar seu gráfico

É possível consultar e explorar o gráfico visualmente usando a Linguagem de consulta de gráficos (GQL) nativa diretamente no BigQuery Studio.

1. Consultar a cadeia contêiner -> embarcação -> empresa

Vamos analisar as consultas GQL para descobrir quem opera os navios de carga. Para encontrar o operador, é necessário percorrer três nós de entidade separados na nossa rede de logística:

1. Comece no nó do contêiner Manifest.
2. Siga a aresta de relação CARRIED_BY para encontrar o Vessel.
3. Siga a aresta de relacionamento OPERATED_BY da embarcação até o Company responsável e recupere o ID dele.

Primeiro, vamos executar uma consulta para visualizar a rede inteira (sem filtros) e ver o gráfico completo.

1. Abra uma nova guia no editor de SQL do BigQuery Studio, cole a seguinte consulta GQL e clique em Executar:

   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. Quando a consulta for concluída, no painel Resultados da consulta na parte de baixo, clique na guia Gráfico, que fica ao lado da guia Tabela de resultados.

3. O BigQuery renderiza os resultados como uma representação gráfica visual interativa. Aumente o zoom para ver a rede completa de contêineres, embarcações e operadores conectados.

Anatomia de uma consulta GQL

Vamos detalhar a consulta GQL que acabamos de executar:

• GRAPH_TABLE: instrui o BigQuery a executar uma consulta de gráfico de propriedades no gráfico logistics_network.
• MATCH: declara o padrão de travessia de vários saltos. Começamos em um Manifest (m), correspondemos à relação de aresta :CARRIED_BY que aponta para Vessel (v) e, em seguida, à relação de aresta :OPERATED_BY que aponta para Company (comp).
• O GQL substitui a lógica de junção complexa por setas de relacionamento intuitivas e legíveis em ASCII-art ()->[]->(), facilitando a gravação e a otimização de consultas de várias etapas.
• RETURN: retorna propriedades ou o caminho JSON dos elementos correspondentes.

2. Filtrar resultados de consultas GQL

Agora, vamos filtrar a consulta para analisar apenas o caminho do contêiner comprometido de destino MV-CAPYBARA-003.

1. Cole a consulta a seguir no editor SQL e clique em Executar:

   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. Clique na guia Gráfico em "Resultados".

3. O visualizador agora mostra apenas a rota de navegação ativa para MV-CAPYBARA-003. Aumente o zoom para ver os nós e as conexões:
   • Clique duas vezes no nó Company para abrir o painel de propriedades. Em Propriedades, você vai encontrar o operador company_id: 103 (Davy Jones Shipping). Anote o ID da empresa. Você vai precisar dele mais tarde para recuperar a senha de acesso do registro de segurança.
   • Clique duas vezes no nó Vessel para verificar se ele é o Flying Dutchman.

Verificação de status:

• O que fizemos: consultamos nossa rede de gráficos de propriedades para localizar o operador da embarcação que transportava a remessa desaparecida (company_id: 103 / Davy Jones Shipping).
• Próximas etapas: analise o gráfico para localizar o destino da embarcação comprometida.

6. Conversar com seu gráfico usando as Análises de conversação

Agora que você consultou o gráfico manualmente para encontrar o ID da empresa, vamos usar as Análises de Conversação para conversar diretamente com ele e identificar para onde nosso contêiner está indo.

1. Iniciar uma sessão do Conversational Analytics

1. No console do Google Cloud, acesse o console do BigQuery e abra o painel de recursos para encontrar seu conjunto de dados (lost_cargo_dataset).
2. Clique no recurso de gráfico de propriedades: logistics_network.
3. Na barra de ferramentas do painel de detalhes na parte de cima, clique no botão Chat. Isso abre uma sessão da Análise Conversacional pré-carregada com o contexto do seu gráfico.

Dica: o agente do Conversational Analytics lê automaticamente a estrutura do seu gráfico, pré-carregando o contexto quando você clica em "Chat".

2. Identifique o ponto de acoplamento mais próximo para o contêiner sequestrado

Uma aeronave de patrulha marítima acaba de avistar uma embarcação que corresponde à descrição do nosso navio de carga navegando fora da rede (com o transponder desativado) nas coordenadas POINT(-122.48 37.55). Para interceptar a carga, precisamos encontrar o porto de atracação mais próximo onde o sindicato fantasma Davy Jones Shipping opera.

Em vez de pesquisar manualmente todos os portos globais, vamos consultar nossa rede de gráficos para extrair os portos conectados à frota ativa do sindicato e medir qual deles está fisicamente mais próximo do avistamento.

1. Na caixa de chat das Análises de Conversação, insira o seguinte comando:

   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. Analise a resposta com atenção. O agente percorre o gráfico e retorna o cais mais próximo e a distância dele:
   • Porta de encaixe: Mountain View Terminal
   • Distância: 39.42 kilometers
3. Como a análise de conversas é alimentada pelo Gemini com integração geoespacial (GIS) nativa, ela pode interpretar pontos de coordenadas geográficas e aproveitar o conhecimento mundial para verificar o local:"A embarcação está a aproximadamente 39,42 quilômetros do terminal de Mountain View, na Califórnia, indicando que está indo para lá para atracar".

Isso confirma que nossa carga está indo direto para Mountain View!

Por dentro: Graph Query Language (GQL) e GIS geoespacial

Nos bastidores, o agente do Conversational Analytics compilou e executou dinamicamente uma consulta que combina a correspondência de caminho do gráfico com cálculos de distância geoespacial. Isso é feito usando uma cláusula COLUMNS nativa do GQL, calculando a distância geodésica de forma nativa dentro da correspondência de travessia do gráfico:

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;

Ao combinar funções nativas geoespaciais (GIS) (ST_DISTANCE, ST_GEOGPOINT) com uma correspondência de gráfico de propriedades do GQL, o BigQuery resolve dinamicamente a presença operacional do sindicato e calcula a proximidade física no mundo real em uma única consulta.

Verificação de status:

• O que conseguimos: usamos a análise de conversas para rastrear os portos de atracação da frota do operador fantasma (Manifest ➔ Vessel ➔ Company ➔ Docks) e calculamos que a embarcação suspeita está indo diretamente para o Terminal de Mountain View (a apenas 39 km de distância).
• O que precisamos fazer agora: encontre o registro de dados que contém o código de substituição manual para que nossa equipe de intervenção tática local possa interceptar o envio e desbloquear manualmente o contêiner quando ele atracar no terminal de Mountain View.

7. Encontrar dados ausentes com o Knowledge Catalog

O gráfico de propriedades mostra relacionamentos, mas não contém a tabela em que os códigos de substituição reais são armazenados.

Em um ambiente empresarial real com centenas de conjuntos de dados e tabelas, encontrar essas informações pode ser difícil. Vamos usar o Knowledge Catalog para fazer uma pesquisa semântica e localizar a tabela correta.

1. Pesquisa semântica no Knowledge Catalog

1. No console do Google Cloud, pesquise e acesse Knowledge Catalog ➔ Pesquisar.
2. Na coluna de filtro de pesquisa em Sistemas, marque BigQuery para restringir os resultados.
3. Na caixa de pesquisa, insira a seguinte consulta:

   container override codes
   

4. Clique no recurso de tabela maritime_security_registry que aparece nos resultados da pesquisa:

Ao inspecionar o esquema de metadados, você vai notar que a tabela tem colunas para dados de segurança do contêiner, como a empresa coordenadora co_id, o token de custodiante cust_tok e, mais importante, a coluna de senha de substituição do contêiner seguro: clc_ovr_cd.

Localizamos a mesa e a coluna segura exata que precisamos para recuperar nossa carga!

Por dentro: correspondência semântica: o nome da tabela (maritime_security_registry) e o nome da coluna de chave (clc_ovr_cd) são completamente obscuros. Sem a análise da pesquisa semântica do Knowledge Catalog na descrição da coluna ("Senha de substituição de contêiner seguro"), seria quase impossível encontrar essa tabela pesquisando "códigos de substituição".

🔓 Governança no mundo real: em um ambiente empresarial de produção, as equipes de segurança e governança também usam:

• Aspectos e modelos de tag: para anexar metadados comerciais (como Proprietário dos dados, Período de retenção ou Classificação de PII) a esquemas de tabela.
• Linhagem de dados: para gerar automaticamente fluxogramas visuais que representam como tabelas como maritime_security_registry são consultadas e consumidas por sistemas downstream.

2. Inspecionar a segurança da coluna no BigQuery

1. Volte ao console do BigQuery.
2. Na guia Explorer, selecione lost_cargo_dataset e clique na tabela maritime_security_registry.
3. Clique na guia Esquema.

4. A coluna clc_ovr_cd é protegida por uma tag de política chamada MaskShippingDetails (listada na coluna "Tags de política").
5. Abra uma nova guia do editor de SQL no BigQuery e tente ver os códigos de substituição do registro executando a seguinte consulta:

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

6. Como sua conta ainda não tem permissões para ler colunas marcadas com MaskShippingDetails, a consulta vai falhar imediatamente com um erro de segurança do banco de dados Acesso negado:

Verificação de status:

• O que conseguimos: encontramos a tabela (maritime_security_registry) e a coluna (clc_ovr_cd) seguras que contêm o código de substituição.
• O que fazer agora: conceda à sua conta permissões de leitura para a coluna protegida.

8. Como burlar a segurança de colunas para recuperar a senha

Para ler o código de substituição final em texto simples, precisamos conceder à nossa conta de usuário permissão para ler colunas marcadas com MaskShippingDetails.

1. Conceder permissões de tag de política

1. No painel de navegação à esquerda do console do BigQuery, acesse Tags de política.
2. Selecione a taxonomia chamada LostCargoSecurity_.
3. Na lista de tags, clique em MaskShippingDetails.
4. No painel de informações à direita da tela, clique em Adicionar participante. Se o painel estiver oculto, clique em Mostrar painel de informações no canto superior direito.
5. No campo Novos principais, digite seu e-mail de usuário ativo do Google Cloud.
6. No menu suspenso Selecionar um papel, pesquise e selecione Leitor refinado e clique em Salvar.

2. Consulta do código de substituição

Volte ao editor do espaço de trabalho do BigQuery. Como agora você tem acesso de leitura refinado, podemos executar a consulta novamente e ver os dados não mascarados:

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

🔓 Resultado

A consulta retorna o código de substituição não mascarado:

SHIVER-ME-TIMBERS-888

Missão cumprida! 🚢

Parabéns! Ao combinar gráficos de propriedades do BigQuery e análise de conversas com o Knowledge Catalog e a segurança no nível da coluna, você rastreou a frota fantasma e extraiu o código de substituição do contêiner seguro.

A equipe de interceptação tática foi enviada ao Terminal de Mountain View. Com o código de substituição descriptografado, eles estão prontos para desbloquear o contêiner de capivara, proteger a carga e recuperar os recursos perdidos.

9. Limpar

Para evitar cobranças, limpe os recursos da sandbox criados durante este laboratório.

Volte ao terminal do Cloud Shell e exclua o conjunto de dados do BigQuery que contém as tabelas de logística:

bq rm -r -f -d lost_cargo_dataset

Remova os arquivos do repositório clonado:

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

10. Parabéns

Você resolveu a investigação e recuperou o código de substituição de autorização.

O que você aprendeu

• Como criar um gráfico de propriedades no BigQuery para representar entidades e relacionamentos complexos.
• Como nós, arestas, propriedades e rótulos são configurados para capturar conexões de dados.
• Como consultar gráficos de propriedades usando linguagem natural com a Análise conversacional do BigQuery.
• Como as expressões da linguagem de consulta de gráficos (GQL) são estruturadas para percorrer caminhos relacionais.
• Como descobrir recursos protegidos usando o Knowledge Catalog e acessar dados restritos no nível da coluna usando tags de política.

Links de recursos

• Visão geral da Análise Conversacional no BigQuery
• Referência de sintaxe de gráficos de propriedades do BigQuery
• Integração do Knowledge Catalog