实验 3：使用 BigQuery 图和对话式分析功能发现丢失的货物

1. 简介

欢迎来到“丢失的货物”调查的最后阶段！在追踪从伦敦到悉尼的被盗 Android 小雕像集装箱后，线索中断了。通过停用应答器，集装箱的智能安全保险库触发了自动紧急锁定 。

为了在贵重货物被永久锁定之前找回它们，您的任务是找到集装箱的最终位置并检索手动替换密码，以便通过物理方式解锁保险库。

丢失的货物实验 3 对话式分析架构预览

为了找到丢失的集装箱并确保货物安全，您将构建 BigQuery 属性图 来追踪货物的运输过程。然后，您将使用对话式分析 以自然语言查询此网络，最后使用 Knowledge Catalog 对数据的元数据执行语义搜索，以找到替换代码。

💡 错过了 实验 1 或 实验 2？不用担心！此实验完全独立。环境设置步骤将预配您所需的一切，因此您可以直接开始并独立完成实验。

您将执行的操作

  • 克隆代码库并在 Google Cloud Shell 中运行设置脚本。
  • 在 BigQuery 中**构建属性图**，将公司、船只和清单数据关联起来。
  • 使用对话式分析 以自然语言查询图表，追踪货物的运输过程，以确定负责的运营商。
  • 找到包含最终替换代码的表 使用 Knowledge Catalog。
  • 使用 BigQuery 列级访问权限控制 来取消遮盖并显示最终代码。

所需条件

  • 网络浏览器，例如 Chrome
  • 启用了结算功能的 Google Cloud 项目
  • 能够访问 Google Cloud Shell

此 Codelab 专为各种级别的数据从业者设计。

在此 Codelab 中创建的资源费用应低于 5 美元。

预计时长： 完成此 Codelab 大约需要 45 分钟。

2. 准备工作

创建 Google Cloud 项目

  1. 在 Google Cloud 控制台 的项目选择器页面上，选择或创建一个 Google Cloud 项目。
  2. 确保您的 Cloud 项目已启用结算功能。

启动 Cloud Shell

您将使用 Google Cloud Shell 下载代码、运行设置脚本和部署应用。

  1. 在新浏览器标签页中，打开 Cloud Shell：

激活 Cloud Shell

  1. 连接后，设置您的项目 ID 并确认您的环境：
gcloud config set project <<YOUR_PROJECT_ID>>
export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1

您应会看到如下所示的消息：

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

启用必需的 API

在 Cloud Shell 中运行以下命令以启用必需的 API：

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

成功执行后，您应会看到如下所示的消息：

Operation "operations/..." finished successfully.

3. 设置您的环境

在本系列的前几个实验中，我们为调查奠定了基础。

1. 克隆代码库

将 Codelab 代码库克隆到 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. 设置基本表和政策标记

运行设置脚本以填充 BigQuery 数据集，并应用列级安全标记来限制敏感数据：

bash setup_lab.sh

确认终端中的输出显示初始化成功：

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

环境设置成功，物流数据已填充 BigQuery，现在您可以构建属性图来关联表并追踪货物的运输过程！

4. 使用 BigQuery 图表关联数据

为了分析供应链数据，我们将定义公司、船只和清单之间的关系。构建属性图可让我们轻松查询这些关联。

1. 属性图如何对关系进行建模

属性图表编译的架构图

BigQuery 属性图使用以下元素对网络进行建模：

  • 节点：网络中的实体。在此实验中，节点表示公司 （直接存储联系方式）、清单 和船只 。
  • 边：将节点关联在一起的关系。例如：
    • 边将清单 连接到船只 （通过 manifests 表中的关系）。
    • 边将船只 连接到公司 （通过 vessels 表中的关系）。
  • 属性：存储在节点或边上的元数据。例如，公司 节点具有 company_name 和 phone_number 等列，而清单 节点具有 seal_integrity_status 和坐标 (last_ping_lat、last_ping_long)。
  • 标签：分配给节点（例如 Company、Vessel、Manifest）和边（例如 CARRIED_BY、OPERATED_BY）的标记名称，以便查询工具可以识别节点和关系类型。

2. 在 BigQuery 中部署属性图

setup_graph.sql 文件包含用于定义和创建属性图的 SQL DDL，但目前尚不完整。您需要在编译和部署此架构文件之前定义边标签（关系）：

  1. 打开 Cloud Shell 编辑器。

打开 Cloud Shell Editor

  1. 在 Cloud Shell 编辑器中打开文件 setup_graph.sql。

图表创建 SQL

  1. 找到边标签的占位符：
    • 第 22 行：将 `EDGE_TABLE_PLACEHOLDER` 替换为有意义的标记，表示清单与船只之间的关系（例如 CARRIED_BY）。
    • 第 27 行：将 `EDGE_TABLE_PLACEHOLDER` 替换为表示船只与公司之间关系的标记（例如 OPERATED_BY）。
  2. 保存文件。

