生成表格数据分析

本文档介绍了如何为 BigQuery 表、BigLake 表和外部表生成表数据分析。表格分析洞见可根据表格元数据生成自然语言问题和 SQL 查询，帮助您了解单个表格中的数据。

借助表格数据洞见，您可以快速了解新表格或不熟悉的表格的结构和内容，而无需编写复杂的查询，从而加快数据探索速度。您还可以根据自然语言问题生成 SQL 查询，从而减少手动编写查询所需的时间和精力。表格洞见还可以帮助非 SQL 用户通过这些自然语言查询来理解和分析数据。

如需了解表和数据集分析洞见，请参阅数据分析洞见概览。

生成表格数据分析洞见的模式

在生成表格分析洞见时，BigQuery 提供两种模式：

模式	说明	用法
生成并发布（预览版）	将生成的表分析洞见作为元数据切面持久保存到 Dataplex Universal Catalog 中。您必须拥有发布所需的权限。当您使用生成并发布时，系统会执行以下操作：将表和列说明存储在 Dataplex Universal Catalog 中。将建议的查询和问题捕获为可重用的方面。使发布的分析洞见可供所有具有相应 Dataplex Universal Catalog 访问权限的用户访问，从而确保组织知识共享。让您直接在 Dataplex Universal Catalog 中修改和保存说明。	此模式适用于持久且可重用的企业级数据文档，或在构建目录驱动型治理工作流时使用。
生成但不发布	按需创建表格分析洞见，例如说明、自然语言问题和 SQL 查询。生成但不发布不会将分析洞见发布到 Dataplex Universal Catalog。	使用此模式可进行快速的临时探索，避免使目录杂乱无章。

模式

说明

用法

生成并发布（预览版）

将生成的表分析洞见作为元数据切面持久保存到 Dataplex Universal Catalog 中。您必须拥有发布所需的权限。当您使用生成并发布时，系统会执行以下操作：

将表和列说明存储在 Dataplex Universal Catalog 中。
将建议的查询和问题捕获为可重用的方面。
使发布的分析洞见可供所有具有相应 Dataplex Universal Catalog 访问权限的用户访问，从而确保组织知识共享。
让您直接在 Dataplex Universal Catalog 中修改和保存说明。

此模式适用于持久且可重用的企业级数据文档，或在构建目录驱动型治理工作流时使用。

生成但不发布

按需创建表格分析洞见，例如说明、自然语言问题和 SQL 查询。生成但不发布不会将分析洞见发布到 Dataplex Universal Catalog。

使用此模式可进行快速的临时探索，避免使目录杂乱无章。

准备工作

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

启用 API

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

角色与权限

如需创建、管理和检索数据分析，请让您的管理员向您授予以下 Identity and Access Management (IAM) 角色：

针对您要生成数据分析的项目的 Dataplex Universal Catalog DataScan Editor (roles/dataplex.dataScanEditor) 或 Dataplex Universal Catalog DataScan Administrator (roles/dataplex.dataScanAdmin) 角色。
针对您要为其生成数据分析的 BigQuery 表的 BigQuery Data Viewer (roles/bigquery.dataViewer) 角色。
针对您要为其生成数据洞察的 BigQuery 表的 BigQuery Data Viewer (roles/bigquery.dataEditor) 角色。
针对您要在其中生成数据洞察的项目的 BigQuery User (roles/bigquery.user) 或 BigQuery Studio User (roles/bigquery.studioUser) 角色。

如需获得对生成的数据分析的只读访问权限，请让您的管理员向您授予以下 IAM 角色：

针对您要查看其数据分析的 BigQuery 表所在项目的 Dataplex Universal Catalog DataScan DataViewer (roles/dataplex.dataScanDataViewer) 角色。

如需将数据分析洞见发布到 Dataplex Universal Catalog，请让您的管理员向您授予资源的以下 IAM 角色：

将说明发布为切面：Dataplex Universal Catalog Catalog Editor (roles/dataplex.catalogEditor)
将查询发布为切面：Dataplex Universal Catalog Entry and EntryLink Owner (roles/dataplex.entryOwner)

