生成数据集洞察

本文档介绍如何为 BigQuery 数据集和 Apache Iceberg 命名空间（在 BigQuery 中表示为数据集）生成数据集洞察。数据集洞察通过生成关系图和跨表查询，帮助您了解数据集或命名空间中表之间的关系。

数据集洞察通过以下方式帮助您加快探索包含多个表的数据集和命名空间：自动发现表之间的关系并在图表中直观呈现，识别主键和外键关系，以及生成示例跨表查询。这有助于您在没有文档的情况下了解数据结构，发现表之间架构定义的关系、基于使用情况的关系或 AI 推断的关系，以及生成联接多个表的复杂查询。

如需大致了解表和数据集洞察，请参阅 数据洞察概览。

生成数据集洞察的模式

生成数据集洞察时，BigQuery 提供两种模式：

模式	说明	用法
生成并发布	将生成的数据集洞察作为元数据切面和 关系持久保存到 Knowledge Catalog 中。您必须拥有发布所需的权限。当您使用 生成并发布 时，BigQuery 会执行以下操作： 将数据集说明存储在 Knowledge Catalog 中。 将建议的查询和问题捕获为可重复使用的 切面。 将关系捕获为 Knowledge Catalog 中的元数据。 让具有相应 Knowledge Catalog 访问权限的用户查看已发布的 洞察，从而确保组织知识共享。 让您使用 API 直接在 Knowledge Catalog 中修改和保存说明。您可以使用 修改建议的查询。 Google Cloud 控制台。	将此模式用于持久 且可重复使用的企业级数据文档，或用于构建目录驱动的治理 工作流。
生成但不发布	按需创建数据集洞察，例如说明、自然语言 问题、关系和 SQL 查询。 生成但不发布 不会将洞察发布到 Knowledge Catalog。	将此模式用于快速的临时探索，以避免目录杂乱。

准备工作

数据洞察是使用 Gemini in BigQuery生成的。 如需开始生成数据洞察，您必须先设置 Gemini in BigQuery。

注意：Gemini in BigQuery 是 Gemini for Google Cloud 的一部分，它提供的合规性和安全性保证与 BigQuery 不同。只有当 BigQuery 项目不需要 Gemini for 不支持的合规性服务 Google Cloud时，才应设置 Gemini in BigQuery 。 如需了解如何停用或禁止访问 Gemini in BigQuery，请参阅 停用 Gemini in BigQuery。

启用 API

重要提示：如需在项目中启用任何 API，请让您的管理员向您授予项目的 serviceusage.services.enable 权限。

如需使用数据分析洞见，请在项目中启用以下 API：Dataplex API、BigQuery API 和 Gemini for Google Cloud API。

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您 创建了项目，则可能已通过 所有者角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获取此权限。 了解如何授予角色。

启用 API

如需详细了解如何启用 Gemini for Google Cloud API，请参阅 在项目中启用 Gemini for Google Cloud API Google Cloud 。

完成数据分析扫描

如需提高洞察的质量，请为数据集中的表生成 数据分析扫描 。

所需的角色

如需获得生成、管理和检索数据集洞察所需的权限，请让您的管理员为您授予以下 IAM 角色：

• 如需生成、管理和检索洞察，请执行以下操作：
  • 针对项目的 Dataplex DataScan Editor (roles/dataplex.dataScanEditor) 或 Dataplex DataScan Administrator (roles/dataplex.dataScanAdmin) 角色
  • BigQuery Data Editor (roles/bigquery.dataEditor) 针对表的角色
  • 针对项目的 BigQuery User (roles/bigquery.user) 或 BigQuery Studio User (roles/bigquery.studioUser) 角色
  • BigQuery Resource Viewer (roles/bigquery.resourceViewer) 针对项目的角色
• 如需查看洞察，请执行以下操作：
  • Dataplex DataScan DataViewer (roles/dataplex.dataScanDataViewer) 针对项目的角色
  • BigQuery Data Viewer (roles/bigquery.dataViewer) 针对数据集