现在，返回 Cloud Shell 终端并使用已完成的脚本部署更新后的属性图：

bq query --use_legacy_sql=false < setup_graph.sql

您应会看到输出，表明作业已完成：

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

您可以在 BigQuery 控制台 中查看属性图详细信息：

找到 lost_cargo_dataset 并选择“图表”：

属性图表编译的架构图

属性图编译成功后，让我们深入了解 BigQuery Studio，查询并直观呈现关联！

5. 查询图表

您可以使用 BigQuery Studio 内的原生 Graph Query Language (GQL) 以直观方式查询和探索图表。

1. 查询集装箱 -> 船只 -> 公司链

让我们通过查找运营运输货物的船只的人员来探索 GQL 查询。查找运营商需要在物流网络中遍历三个单独的实体节点：

图节点概念

  1. 从集装箱 Manifest 节点开始。
  2. 按照 CARRIED_BY 关系边查找运输 Vessel 。
  3. 按照该船只的 OPERATED_BY 关系边查找负责的 Company 并检索其 ID。

首先，我们运行查询以直观呈现整个 网络（没有任何过滤条件），以查看完整图表。

  1. 在 BigQuery Studio SQL 编辑器中打开一个新标签页，粘贴以下 GQL 查询，然后点击 运行：
    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. 查询完成后，在底部的查询结果 窗格中，点击图表 标签页（位于结果表 标签页旁边）。

BigQuery 图结果 1

  1. BigQuery 会将结果呈现为交互式可视化图表！放大以查看关联的集装箱、船只和运营商的完整网络。

GQL 查询的剖析

让我们分解一下刚刚运行的 GQL 查询：

  • GRAPH_TABLE：指示 BigQuery 对 logistics_network 图表执行属性图查询。
  • MATCH：声明多跳遍历模式。我们从 Manifest (m) 开始，匹配指向 Vessel (v) 的边关系 :CARRIED_BY，然后匹配指向 Company (comp) 的边关系 :OPERATED_BY。
  • GQL 使用直观且人类可读的 ASCII 艺术关系箭头 ()->[]->() 替换复杂的联接逻辑，从而使编写和优化多跳查询变得非常简单。
  • RETURN：从匹配的元素返回属性或 JSON 路径。

2. 过滤 GQL 查询结果

现在，让我们过滤查询，以便仅查看目标受损集装箱 MV-CAPYBARA-003 的路径。

  1. 将以下查询粘贴到 SQL 编辑器中，然后点击运行：
    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. 点击结果下的图表 标签页。

BigQuery 图结果 2

  1. 查看器现在仅显示 MV-CAPYBARA-003 的活跃遍历路线。放大以查看节点和关联：
    • 双击 Company 节点以打开属性面板。在属性 下，您将看到运营商 company_id：103 (Davy Jones Shipping)。记下此公司 ID，您稍后需要使用它从安全注册表中检索清关密码！
    • 双击 Vessel 节点以验证它是否为 Flying Dutchman 。

6. 使用对话式分析与图表对话

现在您已手动查询图表以查找公司 ID，接下来让我们使用对话式分析直接与图表对话，并确定集装箱的航向。

1. 启动对话式分析会话

  1. 在 Google Cloud 控制台中，前往 BigQuery 控制台，然后展开资源面板以找到数据集 (lost_cargo_dataset)。
  2. 点击属性图资源：logistics_network 。
  3. 在顶部的详细信息面板工具栏中，点击聊天 按钮。这会打开一个对话式分析会话，其中预加载了图表的上下文。

BigQuery Data Agent 配置界面，用于关联已编译的属性图来源

2. 确定被劫持集装箱的最近停靠港

一架海上巡逻机刚刚发现一艘船只，其描述与我们的货船相符，该船只在坐标 POINT(-122.48 37.55) 处脱离网格航行（应答器已停用）。为了拦截货物，我们需要找到 Davy Jones Shipping 影子集团运营的最近停靠港 。

我们将查询图表网络，而不是手动搜索所有全球港口，以提取与该集团的活跃舰队关联的港口，并衡量哪个港口在物理上最接近观测点！

  1. 在对话式分析聊天框中，输入以下提示：
    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.

BigQuery Data Agent 配置界面，用于关联已编译的属性图来源

  1. 仔细查看响应。智能体会遍历图表并返回最近的停靠设施及其距离：
    • 停靠港: Mountain View Terminal
    • 距离: 39.42 kilometers
  2. 由于对话式分析由 Gemini 提供支持，并具有原生地理空间 (GIS) 集成，因此它可以解读地理坐标点并利用其世界知识来验证位置："该船只距离加利福尼亚州山景城终端大约 39.42 公里 ，表明它正前往该终端停靠。"

这证实了我们的货物正直接前往山景城！

幕后：Graph Query Language (GQL) 和地理空间 GIS