如需启用 API，请让您的管理员为您授予以下 IAM 角色：

您要生成分析洞见的项目的 Service Usage Admin (roles/serviceusage.serviceUsageAdmin)。

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

您也可以通过自定义角色或其他预定义角色来获取所需的权限。如需查看生成数据洞察所需的确切权限，请展开所需权限部分：

所需权限

bigquery.jobs.create
bigquery.tables.get
bigquery.tables.getData
dataplex.datascans.create
dataplex.datascans.get
dataplex.datascans.getData
dataplex.datascans.run

为 BigQuery 表生成数据分析

如需为 BigQuery 表生成分析洞见，您可以使用Google Cloud 控制台或 Dataplex Universal Catalog DataScans API 支持的 DATA_DOCUMENTATION 扫描类型。这些扫描会生成元数据、用于数据探索的 SQL 查询、架构说明和表级摘要。

控制台

如需为 BigQuery 表生成数据洞察，您必须使用 BigQuery Studio 在 BigQuery 中访问表条目。

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

进入 BigQuery Studio
在探索器窗格中，依次选择项目、数据集和要为其生成数据分析的表。
点击数据分析标签页。如果该标签页为空，则表示此表的数据分析尚未生成。
如需生成分析洞见并将其发布到 Dataplex Universal Catalog，请点击生成并发布（预览版）。

如需生成分析洞见但不将其发布到 Dataplex Universal Catalog，请点击生成但不发布。

如需详细了解生成并发布模式与生成但不发布模式之间的区别，请参阅生成分析洞见的模式。
选择一个区域以生成分析洞见，然后点击生成。

数据洞察需要几分钟才能填充完毕。

如果可使用表的已发布数据分析结果，则系统会使用这些内容生成数据洞察。否则，系统会根据列名称和说明生成数据洞察。如需了解详情，请参阅改进生成的数据洞察的最佳实践。
在数据分析标签页中，浏览生成的自然语言问题。
如需查看用于回答问题的 SQL 查询，请点击相应问题。
如需在 BigQuery 中打开查询，请点击复制到查询。
如需提问后续问题，请执行以下操作：
1. 点击接着提问。查询会在新的数据画布中打开。
2. 点击运行，然后点击查询这些结果。
3. 如需提出后续问题，请在自然语言提示字段中输入提示，或在查询编辑器中修改 SQL。
如需生成一组新查询，请点击生成数据分析并再次触发流水线。

为表生成数据洞察后，拥有 dataplex.datascans.getData 权限且可以访问表的任何人都可以查看这些数据洞察。

REST

如需以编程方式生成分析洞见，请使用 Dataplex Universal Catalog DataScans API。为此，请完成以下步骤：

可选：为表创建数据分析扫描
为 BigQuery 表生成数据文档数据扫描
检查数据文档扫描状态
将数据文档扫描结果发布到 BigQuery 表

可选：为表创建数据分析扫描

数据分析扫描的存在可减少 Gemini 的认知错误和近似值，因为它们会将输出结果基于数据中存在的实际值。

如需创建并运行数据分析扫描，请按以下步骤操作：

使用 dataScans.create 方法创建数据分析扫描。
使用 dataScans.run 方法运行数据分析扫描。等待运行完成。
通过将以下数据分析标签附加到 BigQuery 表，将扫描结果发布到该表：
- dataplex-dp-published-scan:DATASCAN_ID
- dataplex-dp-published-project:PROJECT_ID
- dataplex-dp-published-location:LOCATION
如需了解详情，请参阅向表和视图添加标签。

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

您可以选择运行标准受管扫描，也可以选择运行简化的单次扫描。

方法 A：标准受管扫描（创建 + 运行）

如果您想随时间推移管理扫描资源，请使用此方法。

使用 dataScans.create 方法创建数据文档数据扫描。您可以使用 generation_scopes 参数自定义生成范围，以包含架构、说明、查询或它们的组合：