• 如需将洞察发布到 Knowledge Catalog: Dataplex Entry and EntryLink Owner (roles/dataplex.entryOwner) 针对条目组

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义 角色或其他预定义 角色来获取所需的权限。

如需查看生成洞察所需的确切权限，请展开所需权限 部分：

所需权限

• bigquery.datasets.get：读取数据集元数据
• bigquery.jobs.create：创建作业
• bigquery.jobs.listAll：列出项目中的所有作业
• bigquery.tables.get：获取表元数据
• bigquery.tables.getData：获取表数据和元数据
• dataplex.datascans.create：创建数据扫描资源
• dataplex.datascans.get：读取数据扫描资源元数据
• dataplex.datascans.getData：读取数据扫描执行结果
• dataplex.datascans.run：运行按需数据扫描
• dataplex.entryGroups.useSchemaJoinEntryLink：使用 schema-join 条目链接
• dataplex.entryGroups.useSchemaJoinAspect：使用架构联接切面
• dataplex.entryLinks.create：创建条目链接
• dataplex.entryLinks.update：更新条目链接
• dataplex.entryLinks.delete：删除条目链接
• dataplex.entries.link：链接条目
• dataplex.entries.update：更新条目
• dataplex.entryGroups.useDescriptionsAspect：使用说明切面
• dataplex.entryGroups.useQueriesAspect：使用查询切面

生成数据集洞察

控制台

1. 在 Google Cloud 控制台中，前往 BigQuery Studio。

   进入 BigQuery Studio

2. 在探索器 窗格中，选择要为其生成洞察的项目和数据集。对于 Iceberg 命名空间，请选择代表目录命名空间的数据集。

3. 点击洞察 标签页。

4. 如需生成洞察并将其发布到 Knowledge Catalog，请点击生成并发布 。

   如需生成洞察但不将其发布到 Knowledge Catalog，请点击生成但不发布 。

   如需详细了解 生成并发布 模式与 生成但不发布 模式之间的区别，请参阅 生成数据集洞察的模式。

5. 如果您的数据集位于多区域中，系统可能会提示您选择一个区域来生成洞察。选择与要创建洞察扫描的多区域相对应的区域。

   洞察需要几分钟才能填充完毕。如果数据集中的表具有 数据分析结果，则洞察的 质量会提高。

生成洞察后，BigQuery 会显示数据集说明、关系图、关系表和示例跨表查询。

REST

如需以编程方式生成洞察，请使用 Knowledge Catalog DataScans API。 为此，请完成以下步骤：

1. 为 BigQuery 数据集生成数据文档数据扫描
2. 检查数据文档扫描状态
3. 验证是否发布到 Knowledge Catalog

为 BigQuery 数据集生成数据文档数据扫描

1. 使用 dataScans.create 方法创建数据文档数据扫描。 您可以选择性地通过将 catalog_publishing_enabled 参数设置为 true，将这些洞察发布到 Knowledge Catalog。

   例如：

   alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'
   gcurl -X POST \
   https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
   dataScans?dataScanId=DATASCAN_ID \
   -d '{
     "data": {
       "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID"
     },
     "executionSpec": {
       "trigger": { "onDemand": {} }
     },
     "type": "DATA_DOCUMENTATION",
     "dataDocumentationSpec": {
       "catalog_publishing_enabled": true
     }
   }'
   

   替换以下内容：

   • PROJECT_ID：数据集所在 Google Cloud 项目的 ID
   • LOCATION：运行数据扫描的区域
   • DATASCAN_ID：您为此扫描提供的唯一名称
   • DATASET_ID：要扫描的 BigQuery 数据集的 ID

2. 使用 dataScans.run 方法启动数据文档扫描作业。

   例如：

   gcurl -X POST \
   https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
   dataScans/DATASCAN_ID:run
   

   此请求会返回唯一的作业 ID 以及初始状态。

检查数据文档扫描状态