在幕后，对话式分析智能体动态编译并执行了一个查询，该查询将图表路径匹配与地理空间距离计算相结合。这是通过使用原生 GQL COLUMNS 子句实现的，该子句在图表遍历匹配中原生计算测地距离：

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;

通过将原生地理空间 (GIS) 函数（ST_DISTANCE、ST_GEOGPOINT）与 GQL 属性图匹配 相结合，BigQuery 可以动态解析该集团的运营足迹，并在单个查询中计算现实世界中的物理邻近度！

7. 使用 Knowledge Catalog 查找丢失的数据

属性图显示了关系，但不包含存储实际替换代码的表。

在拥有数百个数据集和表的真实企业环境中，查找此信息可能很困难。我们将使用 Knowledge Catalog 执行语义搜索并找到正确的表。

1. Knowledge Catalog 中的语义搜索

  1. 在 Google Cloud 控制台 中，搜索并前往 Knowledge Catalog ➔ 搜索 。
  2. 在系统下的搜索过滤列中，选中BigQuery以缩小结果范围。
  3. 在搜索框中，输入以下查询：
    container override codes

Knowledge Catalog 语义搜索界面，用于查找隔离的实体印章表

  1. 点击搜索结果中显示的 maritime_security_registry 表资源：

检查元数据架构后，您将看到该表包含集装箱安全数据的列，例如协调公司 co_id、保管人令牌 cust_tok，以及最重要的安全集装箱替换密码列：clc_ovr_cd。

我们已成功找到表和恢复货物所需的准确安全列！

🔓 真实世界治理：在生产企业环境中，安全和治理团队还会利用：

  • 切面和标记模板：将业务元数据（例如 数据所有者、保留期限或 PII 分类）附加到表架构。
  • 数据沿袭：自动生成可视化流程图，表示下游系统如何查询和使用 maritime_security_registry 等表。

2. 在 BigQuery 中检查列安全性

  1. 返回 BigQuery 控制台 。
  2. 在 Explorer 标签页中，选择 lost_cargo_dataset ，然后点击 maritime_security_registry 表。
  3. 点击架构 标签页。

显示分配给 clc_ovr_cd 列的政策标记的表架构视图

  1. 请注意，clc_ovr_cd 列受名为 MaskShippingDetails 的政策标记保护（列在“政策标记”列中）。
  2. 在 BigQuery 中打开一个新的 SQL 编辑器标签页，然后运行以下查询，尝试查看注册表替换代码：
    SELECT * FROM `lost_cargo_dataset.maritime_security_registry` 
WHERE co_id = 103;
  3. 由于您的账号尚未获得读取带有 MaskShippingDetails 标记的列的权限，因此查询将立即失败，并显示访问遭拒 数据库安全错误：

输出标准列级遮盖或访问拒绝限制的 BigQuery 工作区视图

8. 破解列安全性以检索密码

如需以明文形式读取最终替换代码，我们需要授予用户账号读取带有 MaskShippingDetails 标记的列的权限。

1. 授予政策标记权限

  1. 在 BigQuery 控制台左侧导航窗格中，前往政策标记 。
  2. 选择名为 LostCargoSecurity_ 的分类法。
  3. 在标记列表中，点击 MaskShippingDetails 。
  4. 在屏幕右侧的信息面板 中，点击添加主账号 。（如果面板处于隐藏状态，请点击右上角的显示信息面板 ）。
  5. 在新建主账号 字段中，输入您的活跃 Google Cloud 用户电子邮件地址。
  6. 在选择角色 下拉列表中，搜索并选择 Fine-Grained Reader ，然后点击保存 。

BigQuery 政策标记管理面板，用于在目标字符串掩码上分配 Fine-Grained Reader 角色

2. 查询替换代码

返回 BigQuery 工作区编辑器。由于您现在拥有精细读取器访问权限，因此我们应该能够再次运行查询并查看未遮盖的数据：

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

🔓 结果

查询返回未遮盖的替换代码：

SHIVER-ME-TIMBERS-888

BigQuery 工作区执行结果，返回未屏蔽的确定性字符串标志

9. 清理

为避免产生费用，请清理在此实验期间创建的沙盒资源。

返回 Cloud Shell 终端并删除包含物流表的 BigQuery 数据集 ：

bq rm -r -f -d lost_cargo_dataset

移除克隆的代码库文件：

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

10. 恭喜

您已成功完成调查并检索到清关替换代码！

您学到的内容

  • 如何在 BigQuery 中构建属性图以表示复杂的实体和关系。
  • 如何配置节点、边、属性和标签以捕获数据关联。
  • 如何使用 BigQuery 对话式分析 以自然语言查询属性图。
  • 如何构建 Graph Query Language (GQL) 表达式以遍历关系路径。
  • 如何使用 Knowledge Catalog 发现受保护的资产，以及如何使用政策标记访问列级受限数据。