如需生成架构、表说明和 SQL 查询，请将 data_documentation_spec 留空或将 generation_scopes 设置为 ALL。例如：

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/tables/TABLE_ID"
  },
  "executionSpec": {
    "trigger": { "onDemand": {} }
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": {
    "generation_scopes": "ALL"
  }
}'

替换以下内容：

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

如需在不使用 SQL 查询的情况下生成架构、表说明和列说明，请将 generation_scopes 设置为 TABLE_AND_COLUMN_DESCRIPTIONS。例如：

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/tables/TABLE_ID"
  },
  "executionSpec": {
    "trigger": { "onDemand": {} }
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": {
    "generation_scopes": "TABLE_AND_COLUMN_DESCRIPTIONS"
  }
}'

如需生成不含说明的 SQL 查询，请将 generation_scopes 设置为 SQL_QUERIES。例如：

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/tables/TABLE_ID"
  },
  "executionSpec": {
    "trigger": { "onDemand": {} }
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": {
    "generation_scopes": "SQL_QUERIES"
  }
}'

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

例如：
```
gcurl -X POST \
https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
dataScans/DATASCAN_ID:run
```
此请求会返回唯一的作业 ID 以及初始状态。

方法 B：一次性扫描（简化版）

使用此方法可在一次 API 调用中启动并完成扫描。此方法无需单独调用 run 方法，并允许使用存留时间 (TTL) 功能自动删除扫描资源。

使用 dataScans.create 方法创建并触发扫描。例如：

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/\
    tables/TABLE_ID"
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": { "generation_scopes": "ALL" },
  "executionSpec": {
    "trigger": {
      "one_time": {
        "ttl_after_scan_completion": { "seconds": TTL_TIME }
      }
    }
  }
}'

替换以下内容：

PROJECT_ID：数据集所在的 Google Cloud项目的 ID
LOCATION：数据扫描运行的区域
DATASCAN_ID：您为此扫描提供的唯一名称
DATASET_ID：正在扫描的 BigQuery 数据集的 ID
TABLE_ID：正在扫描的 BigQuery 表的 ID
TTL_TIME：扫描资源应自动删除的持续时间（以秒为单位）（例如，3600 表示 1 小时）

查看数据文档扫描状态

使用 dataScans.get 方法检查扫描作业运行是否完成。

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

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

当状态为 SUCCEEDED 或 FAILURE 时，表示作业已完成。

将数据文档扫描结果发布到 BigQuery 表

如需将扫描结果发布到 BigQuery 表，请将以下数据文档标签附加到该表：

dataplex-data-documentation-published-scan:DATASCAN_ID
dataplex-data-documentation-published-project:PROJECT_ID
dataplex-data-documentation-published-location:LOCATION

为 BigQuery 外部表生成数据分析

BigQuery 数据洞察支持为包含 Cloud Storage 中数据的 BigQuery 外部表生成数据洞察。您和当前项目的 Dataplex Universal Catalog 服务账号必须拥有针对包含数据的 Cloud Storage 存储桶的 Storage Object Viewer 角色 (roles/storage.objectViewer)。如需了解详情，请参阅将主账号添加到存储桶级层政策中。

如需为 BigQuery 外部表生成数据分析，请按照本文档的为 BigQuery 表生成数据分析部分中的说明操作。

为 BigLake 表生成数据分析

如需为 BigLake 表生成数据分析，请按以下步骤操作：

在项目中启用 BigQuery Connection API。

启用 BigQuery Connection API
创建 BigQuery 连接。如需了解详情，请参阅管理连接。
将 Storage Object Viewer (roles/storage.objectViewer) IAM 角色授予与您创建的 BigQuery 连接对应的服务账号。

您可以从连接详细信息中检索服务账号 ID。
如需生成数据分析，请按照本文档的为 BigQuery 表生成数据分析部分中的说明操作。

生成表和列说明

当您生成数据分析洞见时，Gemini in BigQuery 会自动生成表和列说明。您可以根据需要修改这些说明，然后将其保存到表的元数据中。保存的说明用于生成未来的分析洞见。

控制生成语言

您可以引导 Gemini 以特定语言生成表和列说明。为此，请在生成数据分析洞见之前，向表的现有说明添加简短的指令（例如“使用法语生成表格和列说明”）。