使用 dataScans.get 方法检查扫描作业运行是否完成。 如需检索完整结果（包括洞察和发布状态），请将 view 参数设置为 FULL。

使用作业 ID 获取作业的状态。例如：

gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans/DATASCAN_ID/jobs/JOB_ID?view=FULL

当状态为 SUCCEEDED 或 FAILURE 时，作业即完成。

成功的作业响应会在 dataDocumentationResult 字段中包含生成的分析洞见。

验证是否发布到 Knowledge Catalog

如果 catalog_publishing_enabled 设置为 true，则在数据扫描作业完成后，洞察会异步发布到 Knowledge Catalog。如需验证洞察是否已持久保存，请使用 Dataplex API 检查数据集的切面。

虽然洞察是从数据集级数据扫描生成的，但生成的条目链接存储在它们连接的表之间。如需验证这些 关系，请使用 lookupEntryLinks方法 检索与特定表条目关联的条目链接。

如需检索 BigQuery 数据集的元数据，请使用 entries.get 方法。 如需包含所有切面，请将 view 参数设置为 FULL。例如：

gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/DATASET_PROJECT_ID/datasets/DATASET_ID?view=FULL

替换以下内容：

• PROJECT_ID：配置数据扫描的 Google Cloud 项目 ID
• LOCATION：条目组所在的区域
• DATASET_PROJECT_ID：BigQuery 数据集所在 Google Cloud 项目的 ID
• DATASET：BigQuery 数据集的 ID

注意： BigQuery 的条目组始终为 @bigquery。网址中 entries/ 后面的部分是 BigQuery 资源的完全限定名称，Knowledge Catalog 将其用作唯一标识符。

如果成功发布到 Knowledge Catalog，则以下切面会附加到 BigQuery 数据集：

• Descriptions：包含 AI 生成的数据集说明
• Queries：包含与数据集相关的 SQL 查询
• Relationships：持久保存为数据集中的表之间的条目链接

查看并保存数据集说明

Gemini 会生成数据集的自然语言说明，总结其中包含的表类型及其代表的业务领域。如需将此说明保存到数据集的元数据中，请点击保存到详细信息 。

您可以在保存详细信息之前修改说明。

探索关系图

关系 图直观呈现了数据集中的表之间的关系。它将连接最多的前 10 个表显示为节点，并使用线条表示它们之间的关系。

• 如需查看关系详细信息（例如联接两个表的列），请将鼠标悬停在连接表节点的边上。
• 如需重新排列图表以提高可见性，请拖动表节点。

使用关系表

关系表 以表格格式列出了发现的关系。每一行代表两个表之间的关系，显示源表和列以及目标表和列。来源 列指示关系的确定方式：

• LLM 推断。Gemini 根据数据集中的表和列名称及说明推断出的关系。
• 基于使用情况。根据频繁联接从查询日志中提取的关系。
• 架构定义。从表架构中现有的主键和外键映射派生的关系。

您可以针对特定表过滤关系，或针对检测到的关系的质量提供反馈。如需将生成的数据集说明和关系导出到 JSON 文件，请点击导出到 JSON 。

使用查询建议

Gemini 会根据发现的关系生成示例查询。这些是自然语言问题，其中包含联接数据集中的多个表的相应 SQL 查询。

1. 如需查看 SQL 查询，请点击问题。

2. 如需在 BigQuery 查询编辑器中打开查询，请点击复制到查询 。然后，您可以运行或修改查询。

3. 如需提出后续问题，请点击提出后续问题，系统会打开一个 无标题的数据画布，您可以在其中与 Gemini 聊天以探索 数据。

管理生成的分析洞见

为数据集生成洞察后，您可以在 Knowledge Catalog 中管理、更新或删除这些洞察。 如需了解详情，请参阅 管理数据集洞察。

后续步骤

• 了解数据洞察概览。
• 了解如何生成表洞察。
• 详细了解 Knowledge Catalog 数据分析。