生成分析洞见时，Gemini 会解读此指令，并以所请求的语言生成元数据。此机制之所以有效，是因为 Gemini 在生成新的表说明时会使用现有的表说明作为上下文。

如需查看受支持的语言列表，请参阅 Gemini 语言支持。

生成描述

如需生成表和列说明，请按照以下步骤操作：

按照本文档相关部分中的说明生成分析洞见：
点击架构标签页。
点击查看列说明。

注意：如果您没有看到查看列说明按钮，请点击描述数据。您可能需要滚动才能看到此按钮。

系统会显示生成的表说明和列说明。
如需修改并保存生成的表说明，请执行以下操作：
1. 在表说明部分中，点击保存到详细信息。
2. 如需将当前说明替换为生成的说明，请点击复制建议的说明。
3. 根据需要修改表说明，然后点击保存到详细信息。
  
  系统会立即更新表说明。
如需修改并保存生成的列说明，请执行以下操作：
1. 在列说明部分中，点击保存到架构。
  
  系统会在每个列的新说明字段中填充生成的列说明。
2. 根据需要修改列说明，然后点击保存。
  
  列说明会立即更新。
如需关闭预览面板，请点击关闭。

生成数据洞见方面的最佳实践

如需提高生成的数据洞察的准确性，请遵循以下建议：

提供全面的说明。确保数据集中的表和列都有清晰详细的说明。
使用分析结果为数据洞察建立依据。如果说明不可用，请确保将配置文件扫描与数据集中的每个表相关联，以帮助生成有根据的数据洞见。
明确定义规则。在相应表的说明中，包含信息洞察模块用于影响关系生成的任何关系或业务逻辑。

使用数据分析结果为数据洞察建立依据

在生成式 AI 中，建立依据是指将模型输出连接到可验证的信息源的能力。您可以使用数据分析结果为生成的表格数据洞察建立依据。数据分析可分析 BigQuery 表中的列，并识别常见的统计特征，例如典型数据值和数据分布。

为表创建数据分析扫描时，您可以选择将扫描结果发布到 Google Cloud 控制台中的 BigQuery 和 Dataplex Universal Catalog 页面。数据洞见会执行以下操作，以便使用数据分析结果创建更准确、更相关的查询：

分析数据分析结果，以识别数据中的有趣模式、趋势或离群值。
生成重点关注这些模式、趋势或离群值的查询以发掘数据洞察
针对数据分析结果验证生成的查询，以确保查询返回有意义的结果。

如果不使用数据分析扫描，则会发生以下情况：

生成的查询更有可能包含不准确的子句或生成无意义的结果。
生成的列说明仅基于列名称。

确保针对表的数据分析扫描是最新的，并且结果已发布到 BigQuery。

您可以调整数据分析设置，以增大采样规模并过滤出行和列。运行新的数据分析扫描后，请重新生成数据洞察。

如果数据集中的表具有数据分析结果，数据集分析洞见的质量也会显著提高。

添加表说明

详细的表说明可用于描述您想在表中分析的内容，从而帮助 Gemini in BigQuery 生成更相关的表和数据集洞见。添加表说明后，请重新生成数据洞察。

例如，您可以向 telco_churn 表（例如表数据分析示例中使用的表）添加以下说明：

This table tracks customer churn data, including subscription details, tenure,
and service usage, to predict customer churn behavior.

如果您保存 Gemini 生成的表说明，则该说明将用于生成未来的分析洞见。

添加列说明

列说明可用于说明各列的内容，或一个列与另一个列之间的关系，从而提高表格和数据集数据洞察的质量。在表中更新列说明后，请重新生成数据洞察。

例如，您可以向 telco_churn 表（例如表格数据分析示例中使用的表格）的特定列添加以下说明：

对于 tenure 列：

The number of months the customer has been with the service.

对于 churn 列：

Whether the customer has stopped using the service. TRUE indicates the customer
no longer uses the service, FALSE indicates the customer is active.

如果您保存 Gemini 生成的列说明，那么这些说明将用于生成未来的分析洞见。